copilot instructions

Author: stefanseifert

.github/copilot-instructions.md

@@ -0,0 +1,96 @@
+# adaptTo() Website – Copilot Instructions
+
+adaptTo() conference website built on **Adobe Edge Delivery Services (EDS / AEM Franklin)**.
+Content is authored in Microsoft SharePoint/Google Docs and served as semantic HTML, then
+progressively enhanced client-side by vanilla ES modules. There is **no build step** and **no
+framework** – plain JavaScript (ES modules), CSS, and the AEM `aem.js` library.
+
+## Big picture
+
+- **Authors** edit documents (one document = one page) and spreadsheets (`.xlsx`). EDS publishes
+  them as HTML pages plus JSON endpoints (`query-index.json`, yearly `schedule-data.json`).
+- **The browser** loads a page, and `scripts/scripts.js` decorates the DOM: it builds sections,
+  auto-blocks, and loads block JS/CSS on demand.
+- **Blocks** (`blocks/<name>/<name>.js` + `.css`) are the UI components. Each exports a default
+  `decorate(block)` function that transforms its DOM subtree and may fetch data.
+- **Services** (`scripts/services/`) encapsulate all **business logic / data access** – reading the
+  query index and schedule sheets, resolving speakers/talks, filtering the archive. Blocks should
+  delegate data work to services, not reimplement it.
+- **Utils** (`scripts/utils/`) are small stateless helpers (DOM, dates, paths, metadata parsing).
+
+```
+content (Docs + Sheets)
+   │  published by EDS
+   ▼
+query-index.json / schedule-data.json / HTML pages
+   │  fetched by
+   ▼
+scripts/services/*  ──►  blocks/*/*.js  ──►  decorated DOM
+   ▲                         ▲
+   └── scripts/utils/* ──────┘
+```
+
+## Yearly editions & content model
+
+- The site hosts one edition per year. **URL convention is the source of truth**:
+  - `/<year>/` – site root of an edition (e.g. `/2024/`), matched by `/^\/\d\d\d\d\/$/`.
+  - `/<year>/schedule/<talk>` – a main talk detail page.
+  - `/<year>/schedule/<talk>/<lightning>` – a lightning talk (one level deeper).
+  - `/speakers/<name>` – speaker pages, which live **outside** the yearly tree and are shared
+    across editions. Use a `#<year>` hash to bind a speaker page to an edition.
+- Speaker metadata can change over the years; `uptoyear` and `speaker-alias` fields let a speaker
+  have multiple variants. Resolution logic lives in `QueryIndex` (see services instructions).
+- Page behaviour is driven by **metadata** (`getMetadata(name)` from `aem.js`): `template`,
+  `theme`, `include-aside-bar`, `include-teaser-bar`, `affiliation`, `video`, `article:tag`, etc.
+- Pre-2024 editions use a legacy design: `loadEager` adds the `design-2023` body class and loads
+  `styles/styles-design-2023.css` when `getYearFromPath(...) < 2024`.
+
+## Page lifecycle (`scripts/scripts.js`)
+
+Three phases, mirroring the EDS pattern:
+1. **`loadEager`** – language, legacy-design detection, fullscreen handling, static header,
+   template/theme auto-detection, `decorateMain`, render first section (LCP).
+2. **`loadLazy`** – header/footer, remaining sections, hash scroll, lazy CSS, consent management.
+3. **`loadDelayed`** – everything deferrable (loaded after 3s via `delayed.js`).
+
+`decorateMain` runs `buildAutoBlocks`, which **synthesises blocks** based on page type:
+- Speaker pages → `speaker-detail` block (see `isSpeakerDetailPath`).
+- `theme === 'talk-detail'` pages → inserts `talk-detail-before-outline`,
+  `talk-detail-after-outline`, `talk-detail-footer`, and relocates `talk-qa`.
+- Always extracts a `stage-header` section and appends `teaser-bar` / `aside-bar` fragments unless
+  disabled via metadata.
+
+When adding page-type behaviour, prefer extending `buildAutoBlocks` + a dedicated block over
+inlining logic in `scripts.js`.
+
+## Conventions
+
+- **ES modules only.** Imports must include the `.js` extension (enforced by ESLint
+  `import/extensions`). Unix linebreaks. Style is `airbnb-base`.
+- **Build DOM with `scripts/utils/dom.js`** (`append`, `prepend`) instead of verbose
+  `createElement` + `append` chains. Use the `html` tagged template (`utils/htmlTemplateTag.js`)
+  for larger markup – it auto-escapes interpolations (prefix with `$` to opt out).
+- **All fetches go through `utils/fetch.js`** cache helpers so a browser reload force-refreshes data.
+- **Never hardcode `/2024/` style paths.** Derive them with `utils/site.js` / `utils/path.js`
+  helpers (`getSiteRootPath`, `getYearFromPath`, `getSchedulePath`, …).
+- Use JSDoc with `@typedef`/`@param`/`@returns`; the codebase is typed via JSDoc, not TypeScript.
+- Keep data/business logic in `scripts/services/`; keep blocks focused on presentation.
+
+## Developer workflow
+
+```sh
+npm install
+npm test          # web-test-runner, files: test/**/*.test.js (with coverage)
+npm run test:watch
+npm run lint      # lint:js (eslint) + lint:css (stylelint)
+```
+
+Local preview uses the AEM CLI: `npm install -g @adobe/aem-cli` then `aem up` (serves at
+`http://localhost:3000`). CI runs build + tests and reports coverage to SonarCloud.
+
+## Where to look
+
+- Architecture / page lifecycle → `scripts/scripts.js`, this file.
+- **Talk & speaker data model and business logic** → `.github/instructions/data-services.instructions.md`.
+- Authoring blocks and how they consume data → `.github/instructions/blocks.instructions.md`.
+- Tests → `.github/instructions/testing.instructions.md`.

.github/instructions/blocks.instructions.md

@@ -0,0 +1,84 @@
+---
+applyTo: "blocks/**"
+---
+
+# Blocks – authoring & consuming data
+
+Blocks are the UI components of the site. Each block is a folder `blocks/<name>/` containing
+`<name>.js` and `<name>.css`. EDS loads a block's JS/CSS lazily when the block appears on a page.
+
+## Anatomy
+
+```js
+import { getQueryIndex } from '../../scripts/services/QueryIndex.js';
+import { append } from '../../scripts/utils/dom.js';
+
+/**
+ * @param {Element} block The block's root element
+ */
+export default async function decorate(block) {
+  // transform block's DOM subtree in place
+}
+```
+
+- Export a **default `decorate(block)`** function. It may be `async`.
+- It receives the block's root element (already in the DOM) and mutates that subtree.
+- Authored content arrives as nested `div` rows/cells; read it, then usually replace it
+  (`block.textContent = ''` / `block.innerHTML = ...`) with the final markup.
+- Read block configuration (key/value rows) with `readBlockConfig(block)` from `aem.js`
+  (e.g. `speaker-gallery` reads a `speakers` list this way).
+
+## Data flow: always go through services
+
+Blocks must get talk/speaker/schedule data from `scripts/services/`, never by fetching or parsing
+JSON directly. Typical patterns:
+
+- **Query index**: `const queryIndex = await getQueryIndex();` then use methods like
+  `getItem`, `getSpeaker`, `getTalksForSpeaker`, `getTalkSpeakerNames`,
+  `getLightningTalkSpeakerNames` (see the data-services instructions).
+- **Schedule**: `const data = await getScheduleData(\`${siteRoot}schedule-data.json\`, forceReload);`
+  then `data.getDays()` / `data.getTalkEntry(path)`.
+- **Archive**: `const archive = await getTalkArchive();` then `applyFilter` + `getFilteredTalks*`.
+
+Resolve paths/years with `utils/site.js` and `utils/path.js`
+(`getSiteRootPath`, `getSiteRootPathAlsoForSpeakerPath`, `getYearFromPath`,
+`getSpeakerDetailPath`, `getArchivePath`, …). **Never hardcode a year or path.**
+
+### Speaker rendering rules (when building speaker UI)
+
+- Resolve a speaker for the current edition with `queryIndex.getSpeaker(name, siteRoot)` so the
+  correct yearly variant (`uptoyear`) is chosen.
+- Link to a speaker detail page using `getSpeakerDetailPath(speakerItem, siteRoot)` — it appends
+  the `#<year>` hash that binds the shared speaker page to the edition.
+- Use `createOptimizedPicture` (from `aem.js`) for speaker images; fall back to
+  `/resources/img/speaker_placeholder.svg` when `speakerItem.image` is absent.
+- Use eager image loading only for the first few speakers (see `speaker-gallery`).
+
+### Schedule / talk-detail rules
+
+- Talk detail pages are driven by metadata (`theme: talk-detail`); the auto-blocks in
+  `scripts.js` inject `talk-detail-before-outline`, `talk-detail-after-outline`,
+  `talk-detail-footer`. Add talk-detail UI by editing those blocks.
+- Get a talk's time/duration via `scheduleData.getTalkEntry(document.location.pathname)`.
+- The `schedule` block owns parallel-track grouping (`buildGroupedEntries`) and day-tab
+  navigation; active day comes from the `#day-<n>` hash or today's date.
+
+## Markup & DOM conventions
+
+- Build elements with `append`/`prepend` from `utils/dom.js` (the optional rest args are class
+  names) rather than manual `createElement` chains.
+- For larger fragments use the `html` tagged template (`utils/htmlTemplateTag.js`): interpolations
+  are **HTML-escaped by default**; prefix the placeholder with `$` only for trusted pre-escaped
+  content.
+- React to in-page edition/day/filter changes via the `hashchange` event (several blocks reload or
+  re-render on hash change).
+- Keep imports extension-explicit (`../../scripts/...js`) — ESLint enforces it.
+- Styling belongs in the block's own `.css`; class names are scoped under the block root.
+
+## Adding a new block
+
+1. Create `blocks/<name>/<name>.js` (default `decorate`) and `blocks/<name>/<name>.css`.
+2. Put any data/domain logic in a service under `scripts/services/`, not in the block.
+3. If the block should be auto-injected for a page type, wire it into `buildAutoBlocks`
+   in `scripts/scripts.js`.
+4. Add a test under `test/blocks/<name>/` using the test harness.

.github/instructions/data-services.instructions.md

@@ -0,0 +1,116 @@
+---
+applyTo: "scripts/services/**/*.js"
+---
+
+# Talk & speaker data – business logic
+
+All data access and domain logic lives in `scripts/services/`. Blocks consume these services and
+should **not** parse the raw JSON themselves. There are two data sources, both published by EDS:
+
+- **`/query-index.json`** – flat list of every published page with its metadata (one row per page).
+- **`/<year>/schedule-data.json`** – per-edition spreadsheet export describing the timetable.
+
+## Query index (`QueryIndex.js`, `QueryIndexItem.js`)
+
+`getQueryIndex()` fetches `/query-index.json` once and **caches the promise** (singleton). Tests
+reset it with `clearQueryIndexCache()`. Each raw row is mapped onto a `QueryIndexItem`
+(`Object.assign(new QueryIndexItem(), row)`), and the placeholder `default-meta-image.png` is
+nulled out.
+
+`QueryIndexItem` is the canonical page/metadata record. Fields are strings as stored; helper
+methods parse them:
+- `getKeywords()` / `getRobots()` → `parseCSVArray` (comma-separated).
+- `getTags()` → `parseJsonArray` (JSON array, falls back to CSV).
+- `getSpeakers()` → `parseCSVArray` of the `speakers` field.
+
+Speaker-specific fields: `affiliation`, `twitter`, `speaker-alias`, `uptoyear`.
+Talk-specific field: `speakers` (speaker **names** or speaker **document-names**).
+
+### Page-type detection is path-based
+
+`QueryIndex` classifies items purely by their `path` using regexes:
+- site root: `/^\/\d\d\d\d\/$/`
+- speaker page: `/^\/speakers\/.*$/`
+- talk page: `/^\/\d\d\d\d\/schedule\/.+$/`
+
+Key methods:
+- `getItem(path)` – exact path lookup.
+- `getAllSiteRoots()` – yearly editions, newest first.
+- `getAllTalks()` – all talk pages, sorted year-desc then title-asc.
+- `getTalkSpeakerNames(siteRoot)` – distinct sorted speakers of **main** talks (`schedule/<x>`).
+- `getLightningTalkSpeakerNames(siteRoot)` – speakers of **lightning** talks
+  (`schedule/<x>/<y>`), **minus** anyone already in the main-talk list.
+- `getTalksForSpeaker(speakerItem)` – talks whose `speakers` include the speaker's title or
+  document-name.
+
+### Speaker variant resolution (important domain rule)
+
+A speaker can appear at the same name across years with different affiliation/details.
+`getSpeaker(pathOrName, siteRootPath)`:
+1. If given a URL/path under `/speakers/`, returns that exact item.
+2. Otherwise matches speaker items whose `title` **or** document-name equals the input.
+3. Disambiguates multiple matches via `getMatchingSpeakerVariant`: sorts by `uptoyear` (items
+   **without** `uptoyear` sort last = "current"), and picks the first variant whose `uptoyear`
+   is absent or `>= requested year`.
+
+When you need the right speaker for a given edition, always pass the `siteRootPath` so this logic
+applies — don't pick the first match yourself.
+
+## Schedule data (`ScheduleData.js`, `ScheduleDay.js`, `ScheduleEntry.js`)
+
+`getScheduleData(url, forceReload)` fetches a yearly `schedule-data.json` and **joins it with the
+query index** to produce `ScheduleDay[]` → `ScheduleEntry[]`.
+
+Spreadsheet columns → `ScheduleEntry`: `Day`, `Track`, `Start`, `End`, `Entry` (title),
+`Duration`, `FAQ` (Q&A minutes), `Type`, `Speakers`.
+- Valid `Type`s: `day`, `talk`, `break`, `other`, `other_rating`. `day` rows are dropped from
+  entries (only used implicitly).
+- `Start`/`End` are Excel/Sheets serial numbers → real `Date`s via
+  `convertSheetDateValue` (UTC). Times are formatted UTC (`utils/datetime.js`).
+- A row is **invalid and skipped** if day/start/end/title/duration are missing/zero or the type is
+  not recognised.
+
+### Talk rows resolve against the query index
+
+For `Type === 'talk'`, the `Entry` value is a reference to the talk detail page:
+- absolute URL/path → used directly; otherwise treated as a document-name under
+  `/<year>/schedule/<ref>`.
+- If no matching query-index item exists, **the entry is dropped**.
+- The entry's `title` is taken from the index item (with `removeTitleSuffix`), and if the sheet
+  has no `Speakers`, speakers are inherited from the index item.
+
+`ScheduleData.getTalkEntry(path)` finds the entry for a talk detail page (used by talk-detail
+blocks to show time/duration).
+
+`ScheduleDay` aggregates its entries' min `start` / max `end`. Parallel tracks are represented by
+the `track` number (track 1..n share a start time); grouping into parallel rows is done in the
+`schedule` block, not here.
+
+## Talk archive (`TalkArchive*.js`)
+
+`getTalkArchive()` builds a `TalkArchive` from the query index. It projects talks into lightweight
+`TalkArchiveItem`s (arrays already parsed) and **drops talks with no speakers**.
+
+- `TalkArchiveFilter` – `tags` / `years` / `speakers` (AND across categories, OR within a
+  category). Serialised to/from the URL hash via `buildHash()` / `getFilterFromHash(hash)` using
+  `category=val1,val2/...`. Only `tags`, `years`, `speakers` are valid categories.
+- `TalkArchive.applyFilter(filter)` recomputes `filteredTalks` and invalidates the full-text index.
+- `getFilteredTalksFullTextSearch(text)` lazily builds a `TalkArchiveFullTextIndex` over the
+  currently filtered talks. The index is deliberately simplistic: it concatenates
+  title/description/keywords/tags/speakers, lowercases, and does substring matching.
+- Filter option lists: `getTagFilterOptions()` / `getSpeakerFilterOptions()` (asc),
+  `getYearFilterOptions()` (desc) — all distinct & sorted.
+
+## Link handling (`Link.js`, `LinkHandler.js`)
+
+`rewriteUrl` / `decorateAnchor` strip the host from internal adaptTo() URLs (so preview links stay
+on preview and live stays on live), open external links in a new tab, and mark `.pdf`/`.zip` links
+as downloads. `decorateAnchors(container)` is applied during `decorateMain`.
+
+## When extending the data layer
+
+- Add new domain logic here as a service/method with JSDoc, not inline in a block.
+- Reuse `utils/path.js` (`isUrlOrPath`, `getPathName`, `getDocumentName`, `getYearFromPath`) and
+  `utils/metadata.js` (`parseCSVArray`, `parseJsonArray`, `removeTitleSuffix`) rather than new regexes.
+- Fetch via `utils/fetch.js` cache helpers.
+- Add a matching test under `test/scripts/services/` with sample JSON in `test/test-data/`.

.github/instructions/testing.instructions.md

@@ -0,0 +1,43 @@
+---
+applyTo: "test/**"
+---
+
+# Tests
+
+Tests run with **@web/test-runner** in a real browser, using Chai (`@esm-bundle/chai`) and Sinon.
+
+```sh
+npm test            # all test/**/*.test.js with coverage
+npm run test:watch
+```
+
+## Layout
+
+- `test/scripts/services/` – unit tests for the data/business-logic services.
+- `test/blocks/<name>/` – block tests (decorate a fixture DOM, assert resulting markup).
+- `test/test-data/` – sample fixtures: `query-index-*.json`, `schedule-data-*.json` (+ source
+  `.xlsx`), images.
+- `test/scripts/test-utils.js` – shared helpers.
+
+## Conventions & helpers
+
+- Files are ES modules and use the global `describe`/`it` (declared via
+  `/* global describe it */`). Import `expect` from `@esm-bundle/chai`.
+- **Stub network with `stubFetchUrlMap(map)`** from `test-utils.js` — it redirects requested URLs
+  (e.g. `/query-index.json`) to a local fixture under `test/test-data/`. Example:
+  ```js
+  stubFetchUrlMap({ '/query-index.json': '/test/test-data/query-index-sample.json' });
+  ```
+- The query index is a cached singleton: call `clearQueryIndexCache()` when a test needs fresh
+  data with a different stub.
+- Control the current URL with `setWindowLocationHref(href)` (path-based logic depends on
+  `window.location`).
+- Wait for async EDS loading with `sectionLoaded` / `blockLoaded`; use `sleep(ms)` sparingly.
+
+## When changing behaviour
+
+- Add/adjust a fixture in `test/test-data/` and a test mirroring the source file's location
+  (a service in `scripts/services/Foo.js` → `test/scripts/services/Foo.test.js`).
+- Prefer asserting domain outcomes (resolved speaker variant, dropped invalid schedule rows,
+  filter/full-text results) over incidental markup details.
+- Run `npm test` and `npm run lint` before finishing.