@gyral/core 0.2.0 → 0.3.1

package/dist/view/server/tags.js

@@ -0,0 +1,132 @@
+import { serverComponent, serverProvider, } from '../registry.js';
+import { hookSpec } from '../render/hooks.js';
+import { badHook } from '../render/warn.js';
+import { escapeAttr, onlyWhitespace } from './escape.js';
+import { absent, attrText, checkAttrName, lightChildrenError, multiText } from './values.js';
+export const PLAIN = { k: 'plain' };
+export class Markup {
+    /**
+     * `dev`: development markers and checks. `scope`: the nearest provider's scope, passed to
+     * components (undefined: the request's). `styles`: collects every `style` value written.
+     */
+    constructor(dev, scope, styles) {
+        this.dev = dev;
+        this.scope = scope;
+        this.styles = styles;
+        this.buf = '';
+        this.items = [];
+        /** The template being written, for `styles` (its `loc` or id). */
+        this.where = '';
+    }
+    /** Records a `style` value the DOM will see (empty values declare nothing). */
+    style(value) {
+        if (value !== '' && this.styles !== undefined && !this.styles.has(value)) {
+            this.styles.set(value, this.where);
+        }
+    }
+    write(markup) {
+        this.buf += markup;
+    }
+    /** The markup and deferred components written so far. */
+    done() {
+        this.flush();
+        return this.items;
+    }
+    flush() {
+        if (this.buf !== '')
+            this.items.push(this.buf);
+        this.buf = '';
+    }
+    /** `name=${v}` or `name="a ${v} b"`; returns the index of the next value. */
+    attr(s, values, at, opening) {
+        const { name, strings } = s;
+        const value = strings === undefined
+            ? attrText(values[at], s, name, this.dev)
+            : multiText(values, at, strings, s, name, this.dev);
+        if (value !== null)
+            this.valued(name, value, opening);
+        return at + (strings === undefined ? 1 : strings.length - 1);
+    }
+    valued(name, value, opening) {
+        this.buf += ` ${name}="${escapeAttr(value)}"`;
+        if (name === 'style')
+            this.style(value);
+        if (opening !== undefined)
+            opening.attributes[name] = value;
+    }
+    /** A present boolean attribute (`?name`, or `true` from a hook's server half). */
+    bare(name, opening) {
+        this.buf += ` ${name}`;
+        if (opening !== undefined)
+            opening.attributes[name] = '';
+    }
+    /** An element hook: its server half's attributes (02 "Element hooks"). */
+    hook(v, opening) {
+        if (absent(v))
+            return;
+        const spec = hookSpec(v);
+        if (spec === undefined) {
+            if (this.dev)
+                badHook(v);
+            return;
+        }
+        const attributes = spec.server?.(v.args) ?? {};
+        for (const [name, value] of Object.entries(attributes)) {
+            checkAttrName(name);
+            if (value === true)
+                this.bare(name, opening);
+            else
+                this.valued(name, value, opening);
+        }
+    }
+    /** A custom element's start tag: a Gyral component, a provider, or a plain element. */
+    open(tag, html, attrs) {
+        this.buf += html;
+        const component = serverComponent(tag);
+        const provider = component === undefined ? serverProvider(tag) : undefined;
+        if (component === undefined && provider === undefined)
+            return undefined;
+        return { tag, component, provider, attributes: Object.fromEntries(attrs), properties: {} };
+    }
+    openEnd(opening) {
+        if (opening === undefined) {
+            this.buf += '>';
+            return PLAIN;
+        }
+        const { attributes, properties } = opening;
+        const messages = properties['initialMessages'];
+        const input = {
+            attributes,
+            properties,
+            initialMessages: Array.isArray(messages) ? messages : undefined,
+            scope: this.scope,
+        };
+        if (opening.provider !== undefined) {
+            const provided = opening.provider.open(input);
+            for (const [name, value] of Object.entries(provided.attributes)) {
+                this.buf += ` ${name}="${escapeAttr(value)}"`;
+            }
+            this.buf += '>';
+            const frame = { k: 'provider', outer: this.scope };
+            this.scope = provided.scope;
+            return frame;
+        }
+        const component = opening.component; // Sound: open() set one of the two.
+        this.flush();
+        this.items.push({ component, input });
+        return component.light ? { k: 'light', tag: opening.tag, items: this.items.length } : PLAIN;
+    }
+    close(frame, tag) {
+        if (frame.k === 'provider')
+            this.scope = frame.outer;
+        else if (frame.k === 'light') {
+            // Whitespace-only children are dropped; anything else is an error (ADR 0014).
+            if (this.items.length !== frame.items || !onlyWhitespace(this.buf)) {
+                lightChildrenError(frame.tag);
+            }
+            this.buf = '';
+        }
+        this.buf += `</${tag}>`;
+    }
+}
+//# sourceMappingURL=tags.js.map

package/dist/view/server/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../src/view/server/tags.ts"],"names":[],"mappings":"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","sourcesContent":["// Start tags and custom elements for the server renderer (view/06-server.md \"Writing a template\n// result\", \"Components\"): attribute, boolean and hook holes, and what a custom element's\n// `open`/`openEnd`/`close` segments do. A Gyral component's start tag is written here, but\n// its content (seed, shadow root, view) is deferred: the walk returns strings with the\n// deferred components between them, and `render` (index.ts) expands each one in its own step,\n// so every component boundary is a chunk boundary. A provider (`<gyral-stores>`) is a plain\n// element that gives its subtree a scope until its end tag.\nimport type { Segment } from '../normalize/types.js';\nimport {\n  serverComponent,\n  serverProvider,\n  type ServerComponent,\n  type ServerProvider,\n  type ServerRenderInput,\n} from '../registry.js';\nimport { hookSpec, type HookResult } from '../render/hooks.js';\nimport { badHook } from '../render/warn.js';\nimport { escapeAttr, onlyWhitespace } from './escape.js';\nimport { absent, attrText, checkAttrName, lightChildrenError, multiText } from './values.js';\n\n/** A component whose content is written later, in its own render step. */\nexport interface Deferred {\n  readonly component: ServerComponent;\n  readonly input: ServerRenderInput;\n}\n\n/**\n * A render's `style` attribute values for a CSP (ADR 0020): each distinct value as the DOM sees\n * it (decoded), mapped to where it was first written (the template's `loc` or id; `''` when\n * neither is known).\n */\nexport type StyleValues = Map<string, string>;\n\n/** What a walk produces: markup, with deferred components in document order. */\nexport type Item = string | Deferred;\n\n/** A custom element's start tag while its attribute holes are written. */\nexport interface Opening {\n  readonly tag: string;\n  readonly component: ServerComponent | undefined;\n  readonly provider: ServerProvider | undefined;\n  readonly attributes: Record<string, string>;\n  readonly properties: Record<string, unknown>;\n}\n\n/** An open custom element until its end tag: plain, a provider, or a light component. */\nexport type Frame =\n  | { readonly k: 'plain' }\n  | { readonly k: 'provider'; readonly outer: unknown }\n  | { readonly k: 'light'; readonly tag: string; readonly items: number };\n\nexport const PLAIN: Frame = { k: 'plain' };\n\nexport class Markup {\n  protected buf = '';\n  protected readonly items: Item[] = [];\n\n  /** The template being written, for `styles` (its `loc` or id). */\n  protected where = '';\n\n  /**\n   * `dev`: development markers and checks. `scope`: the nearest provider's scope, passed to\n   * components (undefined: the request's). `styles`: collects every `style` value written.\n   */\n  constructor(\n    protected readonly dev: boolean,\n    protected scope: unknown,\n    protected readonly styles?: StyleValues,\n  ) {}\n\n  /** Records a `style` value the DOM will see (empty values declare nothing). */\n  protected style(value: string): void {\n    if (value !== '' && this.styles !== undefined && !this.styles.has(value)) {\n      this.styles.set(value, this.where);\n    }\n  }\n\n  write(markup: string): void {\n    this.buf += markup;\n  }\n\n  /** The markup and deferred components written so far. */\n  done(): Item[] {\n    this.flush();\n    return this.items;\n  }\n\n  private flush(): void {\n    if (this.buf !== '') this.items.push(this.buf);\n    this.buf = '';\n  }\n\n  /** `name=${v}` or `name=\"a ${v} b\"`; returns the index of the next value. */\n  protected attr(\n    s: Extract<Segment, { k: 'attr' }>,\n    values: readonly unknown[],\n    at: number,\n    opening: Opening | undefined,\n  ): number {\n    const { name, strings } = s;\n    const value =\n      strings === undefined\n        ? attrText(values[at], s, name, this.dev)\n        : multiText(values, at, strings, s, name, this.dev);\n    if (value !== null) this.valued(name, value, opening);\n    return at + (strings === undefined ? 1 : strings.length - 1);\n  }\n\n  private valued(name: string, value: string, opening: Opening | undefined): void {\n    this.buf += ` ${name}=\"${escapeAttr(value)}\"`;\n    if (name === 'style') this.style(value);\n    if (opening !== undefined) opening.attributes[name] = value;\n  }\n\n  /** A present boolean attribute (`?name`, or `true` from a hook's server half). */\n  protected bare(name: string, opening: Opening | undefined): void {\n    this.buf += ` ${name}`;\n    if (opening !== undefined) opening.attributes[name] = '';\n  }\n\n  /** An element hook: its server half's attributes (02 \"Element hooks\"). */\n  protected hook(v: unknown, opening: Opening | undefined): void {\n    if (absent(v)) return;\n    const spec = hookSpec(v);\n    if (spec === undefined) {\n      if (this.dev) badHook(v);\n      return;\n    }\n    const attributes = spec.server?.((v as HookResult).args) ?? {};\n    for (const [name, value] of Object.entries(attributes)) {\n      checkAttrName(name);\n      if (value === true) this.bare(name, opening);\n      else this.valued(name, value, opening);\n    }\n  }\n\n  /** A custom element's start tag: a Gyral component, a provider, or a plain element. */\n  protected open(\n    tag: string,\n    html: string,\n    attrs: readonly (readonly [string, string])[],\n  ): Opening | undefined {\n    this.buf += html;\n    const component = serverComponent(tag);\n    const provider = component === undefined ? serverProvider(tag) : undefined;\n    if (component === undefined && provider === undefined) return undefined;\n    return { tag, component, provider, attributes: Object.fromEntries(attrs), properties: {} };\n  }\n\n  protected openEnd(opening: Opening | undefined): Frame {\n    if (opening === undefined) {\n      this.buf += '>';\n      return PLAIN;\n    }\n    const { attributes, properties } = opening;\n    const messages = properties['initialMessages'];\n    const input: ServerRenderInput = {\n      attributes,\n      properties,\n      initialMessages: Array.isArray(messages) ? (messages as readonly unknown[]) : undefined,\n      scope: this.scope,\n    };\n    if (opening.provider !== undefined) {\n      const provided = opening.provider.open(input);\n      for (const [name, value] of Object.entries(provided.attributes)) {\n        this.buf += ` ${name}=\"${escapeAttr(value)}\"`;\n      }\n      this.buf += '>';\n      const frame: Frame = { k: 'provider', outer: this.scope };\n      this.scope = provided.scope;\n      return frame;\n    }\n    const component = opening.component as ServerComponent; // Sound: open() set one of the two.\n    this.flush();\n    this.items.push({ component, input });\n    return component.light ? { k: 'light', tag: opening.tag, items: this.items.length } : PLAIN;\n  }\n\n  protected close(frame: Frame, tag: string): void {\n    if (frame.k === 'provider') this.scope = frame.outer;\n    else if (frame.k === 'light') {\n      // Whitespace-only children are dropped; anything else is an error (ADR 0014).\n      if (this.items.length !== frame.items || !onlyWhitespace(this.buf)) {\n        lightChildrenError(frame.tag);\n      }\n      this.buf = '';\n    }\n    this.buf += `</${tag}>`;\n  }\n}\n"]}

package/dist/view/server/values.d.ts

@@ -0,0 +1,18 @@
+export declare const absent: (v: unknown) => boolean;
+export declare const truthy: (v: unknown) => boolean;
+/** A Promise in any hole: server renders are synchronous (06 "API"). Always an error. */
+export declare function checkPromise(v: object, where: string): void;
+/** `name=${v}`: the value to write, or null to leave the attribute out. */
+export declare function attrText(v: unknown, at: object, name: string, dev: boolean): string | null;
+/** `name="a ${x} b"`: pieces joined; `nothing` in any piece leaves the attribute out. */
+export declare function multiText(values: readonly unknown[], from: number, strings: readonly string[], at: object, name: string, dev: boolean): string | null;
+/** `<textarea>`/`<title>` content: child-hole rules flattened to a string, as on the client. */
+export declare function textContent(v: unknown, at: object, dev: boolean): string;
+/** Text written directly in table structure would be foster-parented (rule 7). */
+export declare function fosterError(text: string, parent: string): never;
+/** An svg template written outside SVG content (`parent`: its parent's name, if known). */
+export declare function svgPlacementError(parent: string | undefined): never;
+/** A light-DOM component owns its children (ADR 0014). */
+export declare function lightChildrenError(tag: string): never;
+/** An attribute name from a hook's server half must not break the start tag. */
+export declare function checkAttrName(name: string): void;

package/dist/view/server/values.js

@@ -0,0 +1,94 @@
+// Value rules for attribute and text-content holes on the server (view/02-bindings.md
+// "Attribute values", "Live form state"; view/06-server.md "Writing a template result"),
+// identical to the client's (render/attr-parts.ts) so both sides write the same attributes.
+// And the server-only errors: a Promise anywhere (renders are synchronous), text the parser
+// would move out of table structure, children given to a light-DOM component.
+import { nothing } from '../render/values.js';
+import { warnTrue, warnValue } from '../render/warn.js';
+const SPEC = 'docs/design-docs/view';
+export const absent = (v) => v === null || v === undefined || v === nothing;
+export const truthy = (v) => v !== nothing && !!v;
+const isObject = (v) => (typeof v === 'object' && v !== null) || typeof v === 'function';
+/** `String(v)`: objects and functions as the client writes them (render/attr-parts.ts). */
+const text = String;
+const isThenable = (v) => typeof v.then === 'function';
+/** A Promise in any hole: server renders are synchronous (06 "API"). Always an error. */
+export function checkPromise(v, where) {
+    if (!isThenable(v))
+        return;
+    throw new TypeError(`gyral: ${where} got a Promise. Server renders are synchronous: state is known before ` +
+        'rendering, so load the data first (in the route handler or a form action) and pass ' +
+        `it as props (${SPEC}/06-server.md "API").`);
+}
+/** `String(v)` for an attribute value, with the development warning for objects. */
+function written(v, at, name, dev) {
+    if (typeof v === 'string')
+        return v;
+    if (isObject(v)) {
+        checkPromise(v, `the attribute ${name}`);
+        if (dev)
+            warnValue(at, v, `the attribute ${name}`);
+    }
+    return text(v);
+}
+/** `name=${v}`: the value to write, or null to leave the attribute out. */
+export function attrText(v, at, name, dev) {
+    return absent(v) ? null : written(v, at, name, dev);
+}
+/** `name="a ${x} b"`: pieces joined; `nothing` in any piece leaves the attribute out. */
+export function multiText(values, from, strings, at, name, dev) {
+    let joined = strings[0] ?? '';
+    for (let i = 1; i < strings.length; i++) {
+        const v = values[from + i - 1];
+        if (v === nothing)
+            return null;
+        joined +=
+            (v === null || v === undefined ? '' : written(v, at, name, dev)) + strings[i];
+    }
+    return joined;
+}
+/** `<textarea>`/`<title>` content: child-hole rules flattened to a string, as on the client. */
+export function textContent(v, at, dev) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number')
+        return String(v);
+    if (isObject(v)) {
+        checkPromise(v, 'the text content');
+        if (dev)
+            warnValue(at, v, 'the text content');
+        return text(v);
+    }
+    if (dev && v === true)
+        warnTrue(at);
+    return '';
+}
+/** Text written directly in table structure would be foster-parented (rule 7). */
+export function fosterError(text, parent) {
+    throw new Error(`gyral: the text ${JSON.stringify(text.slice(0, 40))} is written directly inside ` +
+        `<${parent}>. The HTML parser moves text out of table structure (foster parenting), so ` +
+        'the page would differ from what the client renders. Put text inside a <td>, <th> or ' +
+        `<caption> (${SPEC}/09-template-rules.md, rule 7).`);
+}
+/** An svg template written outside SVG content (`parent`: its parent's name, if known). */
+export function svgPlacementError(parent) {
+    throw new Error(`gyral: an svg template is written ${parent === undefined ? 'at the root of a view' : `inside <${parent}>`}, ` +
+        "which isn't SVG content, so the parser would not create SVG elements and the page " +
+        'would differ from what the client renders. Render svg`…` fragments inside an <svg> (or ' +
+        'another SVG element, not <foreignObject>) of an html template, or write the whole ' +
+        `graphic with html (${SPEC}/01-templates.md "svg templates").`);
+}
+/** A light-DOM component owns its children (ADR 0014). */
+export function lightChildrenError(tag) {
+    throw new Error(`gyral: <${tag}> renders in light DOM (shadow: false), so it owns its children, but its ` +
+        'parent wrote children inside it. Pass the data as props instead, or make it a shadow ' +
+        `component and use <slot> (${SPEC}/06-server.md "Components", ADR 0014).`);
+}
+/** An attribute name from a hook's server half must not break the start tag. */
+export function checkAttrName(name) {
+    if (/^[^\s"'>/=\0]+$/.test(name))
+        return;
+    throw new TypeError(`gyral: an element hook's server half returned the attribute name ${JSON.stringify(name)}, ` +
+        `which isn't a valid attribute name (${SPEC}/02-bindings.md "Element hooks").`);
+}
+//# sourceMappingURL=values.js.map

package/dist/view/server/values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.js","sourceRoot":"","sources":["../../../src/view/server/values.ts"],"names":[],"mappings":"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","sourcesContent":["// Value rules for attribute and text-content holes on the server (view/02-bindings.md\n// \"Attribute values\", \"Live form state\"; view/06-server.md \"Writing a template result\"),\n// identical to the client's (render/attr-parts.ts) so both sides write the same attributes.\n// And the server-only errors: a Promise anywhere (renders are synchronous), text the parser\n// would move out of table structure, children given to a light-DOM component.\nimport { nothing } from '../render/values.js';\nimport { warnTrue, warnValue } from '../render/warn.js';\n\nconst SPEC = 'docs/design-docs/view';\n\nexport const absent = (v: unknown): boolean => v === null || v === undefined || v === nothing;\nexport const truthy = (v: unknown): boolean => v !== nothing && !!v;\n\nconst isObject = (v: unknown): v is object =>\n  (typeof v === 'object' && v !== null) || typeof v === 'function';\n\n/** `String(v)`: objects and functions as the client writes them (render/attr-parts.ts). */\nconst text = String as (value: unknown) => string;\n\nconst isThenable = (v: object): boolean =>\n  typeof (v as { readonly then?: unknown }).then === 'function';\n\n/** A Promise in any hole: server renders are synchronous (06 \"API\"). Always an error. */\nexport function checkPromise(v: object, where: string): void {\n  if (!isThenable(v)) return;\n  throw new TypeError(\n    `gyral: ${where} got a Promise. Server renders are synchronous: state is known before ` +\n      'rendering, so load the data first (in the route handler or a form action) and pass ' +\n      `it as props (${SPEC}/06-server.md \"API\").`,\n  );\n}\n\n/** `String(v)` for an attribute value, with the development warning for objects. */\nfunction written(v: unknown, at: object, name: string, dev: boolean): string {\n  if (typeof v === 'string') return v;\n  if (isObject(v)) {\n    checkPromise(v, `the attribute ${name}`);\n    if (dev) warnValue(at, v, `the attribute ${name}`);\n  }\n  return text(v);\n}\n\n/** `name=${v}`: the value to write, or null to leave the attribute out. */\nexport function attrText(v: unknown, at: object, name: string, dev: boolean): string | null {\n  return absent(v) ? null : written(v, at, name, dev);\n}\n\n/** `name=\"a ${x} b\"`: pieces joined; `nothing` in any piece leaves the attribute out. */\nexport function multiText(\n  values: readonly unknown[],\n  from: number,\n  strings: readonly string[],\n  at: object,\n  name: string,\n  dev: boolean,\n): string | null {\n  let joined = strings[0] ?? '';\n  for (let i = 1; i < strings.length; i++) {\n    const v = values[from + i - 1];\n    if (v === nothing) return null;\n    joined +=\n      (v === null || v === undefined ? '' : written(v, at, name, dev)) + (strings[i] as string);\n  }\n  return joined;\n}\n\n/** `<textarea>`/`<title>` content: child-hole rules flattened to a string, as on the client. */\nexport function textContent(v: unknown, at: object, dev: boolean): string {\n  if (typeof v === 'string') return v;\n  if (typeof v === 'number') return String(v);\n  if (isObject(v)) {\n    checkPromise(v, 'the text content');\n    if (dev) warnValue(at, v, 'the text content');\n    return text(v);\n  }\n  if (dev && v === true) warnTrue(at);\n  return '';\n}\n\n/** Text written directly in table structure would be foster-parented (rule 7). */\nexport function fosterError(text: string, parent: string): never {\n  throw new Error(\n    `gyral: the text ${JSON.stringify(text.slice(0, 40))} is written directly inside ` +\n      `<${parent}>. The HTML parser moves text out of table structure (foster parenting), so ` +\n      'the page would differ from what the client renders. Put text inside a <td>, <th> or ' +\n      `<caption> (${SPEC}/09-template-rules.md, rule 7).`,\n  );\n}\n\n/** An svg template written outside SVG content (`parent`: its parent's name, if known). */\nexport function svgPlacementError(parent: string | undefined): never {\n  throw new Error(\n    `gyral: an svg template is written ${parent === undefined ? 'at the root of a view' : `inside <${parent}>`}, ` +\n      \"which isn't SVG content, so the parser would not create SVG elements and the page \" +\n      'would differ from what the client renders. Render svg`…` fragments inside an <svg> (or ' +\n      'another SVG element, not <foreignObject>) of an html template, or write the whole ' +\n      `graphic with html (${SPEC}/01-templates.md \"svg templates\").`,\n  );\n}\n\n/** A light-DOM component owns its children (ADR 0014). */\nexport function lightChildrenError(tag: string): never {\n  throw new Error(\n    `gyral: <${tag}> renders in light DOM (shadow: false), so it owns its children, but its ` +\n      'parent wrote children inside it. Pass the data as props instead, or make it a shadow ' +\n      `component and use <slot> (${SPEC}/06-server.md \"Components\", ADR 0014).`,\n  );\n}\n\n/** An attribute name from a hook's server half must not break the start tag. */\nexport function checkAttrName(name: string): void {\n  if (/^[^\\s\"'>/=\\0]+$/.test(name)) return;\n  throw new TypeError(\n    `gyral: an element hook's server half returned the attribute name ${JSON.stringify(name)}, ` +\n      `which isn't a valid attribute name (${SPEC}/02-bindings.md \"Element hooks\").`,\n  );\n}\n"]}

package/dist/view/server/writer.d.ts

@@ -0,0 +1,21 @@
+import { type TemplateResult } from '../template.js';
+import { Markup } from './tags.js';
+export type { Deferred, Item, StyleValues } from './tags.js';
+/**
+ * What a child hole's parent means for its value (the development checks): a table tag (text
+ * would be foster-parented), SVG content (where svg templates may render), or nothing.
+ */
+type Ctx = string | undefined;
+/** Warning key for values outside any template (the render root, a component's view). */
+export declare const ROOT: object;
+export declare class Writer extends Markup {
+    /** Writing a page shell's holes (a `server` template): never hydrated, so no anchors (06). */
+    private shell;
+    /** A child value (02 "Child values"). `ctx`: what its parent is (`Ctx`). */
+    child(v: unknown, ctx: Ctx, at: object): void;
+    private object;
+    /** `each(…)`: rows one after another, no markers (03). Keys are checked in development. */
+    private list;
+    /** One template instance: its segments with this render's values. */
+    template(result: TemplateResult, ctx: Ctx): void;
+}

package/dist/view/server/writer.js

@@ -0,0 +1,170 @@
+// The server renderer's walk (view/06-server.md "Writing a template result"): writes a child
+// value by walking template objects' `segments` (01), never tokenizing or building a DOM. Each
+// string segment is written verbatim; each hole op takes its value(s). Start tags and custom
+// elements are tags.ts.
+import { isList, nothing, rawHtml } from '../render/values.js';
+import { badChild, badKey, warnTrue } from '../render/warn.js';
+import { isTemplateResult, templateOf } from '../template.js';
+import { escapeText, onlyWhitespace } from './escape.js';
+import { Markup, PLAIN } from './tags.js';
+import { checkPromise, fosterError, svgPlacementError, textContent, truthy } from './values.js';
+/** Parents in which the parser moves non-whitespace text out (foster parenting). */
+const TABLE = new Set(['table', 'tbody', 'thead', 'tfoot', 'tr']);
+const SVG = '#svg';
+const isTable = (ctx) => ctx !== undefined && TABLE.has(ctx);
+/** A child op's context: its parent's, or the enclosing one at the template root. */
+const ctxOf = (s, outer) => s.svg ? SVG : s.in === undefined ? outer : s.in;
+/** Warning key for values outside any template (the render root, a component's view). */
+export const ROOT = {};
+export class Writer extends Markup {
+    constructor() {
+        super(...arguments);
+        /** Writing a page shell's holes (a `server` template): never hydrated, so no anchors (06). */
+        this.shell = false;
+    }
+    /** A child value (02 "Child values"). `ctx`: what its parent is (`Ctx`). */
+    child(v, ctx, at) {
+        switch (typeof v) {
+            case 'string':
+                if (v === '')
+                    return;
+                if (this.dev && isTable(ctx) && !onlyWhitespace(v))
+                    fosterError(v, ctx);
+                this.buf += escapeText(v);
+                return;
+            case 'number':
+                if (this.dev && isTable(ctx))
+                    fosterError(String(v), ctx);
+                this.buf += String(v);
+                return;
+            case 'object':
+                if (v !== null)
+                    this.object(v, ctx, at);
+                return;
+            case 'boolean':
+                if (v && this.dev)
+                    warnTrue(at);
+                return;
+            case 'undefined':
+                return;
+            default:
+                if (v !== nothing && this.dev)
+                    badChild(v);
+        }
+    }
+    object(v, ctx, at) {
+        if (isTemplateResult(v)) {
+            this.template(v, ctx);
+            return;
+        }
+        if (isList(v)) {
+            this.list(v, ctx, at);
+            return;
+        }
+        if (Array.isArray(v)) {
+            for (const item of v)
+                this.child(item, ctx, at);
+            return;
+        }
+        const raw = rawHtml(v);
+        if (raw !== undefined) {
+            // The start anchor hydration finds (02 "raw(html)"); a page shell is never hydrated.
+            this.buf += this.shell ? raw : `<!---->${raw}`;
+            return;
+        }
+        checkPromise(v, 'a child hole');
+        if (this.dev)
+            badChild(v);
+    }
+    /** `each(…)`: rows one after another, no markers (03). Keys are checked in development. */
+    list(v, ctx, at) {
+        const { items, key, row, pick } = v;
+        const seen = this.dev ? new Set() : undefined;
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            if (seen !== undefined) {
+                const k = key(item);
+                const dup = seen.has(k);
+                if (dup || (typeof k !== 'string' && typeof k !== 'number'))
+                    badKey(k, i, dup);
+                seen.add(k);
+            }
+            this.child(row(item, pick === undefined ? undefined : pick(item)), ctx, at);
+        }
+    }
+    /** One template instance: its segments with this render's values. */
+    template(result, ctx) {
+        const template = templateOf(result);
+        const segments = template.segments;
+        if (segments === undefined) {
+            throw new Error(`gyral: template ${JSON.stringify(template.html.slice(0, 40))} has no server ` +
+                'segments: it was compiled for the client. Render on the server with an SSR build ' +
+                '(or the runtime normalizer), which keeps them ' +
+                '(docs/design-docs/view/01-templates.md "Compiled").');
+        }
+        // An svg template is SVG content: the parser creates SVG elements only inside SVG (01).
+        if (this.dev && template.svg && ctx !== SVG)
+            svgPlacementError(ctx);
+        // Development marker: hydration checks the id before each instance (07). Page shells are
+        // never hydrated.
+        if (this.dev && !template.server)
+            this.buf += `<!--gyral:${template.id ?? ''}-->`;
+        const values = result.values;
+        const outer = this.shell;
+        const outerWhere = this.where;
+        this.shell = template.server === true;
+        if (this.styles !== undefined) {
+            this.where = template.loc ?? template.id ?? '';
+            for (const css of template.staticStyles ?? [])
+                this.style(css);
+        }
+        let at = 0;
+        let opening;
+        let frames;
+        for (const s of segments) {
+            if (typeof s === 'string') {
+                this.buf += s;
+                continue;
+            }
+            switch (s.k) {
+                case 'child':
+                    this.child(values[at++], ctxOf(s, ctx), s);
+                    break;
+                case 'text':
+                    this.buf += escapeText(textContent(values[at++], s, this.dev));
+                    break;
+                case 'attr':
+                    at = this.attr(s, values, at, opening);
+                    break;
+                case 'bool':
+                    // `?indeterminate` has no attribute: it is the property only (02 "Live form state").
+                    // `?modal`/`?popover-open` neither: the browser opens them after hydration (02).
+                    if (truthy(values[at]) && !/^(indeterminate|modal|popover-open)$/.test(s.name)) {
+                        this.bare(s.name, opening);
+                    }
+                    at++;
+                    break;
+                case 'prop':
+                    if (opening !== undefined)
+                        opening.properties[s.name] = values[at];
+                    at++;
+                    break;
+                case 'hook':
+                    this.hook(values[at++], opening);
+                    break;
+                case 'open':
+                    opening = this.open(s.tag, s.html, s.attrs);
+                    break;
+                case 'openEnd':
+                    (frames ??= []).push(this.openEnd(opening));
+                    opening = undefined;
+                    break;
+                case 'close':
+                    this.close(frames?.pop() ?? PLAIN, s.tag);
+            }
+        }
+        this.shell = outer;
+        this.where = outerWhere;
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/view/server/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/view/server/writer.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,+FAA+F;AAC/F,6FAA6F;AAC7F,wBAAwB;AACxB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAmB,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAuB,MAAM,gBAAgB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,KAAK,EAA4B,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIhG,oFAAoF;AACpF,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;AAOlE,MAAM,GAAG,GAAQ,MAAM,CAAC;AAExB,MAAM,OAAO,GAAG,CAAC,GAAQ,EAAiB,EAAE,CAAC,GAAG,KAAK,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjF,qFAAqF;AACrF,MAAM,KAAK,GAAG,CAAC,CAAgD,EAAE,KAAU,EAAO,EAAE,CAClF,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAElD,yFAAyF;AACzF,MAAM,CAAC,MAAM,IAAI,GAAW,EAAE,CAAC;AAE/B,MAAM,OAAO,MAAO,SAAQ,MAAM;IAAlC;;QACE,8FAA8F;QACtF,UAAK,GAAG,KAAK,CAAC;IA0IxB,CAAC;IAxIC,4EAA4E;IAC5E,KAAK,CAAC,CAAU,EAAE,GAAQ,EAAE,EAAU;QACpC,QAAQ,OAAO,CAAC,EAAE,CAAC;YACjB,KAAK,QAAQ;gBACX,IAAI,CAAC,KAAK,EAAE;oBAAE,OAAO;gBACrB,IAAI,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;oBAAE,WAAW,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBACxE,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;gBAC1B,OAAO;YACT,KAAK,QAAQ;gBACX,IAAI,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;oBAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBAC1D,IAAI,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;gBACtB,OAAO;YACT,KAAK,QAAQ;gBACX,IAAI,CAAC,KAAK,IAAI;oBAAE,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;gBACxC,OAAO;YACT,KAAK,SAAS;gBACZ,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG;oBAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;gBAChC,OAAO;YACT,KAAK,WAAW;gBACd,OAAO;YACT;gBACE,IAAI,CAAC,KAAK,OAAO,IAAI,IAAI,CAAC,GAAG;oBAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,CAAS,EAAE,GAAQ,EAAE,EAAU;QAC5C,IAAI,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACd,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrB,KAAK,MAAM,IAAI,IAAI,CAAuB;gBAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACtE,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,qFAAqF;YACrF,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,GAAG,EAAE,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,YAAY,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,GAAG;YAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;IAED,2FAA2F;IACnF,IAAI,CAAC,CAAa,EAAE,GAAQ,EAAE,EAAU;QAC9C,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;gBACpB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBACxB,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,CAAC;oBAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;gBAC/E,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACd,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,QAAQ,CAAC,MAAsB,EAAE,GAAQ;QACvC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QACnC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB;gBAC5E,mFAAmF;gBACnF,gDAAgD;gBAChD,qDAAqD,CACxD,CAAC;QACJ,CAAC;QACD,wFAAwF;QACxF,IAAI,IAAI,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,IAAI,GAAG,KAAK,GAAG;YAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACpE,yFAAyF;QACzF,kBAAkB;QAClB,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,IAAI,CAAC,GAAG,IAAI,aAAa,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC;QAClF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC;QACtC,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,IAAI,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC;YAC/C,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,YAAY,IAAI,EAAE;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,EAAE,GAAG,CAAC,CAAC;QACX,IAAI,OAA4B,CAAC;QACjC,IAAI,MAA2B,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;gBAC1B,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;gBACd,SAAS;YACX,CAAC;YACD,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBACZ,KAAK,OAAO;oBACV,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;oBAC3C,MAAM;gBACR,KAAK,MAAM;oBACT,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;oBAC/D,MAAM;gBACR,KAAK,MAAM;oBACT,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;oBACvC,MAAM;gBACR,KAAK,MAAM;oBACT,qFAAqF;oBACrF,iFAAiF;oBACjF,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,sCAAsC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC/E,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;oBAC7B,CAAC;oBACD,EAAE,EAAE,CAAC;oBACL,MAAM;gBACR,KAAK,MAAM;oBACT,IAAI,OAAO,KAAK,SAAS;wBAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;oBACnE,EAAE,EAAE,CAAC;oBACL,MAAM;gBACR,KAAK,MAAM;oBACT,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;oBACjC,MAAM;gBACR,KAAK,MAAM;oBACT,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;oBAC5C,MAAM;gBACR,KAAK,SAAS;oBACZ,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;oBAC5C,OAAO,GAAG,SAAS,CAAC;oBACpB,MAAM;gBACR,KAAK,OAAO;oBACV,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC;IAC1B,CAAC;CACF","sourcesContent":["// The server renderer's walk (view/06-server.md \"Writing a template result\"): writes a child\n// value by walking template objects' `segments` (01), never tokenizing or building a DOM. Each\n// string segment is written verbatim; each hole op takes its value(s). Start tags and custom\n// elements are tags.ts.\nimport { isList, nothing, rawHtml, type ListResult } from '../render/values.js';\nimport { badChild, badKey, warnTrue } from '../render/warn.js';\nimport { isTemplateResult, templateOf, type TemplateResult } from '../template.js';\nimport { escapeText, onlyWhitespace } from './escape.js';\nimport { Markup, PLAIN, type Frame, type Opening } from './tags.js';\nimport { checkPromise, fosterError, svgPlacementError, textContent, truthy } from './values.js';\n\nexport type { Deferred, Item, StyleValues } from './tags.js';\n\n/** Parents in which the parser moves non-whitespace text out (foster parenting). */\nconst TABLE = new Set(['table', 'tbody', 'thead', 'tfoot', 'tr']);\n\n/**\n * What a child hole's parent means for its value (the development checks): a table tag (text\n * would be foster-parented), SVG content (where svg templates may render), or nothing.\n */\ntype Ctx = string | undefined;\nconst SVG: Ctx = '#svg';\n\nconst isTable = (ctx: Ctx): ctx is string => ctx !== undefined && TABLE.has(ctx);\n\n/** A child op's context: its parent's, or the enclosing one at the template root. */\nconst ctxOf = (s: { readonly in?: string; readonly svg?: true }, outer: Ctx): Ctx =>\n  s.svg ? SVG : s.in === undefined ? outer : s.in;\n\n/** Warning key for values outside any template (the render root, a component's view). */\nexport const ROOT: object = {};\n\nexport class Writer extends Markup {\n  /** Writing a page shell's holes (a `server` template): never hydrated, so no anchors (06). */\n  private shell = false;\n\n  /** A child value (02 \"Child values\"). `ctx`: what its parent is (`Ctx`). */\n  child(v: unknown, ctx: Ctx, at: object): void {\n    switch (typeof v) {\n      case 'string':\n        if (v === '') return;\n        if (this.dev && isTable(ctx) && !onlyWhitespace(v)) fosterError(v, ctx);\n        this.buf += escapeText(v);\n        return;\n      case 'number':\n        if (this.dev && isTable(ctx)) fosterError(String(v), ctx);\n        this.buf += String(v);\n        return;\n      case 'object':\n        if (v !== null) this.object(v, ctx, at);\n        return;\n      case 'boolean':\n        if (v && this.dev) warnTrue(at);\n        return;\n      case 'undefined':\n        return;\n      default:\n        if (v !== nothing && this.dev) badChild(v);\n    }\n  }\n\n  private object(v: object, ctx: Ctx, at: object): void {\n    if (isTemplateResult(v)) {\n      this.template(v, ctx);\n      return;\n    }\n    if (isList(v)) {\n      this.list(v, ctx, at);\n      return;\n    }\n    if (Array.isArray(v)) {\n      for (const item of v as readonly unknown[]) this.child(item, ctx, at);\n      return;\n    }\n    const raw = rawHtml(v);\n    if (raw !== undefined) {\n      // The start anchor hydration finds (02 \"raw(html)\"); a page shell is never hydrated.\n      this.buf += this.shell ? raw : `<!---->${raw}`;\n      return;\n    }\n    checkPromise(v, 'a child hole');\n    if (this.dev) badChild(v);\n  }\n\n  /** `each(…)`: rows one after another, no markers (03). Keys are checked in development. */\n  private list(v: ListResult, ctx: Ctx, at: object): void {\n    const { items, key, row, pick } = v;\n    const seen = this.dev ? new Set<unknown>() : undefined;\n    for (let i = 0; i < items.length; i++) {\n      const item = items[i];\n      if (seen !== undefined) {\n        const k = key(item);\n        const dup = seen.has(k);\n        if (dup || (typeof k !== 'string' && typeof k !== 'number')) badKey(k, i, dup);\n        seen.add(k);\n      }\n      this.child(row(item, pick === undefined ? undefined : pick(item)), ctx, at);\n    }\n  }\n\n  /** One template instance: its segments with this render's values. */\n  template(result: TemplateResult, ctx: Ctx): void {\n    const template = templateOf(result);\n    const segments = template.segments;\n    if (segments === undefined) {\n      throw new Error(\n        `gyral: template ${JSON.stringify(template.html.slice(0, 40))} has no server ` +\n          'segments: it was compiled for the client. Render on the server with an SSR build ' +\n          '(or the runtime normalizer), which keeps them ' +\n          '(docs/design-docs/view/01-templates.md \"Compiled\").',\n      );\n    }\n    // An svg template is SVG content: the parser creates SVG elements only inside SVG (01).\n    if (this.dev && template.svg && ctx !== SVG) svgPlacementError(ctx);\n    // Development marker: hydration checks the id before each instance (07). Page shells are\n    // never hydrated.\n    if (this.dev && !template.server) this.buf += `<!--gyral:${template.id ?? ''}-->`;\n    const values = result.values;\n    const outer = this.shell;\n    const outerWhere = this.where;\n    this.shell = template.server === true;\n    if (this.styles !== undefined) {\n      this.where = template.loc ?? template.id ?? '';\n      for (const css of template.staticStyles ?? []) this.style(css);\n    }\n    let at = 0;\n    let opening: Opening | undefined;\n    let frames: Frame[] | undefined;\n    for (const s of segments) {\n      if (typeof s === 'string') {\n        this.buf += s;\n        continue;\n      }\n      switch (s.k) {\n        case 'child':\n          this.child(values[at++], ctxOf(s, ctx), s);\n          break;\n        case 'text':\n          this.buf += escapeText(textContent(values[at++], s, this.dev));\n          break;\n        case 'attr':\n          at = this.attr(s, values, at, opening);\n          break;\n        case 'bool':\n          // `?indeterminate` has no attribute: it is the property only (02 \"Live form state\").\n          // `?modal`/`?popover-open` neither: the browser opens them after hydration (02).\n          if (truthy(values[at]) && !/^(indeterminate|modal|popover-open)$/.test(s.name)) {\n            this.bare(s.name, opening);\n          }\n          at++;\n          break;\n        case 'prop':\n          if (opening !== undefined) opening.properties[s.name] = values[at];\n          at++;\n          break;\n        case 'hook':\n          this.hook(values[at++], opening);\n          break;\n        case 'open':\n          opening = this.open(s.tag, s.html, s.attrs);\n          break;\n        case 'openEnd':\n          (frames ??= []).push(this.openEnd(opening));\n          opening = undefined;\n          break;\n        case 'close':\n          this.close(frames?.pop() ?? PLAIN, s.tag);\n      }\n    }\n    this.shell = outer;\n    this.where = outerWhere;\n  }\n}\n"]}

package/dist/view/styles.d.ts

@@ -0,0 +1,25 @@
+declare const STYLE: unique symbol;
+/** What `css` returns: CSS text, mapped to one shared `CSSStyleSheet` in the browser. */
+export interface StyleSource {
+    readonly [STYLE]: true;
+    readonly text: string;
+}
+/**
+ * What `spec.styles` accepts: `css` values, plain CSS strings (e.g.
+ * `import base from './base.css?inline'`) and arrays of them, nested freely. CSS is trusted
+ * author code: never interpolate user input.
+ */
+export type Styles = StyleSource | string | readonly Styles[];
+/** A `css` interpolation: inserted as written (another `css` value inserts its text). */
+export type CssValue = string | number | StyleSource;
+export declare const isStyleSource: (value: unknown) => value is StyleSource;
+/**
+ * Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. Strings and numbers are inserted as
+ * written, so values from your own constants need no wrapper.
+ */
+export declare function css(strings: TemplateStringsArray, ...values: readonly CssValue[]): StyleSource;
+/** The CSS texts of `styles`, flattened in order (the server writes them, 06). */
+export declare function styleTexts(styles: Styles | undefined): string[];
+/** One shared sheet per style source (or per distinct string), created on first use. */
+export declare function sheetsFor(styles: Styles | undefined): CSSStyleSheet[];
+export {};

package/dist/view/styles.js

@@ -0,0 +1,58 @@
+// Component styles (view/08-styles.md "Authoring", "Browser"): the `css` tag and the shared
+// sheets. A style source is CSS text plus a cache slot for its one `CSSStyleSheet`, created on
+// first use with `replaceSync`; components that share a source share the sheet. Plain strings
+// are style sources too (cached by text). The server reads the text (06), never the sheet.
+const STYLE = Symbol('gyral.css');
+export const isStyleSource = (value) => typeof value === 'object' && value !== null && STYLE in value;
+/**
+ * Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. Strings and numbers are inserted as
+ * written, so values from your own constants need no wrapper.
+ */
+export function css(strings, ...values) {
+    let text = strings[0] ?? '';
+    for (let i = 0; i < values.length; i++) {
+        const v = values[i];
+        text += (isStyleSource(v) ? v.text : String(v)) + (strings[i + 1] ?? '');
+    }
+    return { [STYLE]: true, text };
+}
+/** The CSS texts of `styles`, flattened in order (the server writes them, 06). */
+export function styleTexts(styles) {
+    if (styles === undefined)
+        return [];
+    if (typeof styles === 'string')
+        return [styles];
+    if (isStyleSource(styles))
+        return [styles.text];
+    return styles.flatMap(styleTexts);
+}
+const bySource = new WeakMap();
+const byText = new Map();
+function sheetOf(text) {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(text);
+    return sheet;
+}
+/** One shared sheet per style source (or per distinct string), created on first use. */
+export function sheetsFor(styles) {
+    if (styles === undefined)
+        return [];
+    if (typeof styles === 'string') {
+        let sheet = byText.get(styles);
+        if (sheet === undefined) {
+            sheet = sheetOf(styles);
+            byText.set(styles, sheet);
+        }
+        return [sheet];
+    }
+    if (isStyleSource(styles)) {
+        let sheet = bySource.get(styles);
+        if (sheet === undefined) {
+            sheet = sheetOf(styles.text);
+            bySource.set(styles, sheet);
+        }
+        return [sheet];
+    }
+    return styles.flatMap(sheetsFor);
+}
+//# sourceMappingURL=styles.js.map

package/dist/view/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/view/styles.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,+FAA+F;AAC/F,8FAA8F;AAC9F,2FAA2F;AAE3F,MAAM,KAAK,GAAkB,MAAM,CAAC,WAAW,CAAC,CAAC;AAkBjD,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,IAAI,KAAK,CAAC;AAEhE;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,OAA6B,EAAE,GAAG,MAA2B;IAC/E,IAAI,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,MAA0B;IACnD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,QAAQ,GAAG,IAAI,OAAO,EAA8B,CAAC;AAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEhD,SAAS,OAAO,CAAC,IAAY;IAC3B,MAAM,KAAK,GAAG,IAAI,aAAa,EAAE,CAAC;IAClC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,SAAS,CAAC,MAA0B;IAClD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YACxB,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC7B,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AACnC,CAAC","sourcesContent":["// Component styles (view/08-styles.md \"Authoring\", \"Browser\"): the `css` tag and the shared\n// sheets. A style source is CSS text plus a cache slot for its one `CSSStyleSheet`, created on\n// first use with `replaceSync`; components that share a source share the sheet. Plain strings\n// are style sources too (cached by text). The server reads the text (06), never the sheet.\n\nconst STYLE: unique symbol = Symbol('gyral.css');\n\n/** What `css` returns: CSS text, mapped to one shared `CSSStyleSheet` in the browser. */\nexport interface StyleSource {\n  readonly [STYLE]: true;\n  readonly text: string;\n}\n\n/**\n * What `spec.styles` accepts: `css` values, plain CSS strings (e.g.\n * `import base from './base.css?inline'`) and arrays of them, nested freely. CSS is trusted\n * author code: never interpolate user input.\n */\nexport type Styles = StyleSource | string | readonly Styles[];\n\n/** A `css` interpolation: inserted as written (another `css` value inserts its text). */\nexport type CssValue = string | number | StyleSource;\n\nexport const isStyleSource = (value: unknown): value is StyleSource =>\n  typeof value === 'object' && value !== null && STYLE in value;\n\n/**\n * Component CSS: `` css`p { margin-block: ${GAP}px; }` ``. Strings and numbers are inserted as\n * written, so values from your own constants need no wrapper.\n */\nexport function css(strings: TemplateStringsArray, ...values: readonly CssValue[]): StyleSource {\n  let text = strings[0] ?? '';\n  for (let i = 0; i < values.length; i++) {\n    const v = values[i];\n    text += (isStyleSource(v) ? v.text : String(v)) + (strings[i + 1] ?? '');\n  }\n  return { [STYLE]: true, text };\n}\n\n/** The CSS texts of `styles`, flattened in order (the server writes them, 06). */\nexport function styleTexts(styles: Styles | undefined): string[] {\n  if (styles === undefined) return [];\n  if (typeof styles === 'string') return [styles];\n  if (isStyleSource(styles)) return [styles.text];\n  return styles.flatMap(styleTexts);\n}\n\nconst bySource = new WeakMap<StyleSource, CSSStyleSheet>();\nconst byText = new Map<string, CSSStyleSheet>();\n\nfunction sheetOf(text: string): CSSStyleSheet {\n  const sheet = new CSSStyleSheet();\n  sheet.replaceSync(text);\n  return sheet;\n}\n\n/** One shared sheet per style source (or per distinct string), created on first use. */\nexport function sheetsFor(styles: Styles | undefined): CSSStyleSheet[] {\n  if (styles === undefined) return [];\n  if (typeof styles === 'string') {\n    let sheet = byText.get(styles);\n    if (sheet === undefined) {\n      sheet = sheetOf(styles);\n      byText.set(styles, sheet);\n    }\n    return [sheet];\n  }\n  if (isStyleSource(styles)) {\n    let sheet = bySource.get(styles);\n    if (sheet === undefined) {\n      sheet = sheetOf(styles.text);\n      bySource.set(styles, sheet);\n    }\n    return [sheet];\n  }\n  return styles.flatMap(sheetsFor);\n}\n"]}

package/dist/view/template-element.d.ts

@@ -0,0 +1,10 @@
+import type { TemplateObject } from './normalize/types.js';
+/** The cached <template> element for `template`, parsed (and checked) on first use. */
+export declare function templateElement(template: TemplateObject): HTMLTemplateElement;
+/**
+ * Prepares an svg template's <template> element (01 "svg templates"): its HTML is parsed inside
+ * an <svg>, so the parser creates SVG elements (camelCase names and attributes, namespaced
+ * static attributes), and that <svg>'s children become the content. Called with every svg
+ * result, before anything renders it; outside a document (the server) there is nothing to do.
+ */
+export declare function svgTemplate(template: TemplateObject): void;