@escape-game-over/atlas 0.1.25 → 0.1.26

package/docs/client-scripts.md

@@ -73,9 +73,9 @@ 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", ({ host, signal }) => {
+    ref(host, "[data-thing-button]").addEventListener("click", open, { signal });   // ends with the visit
+    return loop.attach(host);                                                        // and so does this
 });
 ```
 
@@ -363,96 +363,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", ({ host, signal }) => {
+    const input = ref<HTMLInputElement>(host, "[data-faq-search]");
+    for (const row of refs<HTMLDetailsElement>(host, "[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(host, "[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 +561,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.26",
     "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,32 +1,34 @@
 ---
 /** 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", ({ host, signal }) => {
     // The head script left no consent hook: nothing here sets a cookie.
     if (!consentApplies()) return;
 
@@ -35,11 +37,15 @@ element("atlas-consent", CONSENT_ROLES, (host, { answer }, signal) => {
         host.hidden = false;
     };
 
-    for (const { element, values } of answer.all()) {
-        element.addEventListener(
+    for (const button of refs(host, `[${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);
+                store.record(choice);
                 host.hidden = true;
             },
             { signal }
@@ -47,9 +53,9 @@ element("atlas-consent", CONSENT_ROLES, (host, { answer }, 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)}`);
-  })}
+})}

package/src/astro/RichText.astro

@@ -1,71 +1,88 @@
 ---
 /**
  * Renders what `site.rich()` returns. The site supplies the look: a class per
- * `[v:name]` variant and one for links; everything else is decided here.
+ * `[v:name]` variant and one for links; everything else is decided here. Only
+ * the runs — the caller writes the element they sit in.
  *
  * ```astro
- * <RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} />
+ * <p class="…">
+ *     <RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} />
+ * </p>
  * ```
  */
-import type { HTMLTag } from "astro/types";
 import type { RichText } from "../content/index.ts";
 import { warn } from "../warn.ts";
 
 interface Props {
     readonly spans: RichText;
-    /** The element wrapping the runs. Defaults to `p`. */
-    readonly as?: HTMLTag;
-    readonly class?: string;
     /** `[v:name]` → classes. */
     readonly variants?: Readonly<Record<string, string>>;
+    /** `[v:name]` → attributes, so a script can find that run. */
+    readonly attrs?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     /** Classes on every link: `[a:]`, `[mail]` and `[tel]`. */
     readonly link?: string;
 }
 
-const {
-    spans,
-    as: Tag = "p",
-    class: className,
-    variants = {},
-    link,
-}: Props = Astro.props;
+const { spans, variants = {}, attrs = {}, link }: Props = Astro.props;
 
 // The words still render: losing the sentence is worse than losing its style.
+// A run with attributes and no class is a script's hook, not a missing style.
 const variantClass = (variant: string): string | undefined => {
-    if (!Object.hasOwn(variants, variant)) {
+    if (!Object.hasOwn(variants, variant) && !Object.hasOwn(attrs, variant)) {
         warn(
             Astro.url.pathname,
-            `[v:${variant}] has no class in RichText's variants.`
+            `[v:${variant}] has no class in RichText's variants and no attrs.`
         );
     }
-    return variants[variant];
+    return Object.hasOwn(variants, variant) ? variants[variant] : undefined;
 };
+
+const variantAttrs = (variant: string) =>
+    Object.hasOwn(attrs, variant) ? attrs[variant] : undefined;
 ---
 
-<Tag class={className}>
-    {spans.map((span) => {
-        switch (span.kind) {
-            case "text":
-                return span.text;
-            case "bold":
-                return <strong>{span.text}</strong>;
-            case "variant":
-                return <span class={variantClass(span.variant)}>{span.text}</span>;
-            case "break":
-                return <br />;
-            case "link":
-                return span.to === "external" ? (
-                    <a href={span.href} class={link} target="_blank" rel="noopener noreferrer">
-                        {span.text}
-                    </a>
-                ) : (
-                    <a href={span.href} class={link}>{span.text}</a>
-                );
-            case "mail":
-            case "tel":
-                return <a href={span.href} class={link}>{span.text}</a>;
-            default:
-                return span satisfies never;
-        }
-    })}
-</Tag>
+{spans.map((span) => {
+    switch (span.kind) {
+        case "text":
+            return span.text;
+        case "bold":
+            return <strong>{span.text}</strong>;
+        case "variant":
+            return (
+                <span
+                    {...variantAttrs(span.variant)}
+                    class={variantClass(span.variant)}>
+                    {span.text}
+                </span>
+            );
+        case "break":
+            return <br />;
+        case "link":
+            return span.to === "external" ? (
+                <a
+                    href={span.href}
+                    class={link}
+                    target='_blank'
+                    rel='noopener noreferrer'>
+                    {span.text}
+                </a>
+            ) : (
+                <a
+                    href={span.href}
+                    class={link}>
+                    {span.text}
+                </a>
+            );
+        case "mail":
+        case "tel":
+            return (
+                <a
+                    href={span.href}
+                    class={link}>
+                    {span.text}
+                </a>
+            );
+        default:
+            return span satisfies never;
+    }
+})}

package/src/astro/client.ts

@@ -20,14 +20,13 @@ export {
     consentApplies,
     consentStore,
 } from "./consent.ts";
-export { type Connect, type ElementRoles, element } from "./element.ts";
+export {
+    type Connect,
+    type ElementContext,
+    type ElementTag,
+    element,
+} from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
-export {
-    type Component,
-    type Marked,
-    type Markup,
-    marker,
-    markup,
-} from "./markup.ts";
+export { data, ref, refs } from "./ref.ts";
 export * from "./youtube.ts";

package/src/astro/consent.ts

@@ -1,12 +1,12 @@
 import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
-import { component, markup } from "./markup.ts";
+import type { ElementTag } from "./element.ts";
 
-/** Internal to `ConsentBanner.astro`: the element and the footer control. */
-export const CONSENT_ROLES = {
-    answer: { choice: { kind: "choice", of: ["granted", "denied"] } },
-} as const;
-export const consentBanner = component("atlas-consent", CONSENT_ROLES);
-export const consentReopen = markup("atlas-consent-reopen");
+/** Internal to `ConsentBanner.astro`: the element, and what its script finds. */
+export const consentBanner: ElementTag<"atlas-consent"> = {
+    tag: "atlas-consent",
+};
+export const CONSENT_ANSWER = "data-atlas-consent-answer";
+export const CONSENT_REOPEN = "data-atlas-consent-reopen";
 
 /**
  * What a site's consent markup spreads: the two answer buttons inside
@@ -15,9 +15,9 @@ export const consentReopen = markup("atlas-consent-reopen");
  * withdraw.
  */
 export const consent = {
-    accept: consentBanner.answer.attrs({ choice: "granted" }),
-    decline: consentBanner.answer.attrs({ choice: "denied" }),
-    reopen: { ...consentReopen.attrs(), hidden: "" },
+    accept: { [CONSENT_ANSWER]: "granted" },
+    decline: { [CONSENT_ANSWER]: "denied" },
+    reopen: { [CONSENT_REOPEN]: "", hidden: "" },
 };
 
 /**