@escape-game-over/atlas 0.1.25 → 0.1.27

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: "" },
 };
 
 /**

package/src/astro/element.ts

@@ -1,105 +1,92 @@
 import { reportDevError } from "./dev-log.ts";
-import {
-    type CheckedKeys,
-    type CheckedTagName,
-    type Component,
-    type ComponentRoles,
-    component,
-    type Marked,
-    type MarkupFields,
-    type Reserved,
-    ROOT_ATTRIBUTE,
-} from "./markup.ts";
+
+/**
+ * What `AtlasElement` puts on every root: one name, so a project gives every
+ * root a display in a single stylesheet rule, and so `element` can say when a
+ * root was rendered by hand.
+ */
+export const ROOT_ATTRIBUTE = "data-atlas-root";
 
 /** What is left to undo when the element leaves; usually nothing. */
 // biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
 type Undo = void | (() => void);
 
-/**
- * One role's lookups inside this instance. A role with no fields is found for
- * the element alone; one with fields comes back with its values read.
- */
-type Lookups<F extends MarkupFields> = [keyof F] extends [never]
-    ? {
-          all<T extends Element = HTMLElement>(): T[];
-          one<T extends Element = HTMLElement>(): T | null;
-          require<T extends Element = HTMLElement>(): T;
-      }
-    : {
-          all<T extends Element = HTMLElement>(): Marked<T, F>[];
-          one<T extends Element = HTMLElement>(): Marked<T, F> | null;
-          require<T extends Element = HTMLElement>(): Marked<T, F>;
-      };
-
-/** Every role of an element, bound to one instance. */
-export type ElementRoles<R extends ComponentRoles> = {
-    readonly [K in keyof R]: Lookups<R[K]>;
-};
+export interface ElementContext {
+    /** The element itself: where `ref` and `refs` search from. */
+    readonly root: HTMLElement;
+    /** Aborted when the element leaves, taking its listeners with it. */
+    readonly signal: AbortSignal;
+}
 
 /**
- * What an element does while it is on the page. `signal` is aborted when it
- * leaves, so listeners registered with it come down on their own; anything else
- * to undo is the returned function.
+ * What an element does while it is on the page. Anything `signal` does not
+ * already undo is the returned function.
  */
-export type Connect<R extends ComponentRoles> = (
-    host: HTMLElement,
-    roles: ElementRoles<R>,
-    signal: AbortSignal
-) => Undo;
+export type Connect = (context: ElementContext) => Undo;
+
+/** What a template renders the element from, with `AtlasElement`. */
+export interface ElementTag<Tag extends string = string> {
+    readonly tag: Tag;
+}
 
 /**
- * A custom element: its markup contract and its behaviour, in one call.
+ * A custom element's behaviour, registered under `tag`.
  *
  * ```ts
- * // faq.ts — imported by the template, and by the page's script
- * export const faq = element("go-faq", { row: { key: { kind: "text" } }, search: marker },
- *     (host, { row, search }, signal) => { … });
+ * // faq.ts — imported by the template for the tag, and by the page's script
+ * export const faq = element("go-faq", ({ root, signal }) => {
+ *     const input = ref<HTMLInputElement>(root, "[data-faq-search]");
+ *     …
+ * });
  * ```
  * ```astro
  * <script src="./faq.ts"></script>
+ * <AtlasElement of={faq}><input data-faq-search type="search"></AtlasElement>
  * ```
  *
  * Registers itself when loaded in a browser and does nothing in Node, so the
- * template imports the same file for the contract.
+ * template imports the same file.
  *
  * - **An element can enter the page more than once.** Moving it runs the undo
  *   and `connect` again; Astro's `ClientRouter` does so on every navigation.
- *   State that must survive belongs in a `WeakMap` keyed by `host`.
+ *   State that must survive belongs in a `WeakMap` keyed by `root`.
  * - **The page's script must stay a bundled module** (a plain `<script>`), so
  *   the element has its children when it upgrades.
- * - **A `connect` that throws leaves that one element inert** and reports it.
+ * - **Failures show in dev.** A `connect` that throws leaves that one element
+ *   inert, and it, or any uncaught error on the page, lands in the dev panel.
  * - **A tag defined twice keeps the first definition** and reports the second.
  */
-export function element<
-    const Tag extends string,
-    const R extends ComponentRoles &
-        CheckedKeys<R> & { readonly [K in Reserved]?: never },
->(
-    tag: Tag & CheckedTagName<Tag>,
-    roles: R,
-    connect: Connect<R>
-): Component<Tag, R> {
-    // Already checked by this function's own signature.
-    const contract = component(tag as never, roles) as Component<Tag, R>;
+export function element<const Tag extends string>(
+    tag: Tag,
+    connect: Connect
+): ElementTag<Tag> {
     if (typeof customElements !== "undefined") {
-        define(contract, roles, connect);
+        watchDevErrors();
+        // Defining upgrades elements already on the page synchronously; a
+        // microtask later, `const x = element(…)` is assigned first.
+        queueMicrotask(() => define(tag, connect));
     }
-    return contract;
+    return { tag };
 }
 
-/** The shape this file needs off a role, without its field types. */
-interface AnyRole {
-    all(root: ParentNode): Marked<Element, MarkupFields>[];
-    one(root: ParentNode): Marked<Element, MarkupFields> | null;
-    require(root: ParentNode): Marked<Element, MarkupFields>;
+let watching = false;
+
+/**
+ * Puts errors thrown outside `connect` — in a listener, after an `await` — in
+ * the dev panel too. Once per page load: the listeners outlive a body swap.
+ */
+function watchDevErrors(): void {
+    if (!import.meta.env.DEV || watching) return;
+    watching = true;
+    window.addEventListener("error", (event) => {
+        reportDevError("page", event.error ?? event.message);
+    });
+    window.addEventListener("unhandledrejection", (event) => {
+        reportDevError("page", event.reason);
+    });
 }
 
-function define<R extends ComponentRoles>(
-    contract: Component<string, R>,
-    roles: R,
-    connect: Connect<R>
-): void {
-    const { tag } = contract;
+function define(tag: string, connect: Connect): void {
     if (customElements.get(tag) !== undefined) {
         reportDevError(
             tag,
@@ -108,27 +95,6 @@ function define<R extends ComponentRoles>(
         return;
     }
 
-    const bind = (host: HTMLElement): ElementRoles<R> => {
-        const bound: Record<string, unknown> = {};
-        for (const [name, fields] of Object.entries(roles)) {
-            const role = (contract as unknown as Record<string, AnyRole>)[name];
-            if (role === undefined) continue;
-            bound[name] =
-                Object.keys(fields).length === 0
-                    ? {
-                          all: () => role.all(host).map((each) => each.element),
-                          one: () => role.one(host)?.element ?? null,
-                          require: () => role.require(host).element,
-                      }
-                    : {
-                          all: () => role.all(host),
-                          one: () => role.one(host),
-                          require: () => role.require(host),
-                      };
-        }
-        return bound as ElementRoles<R>;
-    };
-
     customElements.define(
         tag,
         class extends HTMLElement {
@@ -146,11 +112,11 @@ function define<R extends ComponentRoles>(
                         !this.hasAttribute(ROOT_ATTRIBUTE)
                     ) {
                         throw new Error(
-                            `<${tag}> carries no ${ROOT_ATTRIBUTE} — does the template spread {...x.root} on it?`
+                            `<${tag}> carries no ${ROOT_ATTRIBUTE} — is it rendered with <AtlasElement of={…}>?`
                         );
                     }
                     this.#undo =
-                        connect(this, bind(this), ac.signal) ?? undefined;
+                        connect({ root: this, signal: ac.signal }) ?? undefined;
                 } catch (error) {
                     reportDevError(this.localName, error);
                 }

package/src/astro/filters-view.ts

@@ -10,21 +10,18 @@
  * on a clear button, an empty message or a section with nothing left. No class,
  * style or `aria`: that is where the choices live.
  *
- * Two notes for the markup:
- *
- * - **`hidden` needs help in a grid.** Any author rule setting `display` beats
- *   it. Tailwind v4's preflight ships `[hidden] { display: none !important }`;
- *   without something like it these writes are inert and nothing filters.
- * - **A result count wants `aria-live="polite"`**, in the template.
+ * **`hidden` needs help in a grid.** Any author rule setting `display` beats it.
+ * Tailwind v4's preflight ships `[hidden] { display: none !important }`; without
+ * something like it these writes are inert and nothing filters.
  *
  * See docs/client-scripts.md.
  */
 
-import type { FieldMap, FilterChange, Filters } from "./filters.ts";
+import type { FieldMap, FilterChange, Filters, KindOf } from "./filters.ts";
 
 /** The `text` fields of `F`, so a search box cannot be pointed at a flag. */
 export type TextFieldOf<F extends FieldMap> = {
-    [K in keyof F]: F[K] extends { kind: "text" } ? K : never;
+    [K in keyof F]: KindOf<F[K]> extends "text" ? K : never;
 }[keyof F];
 
 /**
@@ -38,12 +35,6 @@ export interface SearchBoxElements {
     readonly clear?: HTMLElement | null;
     /** The "nothing matched" message. Tracks the whole result set. */
     readonly empty?: HTMLElement | null;
-    /**
-     * How many matched, as digits and nothing else: the sentence around them is
-     * translated, and not something to take apart in a browser. Give the count
-     * its own element and let the copy sit beside it.
-     */
-    readonly count?: HTMLElement | null;
 }
 
 /**
@@ -54,20 +45,20 @@ export interface SearchBoxElements {
  * ```ts
  * const list = filters({ fields, items, onChange: … });
  * const detach = list.attach();
- * const unbind = searchBox(list, "q", { input, clear, empty, count });
+ * const unbind = searchBox(list, "q", { input, clear, empty });
  * ```
  */
-export function searchBox<F extends FieldMap>(
-    list: Filters<F>,
+export function searchBox<F extends FieldMap, T>(
+    list: Filters<F, T>,
     field: TextFieldOf<F>,
     elements: SearchBoxElements
 ): () => void {
-    const { input, clear, empty, count } = elements;
+    const { input, clear, empty } = elements;
     // The narrowing `TextFieldOf` already did: inside a generic function
     // TypeScript cannot see that this field holds a string.
     const name = field as Parameters<typeof list.set>[0];
 
-    const render = ({ state, matched }: FilterChange<F>): void => {
+    const render = ({ state, matched }: FilterChange<F, T>): void => {
         const query = String(state[name]);
         // Guarded by inequality: assigning `value` while someone types moves
         // the caret to the end, and this exists for state that moved without
@@ -75,7 +66,6 @@ export function searchBox<F extends FieldMap>(
         if (input != null && input.value !== query) input.value = query;
         if (clear != null) clear.hidden = query === "";
         if (empty != null) empty.hidden = matched.size > 0;
-        if (count != null) count.textContent = String(matched.size);
     };
 
     render(list);