@escape-game-over/atlas 0.1.17 → 0.1.18

package/docs/client-scripts.md

@@ -428,6 +428,53 @@ 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.
 
+### `component`: roles owned by one custom element
+
+`markup` leaves two things to the project, and both bite: a name per role, which
+two components can pick alike, and scope, since `querySelectorAll` from an
+element also finds everything inside a nested copy of that element. `component`
+ties every role to a custom element and settles both.
+
+```ts
+export const faq = component("go-faq", {
+    row: { key: { kind: "text" }, text: { kind: "text" } },
+    search: {},
+});
+```
+
+```astro
+<faq.tag>
+    <input {...faq.search.attrs()} type="search">
+    <details {...faq.row.attrs({ key, text })}>…</details>
+</faq.tag>
+```
+
+```ts
+class Faq extends AtlasElement {
+    protected connect(): void {
+        for (const { element, values } of faq.row.all(this)) { … }
+    }
+}
+faq.define(Faq);
+```
+
+- **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 components
+  cannot share an attribute. Two roles of one component that would write the
+  same attribute — `search` with a field `clear`, and a role `searchClear` — are
+  refused when the component is created.
+- **Lookups stay in their instance.** `all`, `one` and `require` return only
+  elements whose nearest ancestor with this tag is the root's. A nested copy
+  keeps its elements, and a lookup from an element inside the instance, like a
+  dropdown's own panel, still counts as that instance. Elements are filtered
+  before they are read, so a broken nested copy cannot fail the outer lookup.
+- **The tag is written once.** `faq.tag` is what the template renders and
+  `faq.define` registers the class under it.
+
+`tag` and `define` are the component's own keys, so no role may take them. A role
+that lives outside every instance, such as a footer button that reopens a
+banner, is still plain `markup`.
+
 ## `youtube`
 
 A YouTube video that loads nothing from YouTube until a reader asks for it. The
@@ -565,6 +612,10 @@ right properties is a faithful stand-in.
   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`, `element` and `dom` have none. They need a real DOM and
 this package carries no environment for one; adding `happy-dom` as a dev

package/package.json

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

package/src/astro/markup.ts

@@ -430,3 +430,145 @@ export function markup<const F extends MarkupFields = Record<never, never>>(
         },
     };
 }
+
+/** A component's roles, by name: each is the fields of one `markup` role. */
+export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
+
+/** Keys the component object uses itself, so no role may take them. */
+type Reserved = "tag" | "define";
+
+export type Component<Tag extends string, R extends ComponentRoles> = {
+    /** The custom element's name: what the template renders. */
+    readonly tag: Tag;
+    /** Registers the element's class under `tag`. */
+    define(element: CustomElementConstructor): void;
+} & { readonly [K in keyof R]: Markup<R[K]> };
+
+/** A custom element name, as far as a pattern can check it: needs a hyphen. */
+const TAG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
+
+/**
+ * A custom element and the roles inside it, with lookups scoped to one
+ * instance.
+ *
+ * ```ts
+ * export const faq = component("go-faq", {
+ *     row: { key: { kind: "text" }, text: { kind: "text" } },
+ *     search: {},
+ * });
+ *
+ * // template: <faq.tag> … <details {...faq.row.attrs({ key, text })}>
+ * // script:   faq.row.all(this); faq.define(Faq);
+ * ```
+ *
+ * Two things `markup` alone leaves to the project:
+ *
+ * - **Names.** Every attribute is `data-<tag>-<role>[-<field>]`. The browser
+ *   refuses to define one tag twice, so two components cannot share an
+ *   attribute, and clashes inside one component are refused here.
+ * - **Scope.** A lookup returns only elements owned by the same instance as
+ *   its root — the owner being the nearest ancestor with this tag. A nested
+ *   instance keeps its elements to itself, and the root may be any element
+ *   inside the instance, not only the instance itself.
+ *
+ * Roles outside any instance, like a footer button that reopens a banner, are
+ * what plain `markup` is still for.
+ */
+export function component<
+    const Tag extends string,
+    const R extends ComponentRoles & { readonly [K in Reserved]?: never },
+>(tag: Tag, roles: R): Component<Tag, R> {
+    if (!TAG.test(tag)) {
+        throw new Error(
+            `component(${show(tag)}): a custom element name is lowercase words with at least one hyphen, as in "go-faq"`
+        );
+    }
+
+    // Every attribute the component writes, so two that coincide are refused
+    // rather than left to overwrite each other.
+    const claimed = new Map<string, string>();
+    const claim = (attribute: string, by: string): void => {
+        const earlier = claimed.get(attribute);
+        if (earlier !== undefined) {
+            throw new Error(
+                `component(${show(tag)}): ${by} and ${earlier} would both write ${attribute}`
+            );
+        }
+        claimed.set(attribute, by);
+    };
+
+    /** The instance a root belongs to; `null` for the document. */
+    const ownerOf = (root: ParentNode): Element | null =>
+        "closest" in root && typeof root.closest === "function"
+            ? root.closest(tag)
+            : null;
+
+    const scoped = (
+        role: string,
+        fields: MarkupFields
+    ): Markup<MarkupFields> => {
+        if (role === "tag" || role === "define") {
+            throw new Error(
+                `component(${show(tag)}): ${show(role)} is taken by the component itself`
+            );
+        }
+        if (!FIELD.test(role)) {
+            throw new Error(
+                `component(${show(tag)}): the role ${show(role)} must be camelCase — it becomes part of the attribute`
+            );
+        }
+
+        const base = markup(`${tag}-${hyphenate(role)}`, fields);
+        claim(base.selector.slice(1, -1), `the role ${show(role)}`);
+        for (const field of Object.keys(fields)) {
+            claim(base.attribute(field), `${role}.${field}`);
+        }
+
+        // Filtered before anything is read, so a malformed element in a nested
+        // instance cannot fail a lookup that was never going to return it.
+        const mine = <T extends Element>(root: ParentNode): T[] => {
+            const owner = ownerOf(root);
+            return [...root.querySelectorAll<T>(base.selector)].filter(
+                (element) => element.closest(tag) === owner
+            );
+        };
+
+        const one = <T extends Element = HTMLElement>(
+            root: ParentNode
+        ): Marked<T, MarkupFields> | null => {
+            const [found] = mine<T>(root);
+            return found === undefined
+                ? null
+                : { element: found, values: base.read(found) };
+        };
+
+        return {
+            ...base,
+            all: <T extends Element = HTMLElement>(root: ParentNode) =>
+                mine<T>(root).map((element) => ({
+                    element,
+                    values: base.read(element),
+                })),
+            one,
+            require<T extends Element = HTMLElement>(root: ParentNode) {
+                const found = one<T>(root);
+                if (found === null) {
+                    throw new Error(
+                        `nothing in this <${tag}> carries ${base.selector.slice(1, -1)} — does the template spread its attrs inside the element?`
+                    );
+                }
+                return found;
+            },
+        };
+    };
+
+    const built: Record<string, unknown> = {
+        tag,
+        define: (element: CustomElementConstructor) =>
+            customElements.define(tag, element),
+    };
+    for (const [role, fields] of Object.entries(roles)) {
+        built[role] = scoped(role, fields);
+    }
+    return built as Component<Tag, R>;
+}