@escape-game-over/atlas 0.1.76 → 0.1.77

package/docs/client-scripts.md

@@ -36,7 +36,7 @@ finding them.
 | ------------------ | -------------------------------------------------------------- | ----------------------------------------------- |
 | `carousel`         | which slide is current: modulo, swipe, autoplay, the move lock | the transform, dots, arrows, `aria`             |
 | `filters`          | which items match, and what the address bar says               | every DOM read and write                        |
-| `filters-view`     | the two DOM writes every filtered list turned out to share     | finding the elements, and everything else drawn |
+| `filters-view`     | the DOM writes every filtered list turned out to share         | finding the elements, and everything else drawn |
 | `youtube`          | the swap from poster to player, on the click and not before    | the poster, the button, the iframe's classes    |
 | `background-video` | playing or paused, playable or not, and which cut is loaded    | the play/pause control, its icons and its label |
 | `consent`          | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law  |
@@ -249,11 +249,12 @@ re-clicking the current tab does not add a history step to walk back through.
 
 ## `filters-view`
 
-Two helpers, and the bar for being here is not "a list might want this" but
+Three helpers, and the bar for being here is not "a list might want this" but
 "every list we have already written did, character for character, and getting it
 wrong was silent". Three filtered lists in one consuming project — a catalogue, a
-location directory and an FAQ — agree on exactly these and disagree about
-everything else they draw.
+location directory and an FAQ — agree on `searchBox` and `hideEmpty` and
+disagree about everything else they draw; `filtering` was copied between two
+sites before it came here.
 
 ### `searchBox`
 
@@ -334,6 +335,49 @@ recorded as behaviour rather than only as prose.
 A group with no children at all is hidden, by the same rule: there is nothing
 visible in it.
 
+### `filtering`
+
+A chip that narrows a grid in place, animated: what stays slides to its new
+place, what leaves or arrives fades. It wraps the `set` or `reset` the chip does
+in a view transition, and runs it plainly where the API is missing.
+
+```ts
+const items = refs(root, "[data-filter-item]");
+chip.addEventListener(
+    "click",
+    () => filtering(items, () => list.set("category", data(chip, "category"))),
+    { signal }
+);
+```
+
+Every item needs its own view-transition name for the move to animate, and
+`match-element` gives each one without the page minting ids. **Only while it
+runs**: named for good, every card would also pair up across page navigations,
+and one with no partner on the next page would linger over it. So the helper
+writes the name inline, and puts back whatever inline name the item had when
+the last transition ends.
+
+**The last, not each.** A second click skips the first transition, and the
+first one's end would otherwise strip the names out from under the one still
+running, which then animates nothing. The helper counts. `tests/filtering.test.ts`
+pins the overlap, including an item that had a name of its own.
+
+**One rule stays the project's.** A site that stops unpaired names animating
+across pages also stops filtering's fades, since a card hidden or shown has no
+partner either. The helper marks `<html>` with `data-atlas-filtering`
+(`FILTERING_ATTRIBUTE`) while it runs, for the site to scope that rule out:
+
+```css
+:root:not([data-atlas-filtering])::view-transition-new(*):only-child {
+    animation: none;
+}
+:root:not([data-atlas-filtering])::view-transition-old(*):only-child {
+    display: none;
+}
+```
+
+A site without such a rule needs no CSS at all.
+
 ### Why these write instead of calling back
 
 `filters.onChange` is already the callback that hands a consumer the answer and
@@ -632,6 +676,9 @@ right properties is a faithful stand-in.
   pins the write-back guard by counting *writes* — so deleting the guard fails
   rather than passing on an identical value — and pins the nesting order in
   both directions.
+- `tests/filtering.test.ts` stubs `document` with a `startViewTransition` whose
+  transitions finish when the test says, so two overlapping runs can be ended
+  in order.
 - `tests/youtube.test.ts` fakes the trigger, and a container whose
   `ownerDocument` makes the iframe — which is why the module reaches the
   document through the container rather than the global.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.76",
+    "version": "0.1.77",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/filters-view.ts

@@ -1,14 +1,15 @@
 /**
- * The two DOM writes every filtered list turned out to share.
+ * The DOM writes every filtered list turned out to share.
  *
  * `filters` decides which items match; what a page does about that is its own.
- * These are the parts three lists wrote identically, and getting wrong was
- * silent. Both take elements, never selectors, so no attribute name in this
+ * These are the parts the lists wrote identically, and getting wrong was
+ * silent. All take elements, never selectors, so no attribute name in this
  * package has to be matched by a consumer.
  *
- * They write only what is binary and derived — an input's `value`, and `hidden`
- * on a clear button, an empty message or a section with nothing left. No class,
- * style or `aria`: that is where the choices live.
+ * They write only what is binary and derived — an input's `value`, `hidden` on
+ * a clear button, an empty message or a section with nothing left, and a
+ * view-transition name while a filter animates. No class or `aria`: that is
+ * where the choices live.
  *
  * **`hidden` needs help in a grid.** Any author rule setting `display` beats it.
  * Tailwind v4's preflight ships `[hidden] { display: none !important }`; without
@@ -124,3 +125,73 @@ export function hideEmpty<T extends HTMLElement>(
         group.hidden = !visible;
     }
 }
+
+/**
+ * On `<html>` while a `filtering` transition runs: what a stylesheet that
+ * treats unpaired view-transition names one way across pages tells the two
+ * cases apart by.
+ */
+export const FILTERING_ATTRIBUTE = "data-atlas-filtering";
+
+/** Each named item, and the inline name it had before, to put back after. */
+const named = new Map<HTMLElement, string>();
+let running = 0;
+
+/**
+ * Runs `update` — the `set` or `reset` a chip or tab does — as a view
+ * transition, so what stays slides into place and what leaves or arrives
+ * fades. Without the API, `update` just runs.
+ *
+ * ```ts
+ * chip.addEventListener("click", () =>
+ *     filtering(items, () => list.set("category", data(chip, "category")))
+ * );
+ * ```
+ *
+ * **`items` are named only while it runs**, `match-element` each, and put
+ * back after. Named for good, every one of them would be a pair across pages
+ * too, and linger over the next page on navigation.
+ *
+ * **Counted, not just started**: a second click skips the first transition,
+ * and that one's end would otherwise strip the names from the one still
+ * running.
+ *
+ * **One rule is the project's**, because only the project knows it wrote the
+ * other half. A site that stops unpaired names animating across pages — so a
+ * card on one page does not fade over the next — stops filtering's fades with
+ * it, since an item hidden or shown is unpaired too. Scope it out:
+ *
+ * ```css
+ * :root:not([data-atlas-filtering])::view-transition-new(*):only-child {
+ *     animation: none;
+ * }
+ * ```
+ */
+export function filtering(
+    items: Iterable<HTMLElement>,
+    update: () => void
+): void {
+    const doc = globalThis.document;
+    if (typeof doc?.startViewTransition !== "function") {
+        update();
+        return;
+    }
+
+    for (const item of items) {
+        if (!named.has(item)) named.set(item, item.style.viewTransitionName);
+        item.style.viewTransitionName = "match-element";
+    }
+
+    const root = doc.documentElement;
+    running += 1;
+    root.setAttribute(FILTERING_ATTRIBUTE, "");
+    doc.startViewTransition(update).finished.finally(() => {
+        running -= 1;
+        if (running > 0) return;
+        root.removeAttribute(FILTERING_ATTRIBUTE);
+        for (const [item, before] of named) {
+            item.style.viewTransitionName = before;
+        }
+        named.clear();
+    });
+}