@escape-game-over/atlas 0.1.25 → 0.1.27

package/docs/client-scripts.md

@@ -73,15 +73,15 @@ runs when the element enters the page, `signal` ends what it registered when the
 element leaves, and what it returns is the undo for everything else.
 
 ```ts
-export const thing = element("go-thing", { button: marker }, (host, { button }, signal) => {
-    button.one()?.addEventListener("click", open, { signal });   // ends with the visit
-    return loop.attach(host);                                     // and so does this
+export const thing = element("go-thing", ({ root, signal }) => {
+    ref(root, "[data-thing-button]").addEventListener("click", open, { signal });   // ends with the visit
+    return loop.attach(root);                                                        // and so does this
 });
 ```
 
 An element can enter the page more than once — moving it in the DOM runs the
 undo and then the function again — so it has to be able to run twice. State that
-must survive a move goes in a `WeakMap` keyed by `host`, which is what the
+must survive a move goes in a `WeakMap` keyed by `root`, which is what the
 carousel example does with its index.
 
 **The trap this exists for is view transitions.** A bundled `<script src>` is an
@@ -98,50 +98,46 @@ handled. Without a re-`attach` there is simply nothing wired.
 ## `filters`
 
 A list already rendered by the server, narrowed in the browser and mirrored in
-the URL. The caller declares fields; the item shape follows from them.
+the URL. The caller declares fields and hands over its own items — elements,
+records, whatever it holds — with how to read each one's values.
 
 ```ts
 const list = filters({
-    fields: {
-        q:        { kind: "text" },
-        category: { kind: "choice" },
-        featured: { kind: "flag" },
+    fields: { q: "text", category: "choice", featured: "flag" },
+    items: rows,
+    values: (row) => ({
+        q: data(row, "text"),
+        category: data(row, "category"),
+        featured: row.hasAttribute("data-featured"),
+    }),
+    onChange: ({ matched }) => {
+        for (const row of rows) row.hidden = !matched.has(row);
     },
-    items: entries.map((entry) => ({
-        key: entry.id,
-        values: {
-            q: `${entry.title} ${entry.summary}`,
-            category: entry.category,
-            featured: entry.featured,
-        },
-    })),
-    onChange: ({ matched, state }) => { /* the project's DOM writes, all of them */ },
 });
 
 const detach = list.attach();
 ```
 
-Fields are plain data rather than `text()` / `choice()` / `flag()` builders:
-three exported names that general — `text` above all — in a module a project
-imports by name, to return exactly this object. `values` is typed *from*
+A field is its kind, and its URL parameter is its own name — to rename the
+parameter, rename the field. `{ kind: "text", url: false }` keeps a field out of
+the URL, for a list whose page owns the URL itself. `values` is typed *from*
 `fields`, so a `flag` demands a boolean and a mismatch is a compile error rather
-than an item that silently never matches.
+than an item that silently never matches. It is read once per item, at
+construction. `matched` is a set of the caller's own items, so there is no key
+to invent, carry in the markup and map back.
 
 | Kind     | State           | Item value      | Matches when                                     | In the URL                      | History |
 | -------- | --------------- | --------------- | ------------------------------------------------ | ------------------------------- | ------- |
 | `text`   | the query       | searchable text | every folded query word appears; empty keeps all | `?q=…`, dropped if empty        | replace |
 | `choice` | one value, `""` | one, or several | the item holds the chosen one; `""` keeps all    | `?category=…`, dropped if empty | push    |
-| `flag`   | boolean         | boolean         | off keeps all; on keeps only items that carry it | `?featured=1`, absent when off  | push    |
+| `flag`   | boolean         | boolean         | off keeps all; on keeps only items that carry it | `?featured`, absent when off    | push    |
 
 **A `choice` item may hold several values.** The state stays one — the tab strip
 picks one category, the URL carries one — but an item can sit in more than one
 and then answers to any of them:
 
 ```ts
-items: [
-    { key: "burgos", values: { category: "city" } },
-    { key: "avila",  values: { category: ["walk", "city"] } },
-]
+values: (room) => ({ category: data(room, "categories").split(" ") }),
 ```
 
 An escape room is adventure *and* sci-fi; a film is a comedy *and* a drama. This
@@ -175,8 +171,6 @@ pass. What is deliberately absent is one field holding several selected values;
 that is a `choices` kind, and it forces a URL encoding decision (repeated
 parameters or comma-joined) that nothing has needed yet.
 
-`param` defaults to the field's name. `param: false` keeps a field state-only, out of the URL.
-
 ### Facet counts: `matchedWithout`
 
 A dropdown that says how many results each option would give needs a different
@@ -191,7 +185,7 @@ onChange({ matched }) {
     for (const option of countryOptions) {
         const value = option.dataset.choice;
         const count = rows.filter(
-            (row) => rest.has(row.key) && row.country === value
+            (row) => rest.has(row) && row.country === value
         ).length;
         // …the project writes `count` wherever its design puts it
     }
@@ -236,21 +230,12 @@ instead of flashing the whole list back. Nothing writes to the URL before
 `attach`, because `attach` is what reads it — a `set` on an unattached instance
 would overwrite state nobody had loaded.
 
-A set flag is written `1` and an unset one is **absent** rather than `=0`. One
-spelling for off keeps the URL short and leaves a single form to parse; the cost
-is that a hand-written `?featured=0` reads as off, which is the answer it would have
-got anyway. `1` and not `true` because that is what the existing lists already
-emit, and links people have shared should keep resolving to the view they named.
-
-### Two things it refuses at construction
-
-Both are silent otherwise:
+A flag is on by being there, as an HTML boolean attribute is: written as the bare
+`?featured`, and **absent** when off. Reading asks only whether the name is
+present, so `?featured=1` from an older link still reads as on — and so does a
+hand-written `?featured=false`, just as `hidden="false"` still hides.
 
-- **Two items under one key.** `matched` could not say which of them matched.
-- **Two fields on one URL parameter.** Each write erases the other's value, which
-  reads as a filter that will not stay set.
-
-And a `set` to the value already held announces nothing and pushes nothing, so
+A `set` to the value already held announces nothing and pushes nothing, so
 re-clicking the current tab does not add a history step to walk back through.
 
 ## `filters-view`
@@ -275,9 +260,9 @@ const list = filters({
 });
 const detach = list.attach();
 const unbind = searchBox(list, "q", {
-    input: one<HTMLInputElement>("[data-filter-search]"),
-    clear: one("[data-filter-clear]"),
-    empty: one("[data-filter-empty]"),
+    input: ref<HTMLInputElement>(root, "[data-filter-search]"),
+    clear: ref(root, "[data-filter-clear]"),
+    empty: ref(root, "[data-filter-empty]"),
 });
 ```
 
@@ -363,96 +348,70 @@ skips the helper and writes it in `onChange`. Nothing degrades.
 
 ## `element`
 
-A script that enhances server-rendered markup has to agree with the template on
-attribute names, and nothing checks that agreement. `data-filter-regoin` in the
-template and `dataset.filterRegion` in the script compile, build and ship, and
-the facet simply never matches. `element` names every attribute a script and its
-template share, types the values in them, and registers the behaviour.
+A custom element that enhances server-rendered markup: `element` registers the
+behaviour and runs it for as long as the element is on the page, and `ref` and
+`refs` find what it works on by plain attribute selectors.
 
 ```ts
-// faq.ts — imported by the template, and loaded by the page's script
-export const faq = element("go-faq", {
-    row: { key: { kind: "text" }, status: { kind: "choice", of: ["open", "soon"] } },
-    search: marker,
-}, (host, { row, search }, signal) => {
-    for (const { element, values } of row.all()) {
-        values.status; // "open" | "soon"
+// faq.ts — imported by the template for the tag, and loaded by the page's script
+export const faq = element("go-faq", ({ root, signal }) => {
+    const input = ref<HTMLInputElement>(root, "[data-faq-search]");
+    for (const row of refs<HTMLDetailsElement>(root, "[data-faq-row]")) {
+        row.dataset.key;
     }
-    const input = search.one<HTMLInputElement>(); // a marker role is the element itself
 });
 ```
 
 ```astro
+---
+import AtlasElement from "@escape-game-over/atlas/astro/element";
+---
+
 <script src="./faq.ts"></script>
 
-<go-faq {...faq.root}>
-    <input {...faq.search.attrs()} type="search">
-    <details {...faq.row.attrs({ key, status: "open" })}>…</details>
-</go-faq>
+<AtlasElement of={faq} class="…">
+    <input data-faq-search type="search">
+    <details data-faq-row data-key={key}>…</details>
+</AtlasElement>
 ```
 
 It registers itself when loaded in a browser and does nothing in Node, so the
-template imports the same file for the contract.
-
-- **Names are derived, never spelled.** `data-network-row` marks the element and
-  `data-network-row-status` holds a field. A field that does not exist is a
-  compile error in the template and in the script.
-- **Values are typed on the way in.** `attrs` takes each field's type: a missing
-  required field, or a status outside its list, fails `astro check`. It also
-  checks at run time, because this runs at build time and a value can arrive as
-  a plain `string` from an env var or a cast; a throw there fails the build
-  rather than shipping a page whose script throws on every visit.
-- **And parsed on the way out.** `read`, `all`, `one` and `require` parse every
-  field and throw, naming the element and the attribute, when one is missing or
-  malformed. A malformed match fails the whole `all` rather than being skipped:
-  a list that quietly loses a row is the failure this exists to prevent.
-
-The kinds are data, not builders, for the reason `filters` gives:
-`text`, `number`, `list`, `template`, `choice` and `flag`, all but `flag`
-optionally `optional`. A `flag` is off by being absent, never `"false"`, so a
-stylesheet can select it with a bare attribute.
-
-A `template` is the one that keeps a sentence out of the script. It is written
-as the translated string with its placeholders left in, and read back as the
-function that fills them:
+template imports the same file for the tag.
+
+- **What the script asks for is what devtools shows.** A selector is a string
+  the template wrote as an attribute; there is no naming scheme to decode.
+  Prefix the names per element (`data-faq-…`) so two elements sharing a
+  subtree cannot pick up each other's.
+- **Missing is loud in dev.** `ref` throws naming the root and the selector;
+  `refs` returns what it found, none included. A throw inside `connect` leaves
+  that element inert and lands in the dev panel, as does any uncaught error on
+  the page — a failing listener, a rejected `await`.
+- **Values are the DOM's.** `data(row, "key")` reads `data-key` and throws, as
+  `ref` does, when it is missing; an optional one is `row.dataset.state`. Parse
+  where the script needs a number or a list. State a stylesheet reads is a plain attribute the
+  script sets — `data-blocked` — which Tailwind selects as `group-data-blocked:`.
+- **The root says it is one.** `AtlasElement` renders the tag with
+  `data-atlas-root`, so a project gives every root a display in one stylesheet
+  rule. A root rendered by hand says so on the dev server.
+
+A sentence the script updates keeps its words in the page. The copy wraps the
+changing part in a variant run, `RichText`'s `attrs` gives that run an
+attribute, and the script writes only that run:
+
+```ts
+"faq.matched": { "en-US": "[v:count]{count}[/v] answers found" },
+```
 
 ```astro
-<p {...faq.line.attrs({ sentence: t("faq.matched", { count: "{count}" }) })}></p>
+<RichText spans={rich("faq.matched", { count: "" })} attrs={{ count: { "data-faq-count": "" } }} />
 ```
 
 ```ts
-line.element.textContent = line.values.sentence({ count: String(hits.size) });
+for (const each of refs(root, "[data-faq-count]")) each.textContent = String(hits.size);
 ```
 
-So no script spells `"{count}"`, and a sentence that never says one of its own
-placeholders fails the build rather than shipping a brace to a reader.
-
-`write` sets fields back onto an element, for state a stylesheet reads — a
-dropdown that is blocked — so the script uses the names the template did.
-
-**What it still cannot reach is the stylesheet.** Tailwind generates CSS from
-class names it finds as literals in the source, so a variant keyed on one of
-these attributes has to spell it: `group-data-network-dropdown-blocked/dd:`.
-That is the one place a rename is not a compile error. It is also the one place
-a drift is visible, since the style stops applying, where a script reading the
-wrong attribute fails silently. `attribute(field)` returns the name for the
-consumers that can take a computed one, such as an `attributeFilter`.
-
-It keeps the rule at the top of this page in the only reading that admits a
-lookup: it finds only elements carrying its own marker, writes only its own
-attributes, and sets no class, `aria` or `hidden`. The names are the project's,
-so nothing in this package has to be matched.
-
-- **Names come from the tag.** Every attribute is `data-<tag>-<role>` plus the
-  field, and the browser refuses to define one tag twice, so two elements cannot
-  share an attribute.
-- **Lookups stay in their instance.** A nested copy of the element keeps its
-  own roles.
-- **The root says it is one.** `{...faq.root}` writes `data-atlas-root`, so a
-  project gives every root a display in one stylesheet rule. Forget it and the
-  element says so on the dev server.
-- **Names are checked in the editor.** A tag without a hyphen, or a role that is
-  not camelCase, is a compile error where it is written.
+Marks are parsed before placeholders are filled, so a run filled with `""`
+still renders as an empty element for the script to write into.
 
 ## `youtube`
 
@@ -587,16 +546,13 @@ right properties is a faithful stand-in.
   `matches` read live as a browser's is, and fakes the `<video>` down to
   `paused`, `currentSrc`, `networkState`, `autoplay`, `play`, `pause` and `load`,
   including what resource selection does after a reload.
-- `tests/markup.test.ts` fakes elements down to four attribute methods and a
-  root that answers bare attribute selectors, and round-trips every field kind
-  through `attrs` and `read`. `type-tests/markup.ts` pins the half that is a
-  compile error.
-- `tests/component.test.ts` builds a small element tree with parents and
-  `closest`, and pins the scoping: a nested instance, two side by side, a root
-  inside the instance, and a broken nested element that must not be read.
-  `type-tests/component.ts` pins the role types and the reserved keys.
-
-`carousel`, `consent` and `element` have none. They need a real DOM and
+- `tests/ref.test.ts` fakes a root down to its two query methods, and pins
+  that `ref` throws naming the root and the selector.
+- `tests/element.test.ts` stubs `customElements` to upgrade on `define`, as a
+  browser does, and pins what `connect` is handed.
+
+`carousel` and `consent` have none, and `element` has no lifecycle test — moves
+and teardown. They need a real DOM and
 this package carries no environment for one; adding `happy-dom` as a dev
 dependency and setting `environment` in `vitest.config.ts` is what that would
 take.

package/docs/rich-text.md

@@ -234,15 +234,20 @@ faqPage([{ question, answer: html(rich("faq.city.a", { network: "network" })) }]
 
 ## The renderer half
 
-`@escape-game-over/atlas/astro/rich-text` renders the runs. The site supplies the
-look — a class per `[v:name]` and one for links — usually in a small wrapper
+`@escape-game-over/atlas/astro/rich-text` renders the runs, and only the runs:
+the caller writes the element around them. The site supplies the look — a class
+per `[v:name]` and one for links — usually in a small wrapper
 ([`examples/b2c/src/components/RichText.astro`](../examples/b2c/src/components/RichText.astro)):
 
 ```astro
-<RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} link="…" />
+<p class="…">
+    <RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} link="…" />
+</p>
 ```
 
-A variant with no class still renders its words, and warns at build.
+`attrs` puts attributes on a variant's run, so a script can find it and rewrite
+its words — see [client-scripts.md](client-scripts.md). A variant with neither a
+class nor attrs still renders its words, and warns at build.
 
 ## What fails, and where
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.25",
+    "version": "0.1.27",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -18,6 +18,7 @@
         "./client": "./src/astro/client.ts",
         "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
         "./astro/document": "./src/astro/Document.astro",
+        "./astro/element": "./src/astro/AtlasElement.astro",
         "./astro/image": "./src/astro/Image.astro",
         "./astro/rich-text": "./src/astro/RichText.astro"
     },
@@ -50,10 +51,10 @@
         "typescript": ">=5"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.13",
-        "@types/node": "26.5.1",
+        "@biomejs/biome": "2.5.14",
+        "@types/node": "26.6.2",
         "@vitest/coverage-istanbul": "5.0.1",
-        "astro": "7.3.2",
+        "astro": "7.3.3",
         "typescript": "6.0.3",
         "vitest": "5.0.1"
     }

package/src/astro/AtlasElement.astro

@@ -0,0 +1,26 @@
+---
+/**
+ * Renders a custom element with the root attribute: what a stylesheet gives
+ * every root its display by, and what `element` checks for in dev.
+ *
+ * ```astro
+ * <AtlasElement of={trailer} data-video={video} class="…">…</AtlasElement>
+ * ```
+ */
+import type { HTMLAttributes } from "astro/types";
+import { type ElementTag, ROOT_ATTRIBUTE } from "./element.ts";
+
+interface Props extends HTMLAttributes<"div"> {
+    readonly of: ElementTag;
+}
+
+const { of, ...rest } = Astro.props;
+const Tag = of.tag;
+---
+
+<Tag
+    {...rest}
+    {...{ [ROOT_ATTRIBUTE]: "" }}
+>
+    <slot />
+</Tag>

package/src/astro/ConsentElement.astro

@@ -1,55 +1,61 @@
 ---
 /** Internal to `ConsentBanner.astro`, so its script ships only where it renders. */
 import type { HTMLAttributes } from "astro/types";
+import AtlasElement from "./AtlasElement.astro";
 import { consentBanner } from "./consent.ts";
 
 type Props = HTMLAttributes<"div">;
 ---
 
-<atlas-consent
+<AtlasElement
+    of={consentBanner}
     {...Astro.props}
-    {...consentBanner.root}
     hidden
     role="dialog"
     aria-modal="false"
 >
     <slot />
-</atlas-consent>
+</AtlasElement>
 
 <script>
 import {
     applyConsent,
-    CONSENT_ROLES,
+    CONSENT_ANSWER,
+    CONSENT_REOPEN,
     consentApplies,
-    consentReopen,
     consentStore,
 } from "./consent.ts";
 import { element } from "./element.ts";
+import { refs } from "./ref.ts";
 
-element("atlas-consent", CONSENT_ROLES, (host, { answer }, signal) => {
+element("atlas-consent", ({ root, signal }) => {
     // The head script left no consent hook: nothing here sets a cookie.
     if (!consentApplies()) return;
 
     const store = consentStore();
     const show = (): void => {
-        host.hidden = false;
+        root.hidden = false;
     };
 
-    for (const { element, values } of answer.all()) {
-        element.addEventListener(
+    for (const button of refs(root, `[${CONSENT_ANSWER}]`)) {
+        const choice = button.getAttribute(CONSENT_ANSWER);
+        if (choice !== "granted" && choice !== "denied") {
+            throw new Error(`${CONSENT_ANSWER} is "${choice}"`);
+        }
+        button.addEventListener(
             "click",
             () => {
-                store.record(values.choice);
-                host.hidden = true;
+                store.record(choice);
+                root.hidden = true;
             },
             { signal }
         );
     }
 
     // Outside the banner — withdrawing must be as easy as granting.
-    for (const { element } of consentReopen.all(document)) {
-        element.hidden = false;
-        element.addEventListener("click", show, { signal });
+    for (const button of refs(document, `[${CONSENT_REOPEN}]`)) {
+        button.hidden = false;
+        button.addEventListener("click", show, { signal });
     }
 
     // Applied, not re-recorded: recording stamps today's date, and an answer

package/src/astro/Image.astro

@@ -95,8 +95,7 @@ const picture: ComponentProps<typeof Picture> = {
         src={src}
         alt={alt}
         closeLabel={zoom.closeLabel}
-        class={zoom.class}
-    >
+        class={zoom.class}>
         <Picture {...picture} />
     </Zoom>
 )}

package/src/astro/MetaTags.astro

@@ -25,27 +25,40 @@ const { tags } = Astro.props;
     // again as HTML would turn each quote into an entity and leave a block no
     // parser reads.
     if (tag.kind === "script") {
-      return <script type={tag.type} is:inline set:html={tag.content} />;
+        return (
+            <script
+                type={tag.type}
+                is:inline
+                set:html={tag.content}
+            />
+        );
     }
     // `is:inline` so the bundler leaves a third-party URL alone, and `defer`
     // because a script that blocks the parser costs the thing it measures.
     if (tag.kind === "externalScript") {
-      return <script is:inline defer src={tag.src} {...tag.attrs} />;
+        return (
+            <script
+                is:inline
+                defer
+                src={tag.src}
+                {...tag.attrs}
+            />
+        );
     }
     // Tag Manager's fallback, and only ever in the body list. Hidden the way
     // Google's own snippet hides it — a zero-sized iframe nothing can see.
     if (tag.kind === "noscriptFrame") {
-      return (
-        <noscript>
-          <iframe
-            src={tag.src}
-            title="Google Tag Manager"
-            height="0"
-            width="0"
-            style="display:none;visibility:hidden"
-          />
-        </noscript>
-      );
+        return (
+            <noscript>
+                <iframe
+                    src={tag.src}
+                    title='Google Tag Manager'
+                    height='0'
+                    width='0'
+                    style='display:none;visibility:hidden'
+                />
+            </noscript>
+        );
     }
     if (tag.kind === "meta") return <meta {...tag.attrs} />;
     // Named rather than left to a trailing `return`, which used to catch
@@ -59,4 +72,4 @@ const { tags } = Astro.props;
     // copied into every project.
     const unhandled: never = tag;
     throw new Error(`Unhandled meta tag: ${JSON.stringify(unhandled)}`);
-  })}
+})}