@luigisbox/luma 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to `@luigisbox/luma`. Follows [semver](https://semver.org);
+before 1.0, a minor version may break the integration API.
+
+## Unreleased
+
+## 0.5.0 — 2026-10-19
+
+Upgrading from 0.4.0: read **Changed** first.
+
+### Added
+
+- `search.queryUrl` hook: the search page URL for a phrase. Use it when the
+  site's server redirects its search form (e.g. `/search?q=x` → `/search/x/`).
+  Enter, suggestions and "show all results" then go straight to that page.
+- `search.pageWhileTyping`: `'prefetch'` (default), `'prerender'` or `false`.
+  `prerenderWhileTyping: true` equals `'prerender'`.
+- `clientConfig` option `framework` (name or list): build in support for these
+  frameworks only. List every framework that renders part of a page Luma runs
+  on. Unknown names fail the build.
+- `clientConfig` option `serverRendering: false`: leave out hydration of
+  server-rendered listings.
+- `clientConfig` option `locales`: ship only these dictionaries (plus English).
+  Unknown locales or an empty list fail the build.
+
+### Changed
+
+- The build includes only widgets that have a folder (`autocomplete/`,
+  `search/`, `plp/`, `recommender <name>/`). Config for a widget without a
+  folder is ignored. A `recommender` folder without a name fails the build.
+  `yarn dev` still includes every widget.
+- These are built only if their name appears literally in a `.ts`, `.js` (or
+  variant) or `.html` file of the integration's repository, outside
+  `node_modules`, `dist` and hidden folders:
+  - attributes `data-lbx-cart`, `data-lbx-drawer`, `data-lbx-menu`,
+    `data-lbx-dropdown`
+  - hooks `onRender`, `readQuery`, `queryUrl`, `facetsFor`, `onOpen`,
+    `onClose`, `onSelect`, `onReady`
+  - options `emptyValues`, `prerenderWhileTyping` / `pageWhileTyping`,
+    `contentVisibility`
+
+  A name that only appears in a `.vue`, `.svelte` or `.hbs` file or in a
+  package does not count.
+- The search page for the typed phrase is prefetched by default. Set
+  `search.pageWhileTyping: false` to turn it off.
+- Results fetched while typing are cached per query, not per URL.
+- Enter in the search form follows the browser's implicit submission rules.
+- The `_config.ts` check (no functions) runs in development only.
+
+### Fixed
+
+- WebKit: when frames stalled, the site's listing could show instead of
+  Luma's.
+- Safari: listing images were all fetched on render, twice. Bind `src` last
+  in your own `<img>` templates too.
+- WebKit: two chunks were fetched twice per page.
+- Autocomplete: ARIA attributes could stay on the site's input after focus
+  left.
+
+## 0.4.0 — 2026-10-16
+
+### Added
+
+- Readers can return `{ reference, attributedToList: true }` for clicks and
+  add-to-carts on the site's own lists.
+
+### Fixed
+
+- Analytics: clicks and add-to-carts from Luma's widgets were never credited
+  to the search or recommendation that showed the product. They now carry
+  `attributed_to_list: true`, as does GA4 `select_item`.
+- Early hold now covers search routes with the query in the path (`urlMatch`
+  with a capture group). The snippet is unchanged.
+
+## 0.3.0 — 2026-10-15
+
+### Added
+
+- `alignTo: { field, column }` for the autocomplete panel. By default the
+  panel stays within the page's content column.
+
+### Changed
+
+- Cancelling the phone autocomplete sheet restores the site's input value.
+- Back closes an open staged filter drawer (`facetsApply`) and discards its
+  changes.
+- Reloading a listing within a minute after "show more" restores it as left.
+
+### Fixed
+
+- Phone autocomplete sheet: sized to the visible viewport, shown in
+  landscape, `autocorrect="off"`, keeps letters typed while it opens.
+- Autocomplete: lists scroll to top on new results; top product's prices
+  sit under its title.
+- iOS Safari: Back to a listing restores position and "show more" pages.
+- Listing position survives a reload or a redirect back within a minute.
+- Position is restored at the clicked link, not a hidden copy.
+- Staged drawer: Apply scrolls to the listing's top; crossing a breakpoint
+  closes the drawer.
+- A filter group opened by a selection stays open when the value is
+  unticked.
+- Range slider: touch drag on the track follows the finger; vertical scroll
+  starting on the track doesn't move a thumb.
+
+## 0.2.0 — 2026-10-13
+
+### Added
+
+- Analytics, configured in `_global/_analytics.ts`: one `collect.<event>` line
+  per event, with triggers (`lumaPages`, `lumaClicks`, `lumaCarts`, `dl`,
+  `domClick`, `urlChange`, `mutationOf`, `xhrMatching`, `manual`) and readers
+  (`fromLuma`, `fromGa4` or a function). `analytics: false` turns it off.
+- `yarn luma chrome --allow HOST`: keep that host's Luigi's Box scripts.
+
+## 0.1.0 — 2026-10-12
+
+First published version.

package/README.md

@@ -10,10 +10,10 @@ This package is what an integration is built with. Each integration lives in
 its own repository and depends on `@luigisbox/luma`
 ([Integration repository](#integration-repository)).
 
-> **Pre-release.** Until 1.0, a minor version (0.4.0) may change the
+> **Pre-release.** Until 1.0, a minor version (0.6.0) may change the
 > integration API (config keys, template scope, the build); a patch version
-> (0.3.1) only fixes. Depend on `^0.3.0` to take fixes without breaking
-> changes.
+> (0.5.1) only fixes. Depend on `^0.5.0` to take fixes without breaking
+> changes. [`CHANGELOG.md`](CHANGELOG.md) says what each version changed.
 
 ## Core principles
 
@@ -245,6 +245,51 @@ import { clientConfig } from '@luigisbox/luma/build/vite.mjs';
 export default clientConfig(import.meta.url, { plugins: [mkcert()], server: { host: 'localhost', https: {} } });
 ```
 
+`framework` names the site's frontend framework, so the build carries Luma's
+support for that framework only. Without it, every integration carries the
+support for all of them (waiting for each one's hydration, writing URLs through
+its router, keeping out of its page snapshots), and Luma tells them apart on
+each page. Declared, a listing page loads about 1.4 to 2.3 kB gzip less, and
+every page about 0.2 kB less unless React hydrates the whole document. It is
+one of the following, or a list of them:
+
+| `framework` | the site |
+|---|---|
+| `next` | Next.js (app or pages router) |
+| `remix`, `react-router` | Remix, React Router 7, Hydrogen |
+| `react` | a React app in a root element (Vite, Create React App) |
+| `vue`, `nuxt` | Vue 2 or 3, Nuxt |
+| `angular` | Angular |
+| `svelte`, `sveltekit` | a Svelte app, SvelteKit |
+| `astro` | Astro (add the framework of its islands that hold Luma's anchors) |
+| `turbo` | Turbo Drive or Turbolinks |
+| `none` | server-rendered pages: jQuery, htmx, Alpine |
+
+```ts
+export default clientConfig(import.meta.url, { framework: 'vue', plugins: [mkcert()], server: { host: 'localhost', https: {} } });
+```
+
+`serverRendering: false` declares that the site has no server-rendered
+listings (the server-side includes above): the build then leaves out adopting
+and hydrating the server's markup, about 0.9 kB gzip on a listing page. Leave
+it out when the site uses them or may; in development Luma reports
+server-rendered markup a build without them meets.
+
+`locales` lists the locales the site uses (`['cs', 'sk']`): every page then
+carries the map of those dictionaries and English only (about 20 B gzip per
+locale left out). A widget in a locale not listed reads English. Without it,
+every locale Luma has a dictionary for. A locale Luma has no dictionary for
+fails the build.
+
+List every framework that renders a part of the page Luma places into or
+navigates with, on every page Luma runs on (`['astro', 'react']` for an Astro
+site with React islands). Without its framework's support, Luma does not
+wait for that framework's hydration: React or Svelte renders the page anew,
+Vue drops Luma's element, Angular binds the wrong element, a router puts its
+own URL back. In development (`yarn dev`) Luma reports a framework the page
+uses and the build leaves out in `window.__lbx.health.errors`. An unknown name
+fails the build.
+
 Its `tsconfig.json` extends `@luigisbox/luma/tsconfig.json`, includes
 `integration/**/*` and `node_modules/@luigisbox/luma/src/**/*`, and maps `@/*`
 to `./node_modules/@luigisbox/luma/src/*`. Its `package.json` depends on
@@ -265,19 +310,31 @@ integration/
   recommender <name>/              _config.ts [_init.ts] _translations.ts
 ```
 
-- **`_config.ts` is JSON** (checked at boot); anything that needs code goes in
+- **`_config.ts` is JSON** (checked at boot in development: `yarn dev`);
+  anything that needs code goes in
   `_init.ts`. `_global/_init.ts` runs first and can change any config or return
   `false` to stop; a widget's `_init.ts` gets that widget's config. Every config
   key is typed and documented in `src/types.ts`.
+- **A widget is its folder.** The build carries only the widgets the
+  integration has folders for (`autocomplete/`, `search/`, `plp/`,
+  `recommender <name>/`) and analytics only where a folder has an
+  `_analytics.ts`: an integration with an autocomplete only loads about half
+  as much on every page as one with every widget. A config `_global/_init.ts`
+  creates for a widget without its folder is ignored. The development server
+  (`yarn dev`) carries every widget.
 - **`_init.ts` ships and runs on every page; `_widget.ts` loads with its
   widget.** Keep in `_init.ts` only what decides whether and where a widget
-  runs (`disabled`, `active`, `readQuery`, `items`, `intent`, selectors set in
+  runs (`disabled`, `active`, `readQuery`, `queryUrl`, `items`, `intent`, selectors set in
   code, switching the site's own widgets off). Hooks only a widget calls
   (`computedAttributes`, `toFilter`, `facetsFor`, `onRender`, `onOpen`, …) go
   in the folder's optional `_widget.ts`, same signature (its return value is
   ignored): it is loaded with the widget's chunk and run once before its
   context is made, `_global/_widget.ts` first. `__integration.ts` hands it
   over as a lazy glob: `widgetInits: import.meta.glob('./*/_widget.ts', { import: 'default' })`.
+  The build calls `onRender`, `readQuery`, `queryUrl`, `facetsFor` and the autocomplete's
+  `onOpen`, `onClose`, `onSelect`, `onReady` only where a file of the
+  integration's repository (a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) names them, as setting
+  them does (`config.search.onRender = …`).
 - **`style-host.css`** hides the host's own listing or suggestions, only while
   Luma has the page. Other `style-*.css` load with their widget. Luma's built-in
   CSS sits in `@layer lbx`, so the integration's and the site's CSS win.
@@ -328,7 +385,10 @@ export default ({ r, i, img, price }: SearchResultScope) => html`
 - **Helpers** in every scope: `t(key, params)`, `price(n)`, `plain()`,
   `first()`, `include()`, and `img(r, i)` (a complete `<img>` in its placeholder
   box) / `image(r, i)` (its attributes, for your own markup), configured by
-  `_global.images` (srcset, sizes, the eager first row, placeholders).
+  `_global.images` (srcset, sizes, the eager first row, placeholders). In
+  your own `<img>`, bind `src` last: Safari starts the fetch when `src` is
+  set, so a `loading` or `srcset` bound after it loads every image at once,
+  and twice.
 - **Pagination** is "show more" only: templates get `results`, `more` and
   `showMore`; there are no numbered pages.
 - **No results under filters**: the scope still holds the selected groups,
@@ -348,11 +408,17 @@ export default ({ r, i, img, price }: SearchResultScope) => html`
 ### Behaviour switches
 
 On by default unless noted; each falls back to what the page would do anyway.
+`emptyValues`, `prerenderWhileTyping` and `contentVisibility`, off by
+default, are in the build only where a file of the integration's repository
+(a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) names them, as `_config.ts` or `_init.ts` does when
+it sets them; a switch on by default that no file names is built as on.
 
 | Config | What it does | Turn it off when |
 |---|---|---|
 | `search.inPlaceQuery` | a new query on the search page renders in place, without a page load | the host's page-view analytics or server-rendered parts of the search page must follow every query |
 | `search.prefetchWhileTyping` | the search result is fetched once the typed phrase settles, so Enter shows it at once | |
+| `search.pageWhileTyping` (`'prefetch'`, `'prerender'`, `false`) | the search page of the typed phrase is fetched ahead (Chrome, Edge; Firefox and Safari as they ship it), so Enter from another page skips the site's server render; `'prerender'` renders it ahead as well (Chrome, Edge) | the site cannot take a document request per typed phrase; `'prerender'` only where its tags wait for `prerenderingchange` |
+| `search.queryUrl` (an `_init.ts` hook, off unless set) | where the site's server redirects its search form to the query's page (`/search?q=x` to `/search/x/`), names that page: Enter, the autocomplete's "show all" and a picked query load it directly, without the redirect, and the result fetched while typing is shown there | the form's other fields decide the page, or the site must handle every search itself |
 | `restoreOnBack` | Back from a product restores the listing (every page shown) and the followed tile's position, as does the page loaded again within a minute of following a link (a reload, a link whose server redirects back to it); Luma turns the browser's own scroll restoration (`history.scrollRestoration`) off for the listing's history entry until it has placed the page, unless the site set it | |
 | `prefetchNextPage` | "show more" is fetched as the shopper nears the end | |
 | `contentVisibility` (opt-in) | tiles out of view skip style, layout and paint, each at its own measured size: a long list's re-render about halves | keep it off where a tile draws outside its box (a hover panel, a badge hanging out) or holds a `position: fixed` element |
@@ -405,8 +471,8 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 | Event | What `.read()` returns |
 |---|---|
 | `pageView` | the page's reference, or `null` for a page without one. On `lumaPages()`, one pageview per page, sent at once. On any other trigger, one per page that waits for its reference from that trigger (`.timeout(ms)`, default 1000 ms) and is sent without one after that. One `pageView` line per file |
-| `click` | a product click: a reference, or `{ reference }` |
-| `addToCart` | `{ reference, count?, price? }`, or a list of them |
+| `click` | a product click: a reference, or `{ reference, attributedToList? }` |
+| `addToCart` | `{ reference, count?, price?, attributedToList? }`, or a list of them |
 | `purchase` | `{ id?, currency?, items: [{ reference, title, count, total_price, was_discounted? }] }`; sent once per `id`, so a reloaded thank-you page does not count twice |
 | `search`, `autocomplete`, `recommender(name)` | a list from the site's own service: `{ query?, items, filters? }`. Not sent on a page where Luma runs that service itself (the API records Luma's own results) |
 
@@ -416,7 +482,7 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 |---|---|---|
 | `lumaPages()` | each page: the first, the next page of a single-page app, a page restored from the back/forward cache, a prerendered page once it is shown. Filtering or sorting a Luma listing is not a new page | `{ url, referrer }` |
 | `lumaClicks()` | a click on a product in a Luma widget: any link to it, middle and modifier clicks included, and a pick in the autocomplete | `{ reference, result, index, list }` |
-| `lumaCarts()` | a click on a `[data-lbx-cart]` button in a Luma product tile (its value: the quantity). `_global.addToCart(result, { count, el, event })` adds the product to the site's cart, with or without analytics | `{ reference, result, index, list, count, price? }` |
+| `lumaCarts()` | a click on a `[data-lbx-cart]` button in a Luma product tile (its value: the quantity). `_global.addToCart(result, { count, el, event })` adds the product to the site's cart, with or without analytics. The attribute is written in a template of the integration as `data-lbx-cart`: the build includes add-to-cart only where a file of the integration's repository (a script or `.html` file, not in `node_modules`, `dist` or a hidden folder) has it | `{ reference, result, index, list, count, price? }` |
 | `dl(event)` | a dataLayer push with that event name, object or `gtag()` form, including pushes made before Luma loaded. `_global.dataLayer` in `_config.ts` names another layer | `{ event, eventType, data, ecommerce }` |
 | `domClick(selector)` | a click (or middle click) on an element of the site's that matches `selector` | `{ element, event }` |
 | `urlChange()` | a navigation in a single-page app | `{ url, previousUrl }` |
@@ -428,12 +494,26 @@ collect.purchase.on(dl('purchase')).read(fromGa4.purchase);
 
 | Reader | Reads |
 |---|---|
-| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id` |
-| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount` |
+| `fromLuma.pageView`, `.click`, `.addToCart` | what Luma's own triggers saw (`lumaPages()`, `lumaClicks()`, `lumaCarts()`). Products are referenced by their catalog `@id`. Clicks and add-to-carts are in a list (`attributedToList: true`) |
+| `fromGa4.addToCart`, `.purchase`, `.click`, `.pageView`, `.search`, `.autocomplete`, `.recommender` | GA4 ecommerce: `add_to_cart`, `purchase`, `select_item`, `view_item`, `view_item_list`. The data is taken from the push's `ecommerce` (or `gtag()`'s parameters), or from the push itself when its `items` are there. Items are referenced by `ref.product(item_id)`; purchases get line totals, and `was_discounted` from `discount`. `select_item` is a pick from a list (`attributedToList: true`); `add_to_cart` is not |
 
 Each reader belongs to one event: `collect.purchase…read(fromGa4.addToCart)`
 is a type error, and throws when the file runs.
 
+**Clicks and add-to-carts in a list.** Luigi's Box credits a click or an
+add-to-cart to the last search, suggestions, recommendation or listing the
+shopper saw the product in only when the event says it happened in a list:
+`attributedToList: true` from `.read()`, sent as `attributed_to_list: true`.
+A click without it (a bare reference) counts for the product, never for a
+list, so a click on a product page's own link is not credited to a search the
+shopper made earlier. Luma's own tiles always say it (`fromLuma.click`,
+`fromLuma.addToCart`, autocomplete picks included), and so does GA4's
+`select_item` (`fromGa4.click`). A click on the site's own list, read with a
+function of yours, says it when the element is one of that list's results:
+return `{ reference, attributedToList: true }` (below). The list itself must
+be known too: Luma's own results are; the site's own are when the setup
+collects them (`collect.search`, `.autocomplete`, `.recommender(name)`).
+
 **References** follow `<type>/<field>:<value>`
 ([docs](https://docs.luigisbox.ai/analytics/references/)).
 `ref.product(value)` uses the field set by `ref.product.by(field)` (default
@@ -473,8 +553,8 @@ collect.search.on(mutationOf('#results')).once().read(({ element }) => ({
   query: { string: new URLSearchParams(location.search).get('q') ?? '' },
   items: [...element.querySelectorAll('[data-sku]')].map((tile, n) => ({ title: tile.textContent ?? '', type: 'product', reference: ref.product(tile.getAttribute('data-sku')!), position: n + 1 })),
 }));
-// clicks on those results
-collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!));
+// clicks on those results: in that list
+collect.click.on(domClick('#results [data-sku] a')).read(({ element }) => ({ reference: ref.product(element.closest('[data-sku]')!.getAttribute('data-sku')!), attributedToList: true }));
 // the site's suggestions, from its own API
 collect.autocomplete.on(xhrMatching(({ url }) => url.includes('/suggest'))).read(({ response }) => ({ items: /* … */ [] }));
 // the product page's product, from GA4's view_item
@@ -508,7 +588,8 @@ integration repository").
   add-to-carts on Luma's products and dataLayer pushes are kept for the next
   page. A/B tests are not supported yet (`listing_ab_test` is always `false`).
 - **Prerendering** costs the site a page render per unfollowed hover
-  (`speculation: false` turns it off).
+  (`speculation: false` turns it off), and the search page fetched ahead
+  while typing a document per settled phrase (`search.pageWhileTyping: false`).
 - **Early hold**: the snippet carries no site's rules, so the first page
   view is not held.
 - **Host routers out of reach**: where Luma cannot find the host's router (Vue

package/build/baseline.mjs

@@ -53,8 +53,8 @@ export const ALLOW = [
   {
     // Limited availability (Chromium only). document.prerendering through `any`, as above.
     feature: 'speculation-rules',
-    files: ['src/core/speculation.ts', 'src/core/takeover.ts', 'src/main.ts'],
-    why: "The prerender rule is added only when HTMLScriptElement.supports('speculationrules'); document.prerendering is undefined (falsy) elsewhere, so a hold's timer starts at once.",
+    files: ['src/core/speculation.ts', 'src/core/takeover.ts', 'src/main.ts', 'src/widgets/search/speculate.ts'],
+    why: "The product-page prerender rule, and the search page of the phrase typed fetched ahead (prerendered with pageWhileTyping 'prerender'), are added only when HTMLScriptElement.supports('speculationrules'); without it Enter loads the page as usual and its result comes from the stash. document.prerendering is undefined (falsy) elsewhere, so a hold's timer starts at once.",
   },
 ];