@gyral/core 0.3.0 → 0.3.2

package/dist/eslint/unused-intent-rule.js

@@ -0,0 +1,186 @@
+import { findVariable, importedAs, isGyral, OPTIONS_SCHEMA, } from './imports.js';
+/**
+ * A static `data-intent` or `data-intent-<event>` value in template text (not `data-intent-on`,
+ * whose value is events).
+ */
+const STATIC_INTENT = /\sdata-intent(?:-(?!on=)[\w-]+)?=["']?([^"'\s>]+)/g;
+/** Template text that ends where a `data-intent` or `data-intent-<event>` hole starts. */
+const INTENT_HOLE = /\sdata-intent(?:-(?!on=)[\w-]+)?=["']?$/;
+const isFn = (node) => node?.type === 'ArrowFunctionExpression' ||
+    node?.type === 'FunctionExpression' ||
+    node?.type === 'FunctionDeclaration';
+const keyName = (key) => key.type === 'Identifier'
+    ? key.name
+    : key.type === 'Literal' && typeof key.value === 'string'
+        ? key.value
+        : undefined;
+/** `{ name: value }` entries of an object literal, without spreads or computed keys. */
+function entries(object) {
+    if (object.type !== 'ObjectExpression')
+        return [];
+    return object.properties.flatMap((p) => {
+        if (p.type !== 'Property' || p.computed)
+            return [];
+        const name = keyName(p.key);
+        return name === undefined ? [] : [{ name, key: p.key, value: p.value }];
+    });
+}
+/** Whether a variable is bound in this module (not imported, not a global). */
+const isLocal = (variable) => variable !== undefined && variable.defs.length > 0 && variable.defs[0]?.type !== 'ImportBinding';
+/** The function a view is: inline, or a module binding to one; undefined when elsewhere. */
+function viewFunction(context, view) {
+    if (isFn(view))
+        return view;
+    if (view.type !== 'Identifier')
+        return undefined;
+    const variable = findVariable(context.sourceCode.getScope(view), view.name);
+    const def = variable?.defs[0];
+    if (def?.type === 'FunctionName')
+        return def.node;
+    const init = def?.type === 'Variable' ? def.node.init : null;
+    return isFn(init) ? init : undefined;
+}
+/** Whether `tag` is Gyral's `html` or `svg` (an svg fragment can name intents too). */
+const isTemplateTag = (context, tag) => isGyral(context, tag, 'html') || isGyral(context, tag, 'svg');
+/** Whether `node` sits in a hole of a Gyral html or svg template. */
+function inTemplateHole(context, node) {
+    for (let n = node; n !== null; n = n.parent) {
+        const parent = n.parent;
+        if (parent?.type !== 'TemplateLiteral' || parent.parent.type !== 'TaggedTemplateExpression') {
+            continue;
+        }
+        if (isTemplateTag(context, parent.parent.tag))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether a template in the module calls, or passes on, a function imported from a module that
+ * isn't a template source: its markup, which this rule can't see, may name intents.
+ */
+function templatesCallImports(context, program) {
+    const global = context.sourceCode.getScope(program);
+    const module = global.childScopes.find((scope) => scope.type === 'module') ?? global;
+    return module.variables.some((v) => {
+        const def = v.defs[0];
+        if (def?.type !== 'ImportBinding')
+            return false;
+        if (importedAs(context, def.name) !== undefined)
+            return false; // core
+        return v.references.some((r) => {
+            const id = r.identifier;
+            return id.parent?.type === 'CallExpression' && inTemplateHole(context, id);
+        });
+    });
+}
+/** Whether `id`'s reference stays in the module: `id.Name`, or an argument to a local function. */
+function staysLocal(context, id) {
+    const parent = id.parent;
+    if (parent === null)
+        return false;
+    if (parent.type === 'MemberExpression' && parent.object === id)
+        return true;
+    if (parent.type !== 'CallExpression' || parent.callee === id)
+        return false;
+    const callee = parent.callee;
+    if (callee.type !== 'Identifier')
+        return false;
+    return isLocal(findVariable(context.sourceCode.getScope(callee), callee.name));
+}
+/** Whether the view's intents parameter (its second) can reach code outside the module. */
+function viewEscapes(context, fn) {
+    const param = fn.params[1];
+    if (param?.type !== 'Identifier')
+        return false; // absent, or destructured (counted as used)
+    const variable = context.sourceCode.getDeclaredVariables(fn).find((v) => v.name === param.name);
+    return (variable?.references ?? []).some((r) => !staysLocal(context, r.identifier));
+}
+export const unusedIntentRule = {
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'An intent parser that no template in the module names with data-intent: a renamed ' +
+                'intent or dead code (view/09-template-rules.md "Warnings").',
+            recommended: true,
+            url: 'https://github.com/gyraljs/gyral/blob/main/docs/design-docs/view/09-template-rules.md',
+        },
+        schema: OPTIONS_SCHEMA,
+        messages: {
+            unused: 'The intent parser "{{name}}" is never named by data-intent in this module, so it never ' +
+                'runs: name it in the view (data-intent=${i.{{name}}}), or remove the parser (messages ' +
+                'that only come from commands need none) (view/09-template-rules.md "Warnings").',
+        },
+    },
+    create(context) {
+        const used = new Set();
+        const components = [];
+        let exportsIntents = false;
+        return {
+            MemberExpression(node) {
+                const name = node.computed ? keyName(node.property) : undefined;
+                if (!node.computed && node.property.type === 'Identifier')
+                    used.add(node.property.name);
+                else if (name !== undefined)
+                    used.add(name);
+            },
+            ObjectPattern(node) {
+                for (const p of node.properties) {
+                    const name = p.type === 'Property' && !p.computed ? keyName(p.key) : undefined;
+                    if (name !== undefined)
+                        used.add(name);
+                }
+            },
+            TaggedTemplateExpression(node) {
+                if (!isTemplateTag(context, node.tag))
+                    return;
+                const { quasis, expressions } = node.quasi;
+                quasis.forEach((q, k) => {
+                    const text = q.value.cooked ?? '';
+                    for (const m of text.matchAll(STATIC_INTENT))
+                        used.add(m[1] ?? '');
+                    const value = expressions[k];
+                    if (INTENT_HOLE.test(text) && value?.type === 'Literal')
+                        used.add(String(value.value));
+                });
+            },
+            CallExpression(node) {
+                const callee = node.callee;
+                if (isGyral(context, callee, 'intentsOf')) {
+                    // `export const i = intentsOf<typeof C>()`: other modules may name the intents.
+                    const declaration = node.parent.parent?.parent;
+                    if (declaration?.type === 'ExportNamedDeclaration')
+                        exportsIntents = true;
+                    return;
+                }
+                // `define<S, M>()(tag, spec)`: the spec is the second argument of the second call.
+                if (callee.type !== 'CallExpression' ||
+                    !isGyral(context, callee.callee, 'define')) {
+                    return;
+                }
+                const spec = node.arguments[1];
+                const fields = spec === undefined ? [] : entries(spec);
+                const intent = fields.find((f) => f.name === 'intent')?.value;
+                const view = fields.find((f) => f.name === 'view')?.value;
+                if (intent === undefined)
+                    return;
+                const parsers = entries(intent).map((e) => ({ name: e.name, node: e.key }));
+                components.push({ parsers, view: view && viewFunction(context, view) });
+            },
+            'Program:exit'(program) {
+                if (exportsIntents || components.length === 0)
+                    return;
+                if (templatesCallImports(context, program))
+                    return;
+                for (const { parsers, view } of components) {
+                    if (view === undefined || viewEscapes(context, view))
+                        continue;
+                    for (const { name, node } of parsers) {
+                        if (!used.has(name))
+                            context.report({ node, messageId: 'unused', data: { name } });
+                    }
+                }
+            },
+        };
+    },
+};
+//# sourceMappingURL=unused-intent-rule.js.map

package/dist/eslint/unused-intent-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unused-intent-rule.js","sourceRoot":"","sources":["../../src/eslint/unused-intent-rule.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,YAAY,EACZ,UAAU,EACV,OAAO,EACP,cAAc,GAGf,MAAM,cAAc,CAAC;AAEtB;;;GAGG;AACH,MAAM,aAAa,GAAG,oDAAoD,CAAC;AAC3E,0FAA0F;AAC1F,MAAM,WAAW,GAAG,yCAAyC,CAAC;AAU9D,MAAM,IAAI,GAAG,CAAC,IAA6B,EAAc,EAAE,CACzD,IAAI,EAAE,IAAI,KAAK,yBAAyB;IACxC,IAAI,EAAE,IAAI,KAAK,oBAAoB;IACnC,IAAI,EAAE,IAAI,KAAK,qBAAqB,CAAC;AAEvC,MAAM,OAAO,GAAG,CAAC,GAAS,EAAsB,EAAE,CAChD,GAAG,CAAC,IAAI,KAAK,YAAY;IACvB,CAAC,CAAC,GAAG,CAAC,IAAI;IACV,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QACvD,CAAC,CAAC,GAAG,CAAC,KAAK;QACX,CAAC,CAAC,SAAS,CAAC;AAElB,wFAAwF;AACxF,SAAS,OAAO,CAAC,MAAY;IAC3B,IAAI,MAAM,CAAC,IAAI,KAAK,kBAAkB;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;QACrC,IAAI,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,QAAQ;YAAE,OAAO,EAAE,CAAC;QACnD,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,GAAW,CAAC,CAAC;QACpC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAW,EAAE,KAAK,EAAE,CAAC,CAAC,KAAa,EAAE,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,MAAM,OAAO,GAAG,CAAC,QAAoC,EAAW,EAAE,CAChE,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,eAAe,CAAC;AAEnG,4FAA4F;AAC5F,SAAS,YAAY,CAAC,OAAyB,EAAE,IAAU;IACzD,IAAI,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,SAAS,CAAC;IACjD,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,GAAG,EAAE,IAAI,KAAK,cAAc;QAAE,OAAO,GAAG,CAAC,IAAU,CAAC;IACxD,MAAM,IAAI,GAAG,GAAG,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAE,GAAG,CAAC,IAAI,CAAC,IAAoB,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9E,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACvC,CAAC;AAED,uFAAuF;AACvF,MAAM,aAAa,GAAG,CAAC,OAAyB,EAAE,GAAS,EAAW,EAAE,CACtE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEhE,qEAAqE;AACrE,SAAS,cAAc,CAAC,OAAyB,EAAE,IAAU;IAC3D,KAAK,IAAI,CAAC,GAAgB,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;QACxB,IAAI,MAAM,EAAE,IAAI,KAAK,iBAAiB,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,0BAA0B,EAAE,CAAC;YAC5F,SAAS;QACX,CAAC;QACD,IAAI,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,GAAW,CAAC;YAAE,OAAO,IAAI,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,OAAyB,EAAE,OAAa;IACpE,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,MAAM,CAAC;IACrF,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;QACjC,MAAM,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,GAAG,EAAE,IAAI,KAAK,eAAe;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,IAA4B,CAAC,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,CAAC,OAAO;QAC9F,OAAO,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;YAC7B,MAAM,EAAE,GAAG,CAAC,CAAC,UAAkB,CAAC;YAChC,OAAO,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,gBAAgB,IAAI,cAAc,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC7E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,mGAAmG;AACnG,SAAS,UAAU,CAAC,OAAyB,EAAE,EAAQ;IACrD,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;IACzB,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,MAAM,CAAC,IAAI,KAAK,kBAAkB,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC5E,IAAI,MAAM,CAAC,IAAI,KAAK,gBAAgB,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC3E,MAAM,MAAM,GAAG,MAAM,CAAC,MAAc,CAAC;IACrC,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,2FAA2F;AAC3F,SAAS,WAAW,CAAC,OAAyB,EAAE,EAAM;IACpD,MAAM,KAAK,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAqB,CAAC;IAC/C,IAAI,KAAK,EAAE,IAAI,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC,CAAC,4CAA4C;IAC5F,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC;IAChG,OAAO,CAAC,QAAQ,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,UAAkB,CAAC,CAAC,CAAC;AAC9F,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C,IAAI,EAAE;QACJ,IAAI,EAAE,YAAY;QAClB,IAAI,EAAE;YACJ,WAAW,EACT,oFAAoF;gBACpF,6DAA6D;YAC/D,WAAW,EAAE,IAAI;YACjB,GAAG,EAAE,uFAAuF;SAC7F;QACD,MAAM,EAAE,cAAc;QACtB,QAAQ,EAAE;YACR,MAAM,EACJ,yFAAyF;gBACzF,wFAAwF;gBACxF,iFAAiF;SACpF;KACF;IACD,MAAM,CAAC,OAAO;QACZ,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,UAAU,GAAgB,EAAE,CAAC;QACnC,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,OAAO;YACL,gBAAgB,CAAC,IAAI;gBACnB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,QAAgB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACxE,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,YAAY;oBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;qBACnF,IAAI,IAAI,KAAK,SAAS;oBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9C,CAAC;YACD,aAAa,CAAC,IAAI;gBAChB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChC,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;oBACvF,IAAI,IAAI,KAAK,SAAS;wBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACzC,CAAC;YACH,CAAC;YACD,wBAAwB,CAAC,IAAI;gBAC3B,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,GAAW,CAAC;oBAAE,OAAO;gBACtD,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;gBAC3C,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;oBACtB,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC;oBAClC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC;wBAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;oBACnE,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAqB,CAAC;oBACjD,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,EAAE,IAAI,KAAK,SAAS;wBAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;gBACzF,CAAC,CAAC,CAAC;YACL,CAAC;YACD,cAAc,CAAC,IAAI;gBACjB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAc,CAAC;gBACnC,IAAI,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC;oBAC1C,gFAAgF;oBAChF,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;oBAC/C,IAAI,WAAW,EAAE,IAAI,KAAK,wBAAwB;wBAAE,cAAc,GAAG,IAAI,CAAC;oBAC1E,OAAO;gBACT,CAAC;gBACD,mFAAmF;gBACnF,IACE,MAAM,CAAC,IAAI,KAAK,gBAAgB;oBAChC,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAc,EAAE,QAAQ,CAAC,EAClD,CAAC;oBACD,OAAO;gBACT,CAAC;gBACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAqB,CAAC;gBACnD,MAAM,MAAM,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACvD,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,EAAE,KAAK,CAAC;gBAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC;gBAC1D,IAAI,MAAM,KAAK,SAAS;oBAAE,OAAO;gBACjC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC5E,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,IAAI,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1E,CAAC;YACD,cAAc,CAAC,OAAO;gBACpB,IAAI,cAAc,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO;gBACtD,IAAI,oBAAoB,CAAC,OAAO,EAAE,OAAe,CAAC;oBAAE,OAAO;gBAC3D,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,UAAU,EAAE,CAAC;oBAC3C,IAAI,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC;wBAAE,SAAS;oBAC/D,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,OAAO,EAAE,CAAC;wBACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;4BAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;oBACrF,CAAC;gBACH,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC","sourcesContent":["// gyral/unused-intent: the \"unused intent parser\" warning of view/09-template-rules.md. A parser\n// in `define<S, M>()(tag, { intent: { Name: … } })` runs only when an element names it with\n// `data-intent`, so a parser no template in the module names is a renamed intent, dead code, or\n// (since intent names are inferred from these keys, ADR 0023) a misspelled key.\n// Static, over the whole module, so intents rendered conditionally (a dialog's buttons, an\n// error state) count as used; that is why the warning lives here and not in the runtime, which\n// sees only the templates rendered so far. A name counts as used when the module mentions it as\n// a property (`i.Name`, `{ Name } = i`, `i['Name']`) or as a static or literal `data-intent` or\n// `data-intent-<event>` value in an html or svg template. A component is skipped when its intent\n// names may be used elsewhere: its view is not in the module (an imported function), the view\n// hands its intents to an imported function, the module exports an `intentsOf()` constant, or a\n// template in the module calls (or passes on) a function imported from another module, which\n// may render `data-intent=\"Name\"` itself (a shared table header, a row module).\nimport type { Rule, Scope } from 'eslint';\nimport {\n  findVariable,\n  importedAs,\n  isGyral,\n  OPTIONS_SCHEMA,\n  type Node,\n  type NodeOf,\n} from './imports.js';\n\n/**\n * A static `data-intent` or `data-intent-<event>` value in template text (not `data-intent-on`,\n * whose value is events).\n */\nconst STATIC_INTENT = /\\sdata-intent(?:-(?!on=)[\\w-]+)?=[\"']?([^\"'\\s>]+)/g;\n/** Template text that ends where a `data-intent` or `data-intent-<event>` hole starts. */\nconst INTENT_HOLE = /\\sdata-intent(?:-(?!on=)[\\w-]+)?=[\"']?$/;\n\ninterface Component {\n  readonly parsers: readonly { readonly name: string; readonly node: Node }[];\n  readonly view: Fn | undefined;\n}\n\ntype Fn =\n  NodeOf<'ArrowFunctionExpression'> | NodeOf<'FunctionExpression'> | NodeOf<'FunctionDeclaration'>;\n\nconst isFn = (node: Node | null | undefined): node is Fn =>\n  node?.type === 'ArrowFunctionExpression' ||\n  node?.type === 'FunctionExpression' ||\n  node?.type === 'FunctionDeclaration';\n\nconst keyName = (key: Node): string | undefined =>\n  key.type === 'Identifier'\n    ? key.name\n    : key.type === 'Literal' && typeof key.value === 'string'\n      ? key.value\n      : undefined;\n\n/** `{ name: value }` entries of an object literal, without spreads or computed keys. */\nfunction entries(object: Node): { name: string; key: Node; value: Node }[] {\n  if (object.type !== 'ObjectExpression') return [];\n  return object.properties.flatMap((p) => {\n    if (p.type !== 'Property' || p.computed) return [];\n    const name = keyName(p.key as Node);\n    return name === undefined ? [] : [{ name, key: p.key as Node, value: p.value as Node }];\n  });\n}\n\n/** Whether a variable is bound in this module (not imported, not a global). */\nconst isLocal = (variable: Scope.Variable | undefined): boolean =>\n  variable !== undefined && variable.defs.length > 0 && variable.defs[0]?.type !== 'ImportBinding';\n\n/** The function a view is: inline, or a module binding to one; undefined when elsewhere. */\nfunction viewFunction(context: Rule.RuleContext, view: Node): Fn | undefined {\n  if (isFn(view)) return view;\n  if (view.type !== 'Identifier') return undefined;\n  const variable = findVariable(context.sourceCode.getScope(view), view.name);\n  const def = variable?.defs[0];\n  if (def?.type === 'FunctionName') return def.node as Fn;\n  const init = def?.type === 'Variable' ? (def.node.init as Node | null) : null;\n  return isFn(init) ? init : undefined;\n}\n\n/** Whether `tag` is Gyral's `html` or `svg` (an svg fragment can name intents too). */\nconst isTemplateTag = (context: Rule.RuleContext, tag: Node): boolean =>\n  isGyral(context, tag, 'html') || isGyral(context, tag, 'svg');\n\n/** Whether `node` sits in a hole of a Gyral html or svg template. */\nfunction inTemplateHole(context: Rule.RuleContext, node: Node): boolean {\n  for (let n: Node | null = node; n !== null; n = n.parent) {\n    const parent = n.parent;\n    if (parent?.type !== 'TemplateLiteral' || parent.parent.type !== 'TaggedTemplateExpression') {\n      continue;\n    }\n    if (isTemplateTag(context, parent.parent.tag as Node)) return true;\n  }\n  return false;\n}\n\n/**\n * Whether a template in the module calls, or passes on, a function imported from a module that\n * isn't a template source: its markup, which this rule can't see, may name intents.\n */\nfunction templatesCallImports(context: Rule.RuleContext, program: Node): boolean {\n  const global = context.sourceCode.getScope(program);\n  const module = global.childScopes.find((scope) => scope.type === 'module') ?? global;\n  return module.variables.some((v) => {\n    const def = v.defs[0];\n    if (def?.type !== 'ImportBinding') return false;\n    if (importedAs(context, def.name as NodeOf<'Identifier'>) !== undefined) return false; // core\n    return v.references.some((r) => {\n      const id = r.identifier as Node;\n      return id.parent?.type === 'CallExpression' && inTemplateHole(context, id);\n    });\n  });\n}\n\n/** Whether `id`'s reference stays in the module: `id.Name`, or an argument to a local function. */\nfunction staysLocal(context: Rule.RuleContext, id: Node): boolean {\n  const parent = id.parent;\n  if (parent === null) return false;\n  if (parent.type === 'MemberExpression' && parent.object === id) return true;\n  if (parent.type !== 'CallExpression' || parent.callee === id) return false;\n  const callee = parent.callee as Node;\n  if (callee.type !== 'Identifier') return false;\n  return isLocal(findVariable(context.sourceCode.getScope(callee), callee.name));\n}\n\n/** Whether the view's intents parameter (its second) can reach code outside the module. */\nfunction viewEscapes(context: Rule.RuleContext, fn: Fn): boolean {\n  const param = fn.params[1] as Node | undefined;\n  if (param?.type !== 'Identifier') return false; // absent, or destructured (counted as used)\n  const variable = context.sourceCode.getDeclaredVariables(fn).find((v) => v.name === param.name);\n  return (variable?.references ?? []).some((r) => !staysLocal(context, r.identifier as Node));\n}\n\nexport const unusedIntentRule: Rule.RuleModule = {\n  meta: {\n    type: 'suggestion',\n    docs: {\n      description:\n        'An intent parser that no template in the module names with data-intent: a renamed ' +\n        'intent or dead code (view/09-template-rules.md \"Warnings\").',\n      recommended: true,\n      url: 'https://github.com/gyraljs/gyral/blob/main/docs/design-docs/view/09-template-rules.md',\n    },\n    schema: OPTIONS_SCHEMA,\n    messages: {\n      unused:\n        'The intent parser \"{{name}}\" is never named by data-intent in this module, so it never ' +\n        'runs: name it in the view (data-intent=${i.{{name}}}), or remove the parser (messages ' +\n        'that only come from commands need none) (view/09-template-rules.md \"Warnings\").',\n    },\n  },\n  create(context) {\n    const used = new Set<string>();\n    const components: Component[] = [];\n    let exportsIntents = false;\n    return {\n      MemberExpression(node) {\n        const name = node.computed ? keyName(node.property as Node) : undefined;\n        if (!node.computed && node.property.type === 'Identifier') used.add(node.property.name);\n        else if (name !== undefined) used.add(name);\n      },\n      ObjectPattern(node) {\n        for (const p of node.properties) {\n          const name = p.type === 'Property' && !p.computed ? keyName(p.key as Node) : undefined;\n          if (name !== undefined) used.add(name);\n        }\n      },\n      TaggedTemplateExpression(node) {\n        if (!isTemplateTag(context, node.tag as Node)) return;\n        const { quasis, expressions } = node.quasi;\n        quasis.forEach((q, k) => {\n          const text = q.value.cooked ?? '';\n          for (const m of text.matchAll(STATIC_INTENT)) used.add(m[1] ?? '');\n          const value = expressions[k] as Node | undefined;\n          if (INTENT_HOLE.test(text) && value?.type === 'Literal') used.add(String(value.value));\n        });\n      },\n      CallExpression(node) {\n        const callee = node.callee as Node;\n        if (isGyral(context, callee, 'intentsOf')) {\n          // `export const i = intentsOf<typeof C>()`: other modules may name the intents.\n          const declaration = node.parent.parent?.parent;\n          if (declaration?.type === 'ExportNamedDeclaration') exportsIntents = true;\n          return;\n        }\n        // `define<S, M>()(tag, spec)`: the spec is the second argument of the second call.\n        if (\n          callee.type !== 'CallExpression' ||\n          !isGyral(context, callee.callee as Node, 'define')\n        ) {\n          return;\n        }\n        const spec = node.arguments[1] as Node | undefined;\n        const fields = spec === undefined ? [] : entries(spec);\n        const intent = fields.find((f) => f.name === 'intent')?.value;\n        const view = fields.find((f) => f.name === 'view')?.value;\n        if (intent === undefined) return;\n        const parsers = entries(intent).map((e) => ({ name: e.name, node: e.key }));\n        components.push({ parsers, view: view && viewFunction(context, view) });\n      },\n      'Program:exit'(program) {\n        if (exportsIntents || components.length === 0) return;\n        if (templatesCallImports(context, program as Node)) return;\n        for (const { parsers, view } of components) {\n          if (view === undefined || viewEscapes(context, view)) continue;\n          for (const { name, node } of parsers) {\n            if (!used.has(name)) context.report({ node, messageId: 'unused', data: { name } });\n          }\n        }\n      },\n    };\n  },\n};\n"]}

package/dist/features.d.ts

@@ -1,5 +1,5 @@
 import type { DriverOverrides } from './command.js';
-import type { Interpreter } from './internal/interpreter.js';
+import type { CommandFailure, Interpreter } from './internal/interpreter.js';
 import type { PropFeature } from './props.js';
 import type { AnyStore, StoreOverrides, StoreRef, StoreSendInput } from './store.js';
 import type { CommandTrace } from './devtools-events.js';
@@ -30,7 +30,7 @@ export interface LocalDriver {
 type Msg = Tagged | IntentRejected;
 export declare const features: {
     /** Set by `command()`: a host's command interpreter, resolving drivers by name (ADR 0006). */
-    commands?: (el: FeatureHost, drivers: DriverOverrides | undefined, dispatch: (msg: Msg) => void, trace: CommandTrace | undefined) => Interpreter<Msg>;
+    commands?: (el: FeatureHost, dispatch: (msg: Msg) => void, trace: CommandTrace | undefined, failed: CommandFailure) => Interpreter<Msg>;
     /** Set by `defineStore()`: binds a host to the stores it declares (ADR 0013). */
     stores?: (el: FeatureHost, tag: string, declared: readonly AnyStore[], onChange: (store: AnyStore, state: unknown, prev: unknown) => void) => StoreLink;
     /** Set by the prop builders: attribute parsing and validation (view/05 "Props"). */

package/dist/features.js.map

@@ -1 +1 @@
-{"version":3,"file":"features.js","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAsCA,MAAM,CAAC,MAAM,QAAQ,GAiBjB,EAAE,CAAC","sourcesContent":["// Features that register themselves when their API is used (ADR 0018 \"Size\", gyral-g1r.18).\n// Core reaches them only through these slots, which the feature's own API fills when called:\n// `command()` the interpreter, `defineStore()` the store binding, a prop builder the prop\n// machinery. An app that never calls one doesn't bundle what it registers. No module does this\n// at load time: bundlers keep `sideEffects: false` and tree-shake as usual.\nimport type { DriverOverrides } from './command.js';\nimport type { Interpreter } from './internal/interpreter.js';\nimport type { PropFeature } from './props.js';\nimport type { AnyStore, StoreOverrides, StoreRef, StoreSendInput } from './store.js';\nimport type { CommandTrace } from './devtools-events.js';\nimport type { IntentRejected, Tagged } from './types.js';\n\n/** A host's element, as features see it. */\nexport type FeatureHost = HTMLElement & { drivers: DriverOverrides; stores: StoreOverrides };\n\n/** What a component's store binding offers its model (store-binding.ts). */\nexport interface StoreLink {\n  read<S>(ref: StoreRef<S>): S;\n  send(input: StoreSendInput): void;\n  connect(): boolean;\n  disconnect(): void;\n}\n\n/** The host a marker driver's `local` handler runs against (focus, emit, store send). */\nexport interface LocalHost {\n  readonly el: FeatureHost;\n  readonly tag: string;\n  readonly root: () => ParentNode | undefined;\n  readonly stores: () => StoreLink;\n}\n\n/** A marker driver core runs itself, synchronously, without the interpreter. */\nexport interface LocalDriver {\n  readonly local: (host: LocalHost, input: unknown) => void;\n}\n\ntype Msg = Tagged | IntentRejected;\n\nexport const features: {\n  /** Set by `command()`: a host's command interpreter, resolving drivers by name (ADR 0006). */\n  commands?: (\n    el: FeatureHost,\n    drivers: DriverOverrides | undefined,\n    dispatch: (msg: Msg) => void,\n    trace: CommandTrace | undefined,\n  ) => Interpreter<Msg>;\n  /** Set by `defineStore()`: binds a host to the stores it declares (ADR 0013). */\n  stores?: (\n    el: FeatureHost,\n    tag: string,\n    declared: readonly AnyStore[],\n    onChange: (store: AnyStore, state: unknown, prev: unknown) => void,\n  ) => StoreLink;\n  /** Set by the prop builders: attribute parsing and validation (view/05 \"Props\"). */\n  props?: PropFeature;\n} = {};\n"]}
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAsCA,MAAM,CAAC,MAAM,QAAQ,GAiBjB,EAAE,CAAC","sourcesContent":["// Features that register themselves when their API is used (ADR 0018 \"Size\", gyral-g1r.18).\n// Core reaches them only through these slots, which the feature's own API fills when called:\n// `command()` the interpreter, `defineStore()` the store binding, a prop builder the prop\n// machinery. An app that never calls one doesn't bundle what it registers. No module does this\n// at load time: bundlers keep `sideEffects: false` and tree-shake as usual.\nimport type { DriverOverrides } from './command.js';\nimport type { CommandFailure, Interpreter } from './internal/interpreter.js';\nimport type { PropFeature } from './props.js';\nimport type { AnyStore, StoreOverrides, StoreRef, StoreSendInput } from './store.js';\nimport type { CommandTrace } from './devtools-events.js';\nimport type { IntentRejected, Tagged } from './types.js';\n\n/** A host's element, as features see it. */\nexport type FeatureHost = HTMLElement & { drivers: DriverOverrides; stores: StoreOverrides };\n\n/** What a component's store binding offers its model (store-binding.ts). */\nexport interface StoreLink {\n  read<S>(ref: StoreRef<S>): S;\n  send(input: StoreSendInput): void;\n  connect(): boolean;\n  disconnect(): void;\n}\n\n/** The host a marker driver's `local` handler runs against (focus, emit, store send). */\nexport interface LocalHost {\n  readonly el: FeatureHost;\n  readonly tag: string;\n  readonly root: () => ParentNode | undefined;\n  readonly stores: () => StoreLink;\n}\n\n/** A marker driver core runs itself, synchronously, without the interpreter. */\nexport interface LocalDriver {\n  readonly local: (host: LocalHost, input: unknown) => void;\n}\n\ntype Msg = Tagged | IntentRejected;\n\nexport const features: {\n  /** Set by `command()`: a host's command interpreter, resolving drivers by name (ADR 0006). */\n  commands?: (\n    el: FeatureHost,\n    dispatch: (msg: Msg) => void,\n    trace: CommandTrace | undefined,\n    failed: CommandFailure,\n  ) => Interpreter<Msg>;\n  /** Set by `defineStore()`: binds a host to the stores it declares (ADR 0013). */\n  stores?: (\n    el: FeatureHost,\n    tag: string,\n    declared: readonly AnyStore[],\n    onChange: (store: AnyStore, state: unknown, prev: unknown) => void,\n  ) => StoreLink;\n  /** Set by the prop builders: attribute parsing and validation (view/05 \"Props\"). */\n  props?: PropFeature;\n} = {};\n"]}

package/dist/focus.d.ts

@@ -11,6 +11,12 @@ export interface FocusOptions {
     readonly preventScroll?: boolean;
     /** Also select the text of an input or textarea. */
     readonly select?: boolean;
+    /**
+     * If nothing matches after this render, keep the request and focus the target as soon as a
+     * later render of this component produces it; a newer `focus()` from the component replaces
+     * it, and after one second it gives up with the usual warning. `settled()` doesn't wait for it.
+     */
+    readonly wait?: boolean;
 }
 /** The input of a `focus()` command. */
 export interface FocusInput extends FocusOptions {

package/dist/focus.js

@@ -1,4 +1,5 @@
 import { afterRender, POST_FOCUS } from './scheduler.js';
+import { message } from './view/index.js';
 /** Marker driver: the host runs focus commands itself (`local`). */
 export const FOCUS = {
     name: '@gyral/focus',
@@ -7,6 +8,10 @@ export const FOCUS = {
         queueFocus(host.el, host.root, host.tag, input);
     },
 };
+// How long `focus(selector, { wait: true })` waits for its target to appear.
+const FOCUS_WAIT_MS = 1000;
+// A component's waiting focus request, so the next focus() can cancel it.
+const waiting = new WeakMap();
 /**
  * A command that focuses the first element matching `selector` inside this component (its
  * shadow root, or its own children in light-DOM mode) once the current update has rendered:
@@ -23,7 +28,7 @@ export function focus(selector, options = {}) {
 export function runFocus(root, tag, input) {
     const target = root.querySelector(input.selector);
     if (!(target instanceof HTMLElement || target instanceof SVGElement)) {
-        console.warn(`<${tag}> focus("${input.selector}") matched no focusable element.`);
+        console.warn(message(13, tag, input.selector));
         return;
     }
     target.focus({ preventScroll: input.preventScroll ?? false });
@@ -37,9 +42,34 @@ export function runFocus(root, tag, input) {
  */
 export function queueFocus(host, root, tag, input) {
     afterRender(POST_FOCUS, () => {
+        waiting.get(host)?.();
         const target = root();
-        if (host.isConnected && target !== undefined)
+        if (!host.isConnected || target === undefined)
+            return;
+        if (input.wait !== true || target.querySelector(input.selector) !== null) {
             runFocus(target, tag, input);
+            return;
+        }
+        // Not rendered yet: watch the component's own DOM (renders are the only writers) until the
+        // target appears, a newer focus() cancels, or time runs out. settled() doesn't wait for it.
+        const stop = () => {
+            observer.disconnect();
+            clearTimeout(timer);
+            waiting.delete(host);
+        };
+        const observer = new MutationObserver(() => {
+            if (target.querySelector(input.selector) !== null) {
+                stop();
+                if (host.isConnected)
+                    runFocus(target, tag, input);
+            }
+        });
+        const timer = setTimeout(() => {
+            stop();
+            runFocus(target, tag, input);
+        }, FOCUS_WAIT_MS);
+        observer.observe(target, { childList: true, subtree: true, attributes: true });
+        waiting.set(host, stop);
     });
 }
 //# sourceMappingURL=focus.js.map

package/dist/focus.js.map

@@ -1 +1 @@
-{"version":3,"file":"focus.js","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEzD,oEAAoE;AACpE,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,IAAI,EAAE,cAAc;IACpB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,KAAK,EAAE,CAAC,IAAe,EAAE,KAAc,EAAE,EAAE;QACzC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,KAAmB,CAAC,CAAC;IAChE,CAAC;CACO,CAAC;AAcX;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,QAAgB,EAAE,UAAwB,EAAE;IAChE,MAAM,KAAK,GAAe,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IACnD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,GAAW,EAAE,KAAiB;IACvE,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,MAAM,YAAY,WAAW,IAAI,MAAM,YAAY,UAAU,CAAC,EAAE,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,IAAI,GAAG,YAAY,KAAK,CAAC,QAAQ,kCAAkC,CAAC,CAAC;QAClF,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,KAAK,EAAE,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,QAAQ,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACtF,MAA2B,CAAC,MAAM,EAAE,CAAC;IACxC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,IAAa,EACb,IAAkC,EAClC,GAAW,EACX,KAAiB;IAEjB,WAAW,CAAC,UAAU,EAAE,GAAG,EAAE;QAC3B,MAAM,MAAM,GAAG,IAAI,EAAE,CAAC;QACtB,IAAI,IAAI,CAAC,WAAW,IAAI,MAAM,KAAK,SAAS;YAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// Focus management from the model (gyral-czi.28). Moving focus is a side effect, so the model\n// asks for it with a command; define() queues it as the scheduler's first post-render work\n// (view/04-scheduler.md \"Post-render queue\"), against the component's own root, so the element\n// to focus already exists.\nimport type { Command } from './command.js';\nimport type { LocalHost } from './features.js';\nimport { afterRender, POST_FOCUS } from './scheduler.js';\n\n/** Marker driver: the host runs focus commands itself (`local`). */\nexport const FOCUS = {\n  name: '@gyral/focus',\n  run: () => undefined,\n  local: (host: LocalHost, input: unknown) => {\n    queueFocus(host.el, host.root, host.tag, input as FocusInput);\n  },\n} as const;\n\nexport interface FocusOptions {\n  /** Don't scroll the element into view (default `false`: the browser scrolls if needed). */\n  readonly preventScroll?: boolean;\n  /** Also select the text of an input or textarea. */\n  readonly select?: boolean;\n}\n\n/** The input of a `focus()` command. */\nexport interface FocusInput extends FocusOptions {\n  readonly selector: string;\n}\n\n/**\n * A command that focuses the first element matching `selector` inside this component (its\n * shadow root, or its own children in light-DOM mode) once the current update has rendered:\n *\n *   NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]\n *\n * Non-focusable targets (a heading) need `tabindex=\"-1\"` in the view.\n */\nexport function focus(selector: string, options: FocusOptions = {}): Command<never> {\n  const input: FocusInput = { selector, ...options };\n  return { driver: FOCUS, input, onSuccess: () => undefined };\n}\n\n/** Runs a focus command against `root` (the scheduler calls it after the render). */\nexport function runFocus(root: ParentNode, tag: string, input: FocusInput): void {\n  const target = root.querySelector(input.selector);\n  if (!(target instanceof HTMLElement || target instanceof SVGElement)) {\n    console.warn(`<${tag}> focus(\"${input.selector}\") matched no focusable element.`);\n    return;\n  }\n  target.focus({ preventScroll: input.preventScroll ?? false });\n  if (input.select === true && 'select' in target && typeof target.select === 'function') {\n    (target as HTMLInputElement).select();\n  }\n}\n\n/**\n * Runs a focus command after the flush that renders the same update, view transition\n * included: it is post-render work, so the DOM already shows the new state.\n */\nexport function queueFocus(\n  host: Element,\n  root: () => ParentNode | undefined,\n  tag: string,\n  input: FocusInput,\n): void {\n  afterRender(POST_FOCUS, () => {\n    const target = root();\n    if (host.isConnected && target !== undefined) runFocus(target, tag, input);\n  });\n}\n"]}
+{"version":3,"file":"focus.js","sourceRoot":"","sources":["../src/focus.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE1C,oEAAoE;AACpE,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,IAAI,EAAE,cAAc;IACpB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS;IACpB,KAAK,EAAE,CAAC,IAAe,EAAE,KAAc,EAAE,EAAE;QACzC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,KAAmB,CAAC,CAAC;IAChE,CAAC;CACO,CAAC;AAeX,6EAA6E;AAC7E,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B,0EAA0E;AAC1E,MAAM,OAAO,GAAG,IAAI,OAAO,EAAuB,CAAC;AAOnD;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,QAAgB,EAAE,UAAwB,EAAE;IAChE,MAAM,KAAK,GAAe,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IACnD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;AAC9D,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,GAAW,EAAE,KAAiB;IACvE,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC,MAAM,YAAY,WAAW,IAAI,MAAM,YAAY,UAAU,CAAC,EAAE,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC/C,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,KAAK,EAAE,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,QAAQ,IAAI,MAAM,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACtF,MAA2B,CAAC,MAAM,EAAE,CAAC;IACxC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CACxB,IAAa,EACb,IAAkC,EAClC,GAAW,EACX,KAAiB;IAEjB,WAAW,CAAC,UAAU,EAAE,GAAG,EAAE;QAC3B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QACtD,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;YACzE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC7B,OAAO;QACT,CAAC;QACD,2FAA2F;QAC3F,4FAA4F;QAC5F,MAAM,IAAI,GAAG,GAAS,EAAE;YACtB,QAAQ,CAAC,UAAU,EAAE,CAAC;YACtB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC,CAAC;QACF,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,GAAG,EAAE;YACzC,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;gBAClD,IAAI,EAAE,CAAC;gBACP,IAAI,IAAI,CAAC,WAAW;oBAAE,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YACrD,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,EAAE,CAAC;YACP,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC,EAAE,aAAa,CAAC,CAAC;QAClB,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/E,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["// Focus management from the model (gyral-czi.28). Moving focus is a side effect, so the model\n// asks for it with a command; define() queues it as the scheduler's first post-render work\n// (view/04-scheduler.md \"Post-render queue\"), against the component's own root, so the element\n// to focus already exists.\nimport type { Command } from './command.js';\nimport type { LocalHost } from './features.js';\nimport { afterRender, POST_FOCUS } from './scheduler.js';\nimport { message } from './view/index.js';\n\n/** Marker driver: the host runs focus commands itself (`local`). */\nexport const FOCUS = {\n  name: '@gyral/focus',\n  run: () => undefined,\n  local: (host: LocalHost, input: unknown) => {\n    queueFocus(host.el, host.root, host.tag, input as FocusInput);\n  },\n} as const;\n\nexport interface FocusOptions {\n  /** Don't scroll the element into view (default `false`: the browser scrolls if needed). */\n  readonly preventScroll?: boolean;\n  /** Also select the text of an input or textarea. */\n  readonly select?: boolean;\n  /**\n   * If nothing matches after this render, keep the request and focus the target as soon as a\n   * later render of this component produces it; a newer `focus()` from the component replaces\n   * it, and after one second it gives up with the usual warning. `settled()` doesn't wait for it.\n   */\n  readonly wait?: boolean;\n}\n\n// How long `focus(selector, { wait: true })` waits for its target to appear.\nconst FOCUS_WAIT_MS = 1000;\n\n// A component's waiting focus request, so the next focus() can cancel it.\nconst waiting = new WeakMap<Element, () => void>();\n\n/** The input of a `focus()` command. */\nexport interface FocusInput extends FocusOptions {\n  readonly selector: string;\n}\n\n/**\n * A command that focuses the first element matching `selector` inside this component (its\n * shadow root, or its own children in light-DOM mode) once the current update has rendered:\n *\n *   NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]\n *\n * Non-focusable targets (a heading) need `tabindex=\"-1\"` in the view.\n */\nexport function focus(selector: string, options: FocusOptions = {}): Command<never> {\n  const input: FocusInput = { selector, ...options };\n  return { driver: FOCUS, input, onSuccess: () => undefined };\n}\n\n/** Runs a focus command against `root` (the scheduler calls it after the render). */\nexport function runFocus(root: ParentNode, tag: string, input: FocusInput): void {\n  const target = root.querySelector(input.selector);\n  if (!(target instanceof HTMLElement || target instanceof SVGElement)) {\n    console.warn(message(13, tag, input.selector));\n    return;\n  }\n  target.focus({ preventScroll: input.preventScroll ?? false });\n  if (input.select === true && 'select' in target && typeof target.select === 'function') {\n    (target as HTMLInputElement).select();\n  }\n}\n\n/**\n * Runs a focus command after the flush that renders the same update, view transition\n * included: it is post-render work, so the DOM already shows the new state.\n */\nexport function queueFocus(\n  host: Element,\n  root: () => ParentNode | undefined,\n  tag: string,\n  input: FocusInput,\n): void {\n  afterRender(POST_FOCUS, () => {\n    waiting.get(host)?.();\n    const target = root();\n    if (!host.isConnected || target === undefined) return;\n    if (input.wait !== true || target.querySelector(input.selector) !== null) {\n      runFocus(target, tag, input);\n      return;\n    }\n    // Not rendered yet: watch the component's own DOM (renders are the only writers) until the\n    // target appears, a newer focus() cancels, or time runs out. settled() doesn't wait for it.\n    const stop = (): void => {\n      observer.disconnect();\n      clearTimeout(timer);\n      waiting.delete(host);\n    };\n    const observer = new MutationObserver(() => {\n      if (target.querySelector(input.selector) !== null) {\n        stop();\n        if (host.isConnected) runFocus(target, tag, input);\n      }\n    });\n    const timer = setTimeout(() => {\n      stop();\n      runFocus(target, tag, input);\n    }, FOCUS_WAIT_MS);\n    observer.observe(target, { childList: true, subtree: true, attributes: true });\n    waiting.set(host, stop);\n  });\n}\n"]}

package/dist/form-associated.d.ts

@@ -0,0 +1,46 @@
+import type { Ctx } from './types.js';
+import type { HostModel } from './host-model.js';
+/** A native submitted value, or null to omit this component from the submission. */
+export type FormControlValue = string | File | FormData | null;
+/** Native constraint flags and a validation bubble anchor in the component's render root. */
+export interface FormControlValidity {
+    readonly flags: ValidityStateFlags;
+    readonly message: string;
+    readonly anchor?: string;
+}
+/** Pure model projections applied by Gyral to the host's ElementInternals (ADR 0008). */
+export interface FormAssociation<S, P> {
+    readonly value: (state: S, ctx: Ctx<P>) => FormControlValue;
+    readonly state?: (state: S, ctx: Ctx<P>) => FormControlValue;
+    readonly validity?: (state: S, ctx: Ctx<P>) => FormControlValidity | undefined;
+}
+/** Framework message: the owning native form was reset. */
+export interface FormReset {
+    readonly _tag: 'FormReset';
+}
+/** Framework message: the host or its fieldset changed the effective disabled state. */
+export interface FormDisabled {
+    readonly _tag: 'FormDisabled';
+    readonly disabled: boolean;
+}
+/** Framework message: native session restoration or autofill supplied control state. */
+export interface FormStateRestore {
+    readonly _tag: 'FormStateRestore';
+    readonly state: FormControlValue;
+    readonly mode: 'restore' | 'autocomplete';
+}
+export type FormMessage = FormReset | FormDisabled | FormStateRestore;
+export interface FormControl {
+    receive(msg: FormMessage): void;
+    sync<S, P>(projection: FormAssociation<S, P>, state: S, ctx: Ctx<P>, root: ParentNode): void;
+}
+/** Native reactions must be installed before customElements.define() reads the prototype. */
+declare function installFormCallbacks(Element: CustomElementConstructor, enabled: boolean): void;
+/** Attach once in the constructor; defer pre-render reactions until hydration has committed. */
+export declare function createFormControl(host: HTMLElement, model: Pick<HostModel<unknown, unknown>, 'hasReducer' | 'dispatch'>): FormControl;
+export declare const formFeature: {
+    create<S, P>(host: HTMLElement, model: Pick<HostModel<unknown, unknown>, "hasReducer" | "dispatch">, projection: FormAssociation<S, P> | undefined): void;
+    sync(host: HTMLElement, state: unknown, ctx: Ctx<unknown>, root: ParentNode): void;
+    install: typeof installFormCallbacks;
+};
+export {};

package/dist/form-associated.js

@@ -0,0 +1,77 @@
+import { internalsOf } from './element-internals.js';
+import { afterRender, POST_HYDRATED } from './scheduler.js';
+const controls = new WeakMap();
+const projections = new WeakMap();
+/** Native reactions must be installed before customElements.define() reads the prototype. */
+function installFormCallbacks(Element, enabled) {
+    if (!enabled)
+        return;
+    Object.defineProperty(Element, 'formAssociated', { value: true });
+    Object.assign(Element.prototype, {
+        formResetCallback() {
+            controls.get(this)?.receive({ _tag: 'FormReset' });
+        },
+        formDisabledCallback(disabled) {
+            controls.get(this)?.receive({ _tag: 'FormDisabled', disabled });
+        },
+        formStateRestoreCallback(state, mode) {
+            controls.get(this)?.receive({ _tag: 'FormStateRestore', state, mode });
+        },
+    });
+}
+/** Attach once in the constructor; defer pre-render reactions until hydration has committed. */
+export function createFormControl(host, model) {
+    const dispatch = (msg) => {
+        if (model.hasReducer(msg._tag))
+            model.dispatch(msg);
+    };
+    const internals = internalsOf(host);
+    let live = false;
+    const pending = [];
+    const control = {
+        receive(msg) {
+            if (live)
+                dispatch(msg);
+            else
+                pending.push(msg);
+        },
+        sync(projection, state, ctx, root) {
+            const value = projection.value(state, ctx);
+            if (projection.state === undefined)
+                internals.setFormValue(value);
+            else
+                internals.setFormValue(value, projection.state(state, ctx));
+            const validity = projection.validity?.(state, ctx);
+            const anchor = validity?.anchor === undefined ? undefined : root.querySelector(validity.anchor);
+            if (anchor != null && !(anchor instanceof HTMLElement)) {
+                throw new TypeError('The form validity anchor must select an HTMLElement.');
+            }
+            internals.setValidity(validity?.flags ?? {}, validity?.message ?? '', anchor ?? undefined);
+            live = true;
+            if (pending.length > 0) {
+                const messages = pending.splice(0);
+                afterRender(POST_HYDRATED, () => {
+                    for (const msg of messages)
+                        dispatch(msg);
+                });
+            }
+        },
+    };
+    controls.set(host, control);
+    return control;
+}
+export const formFeature = {
+    create(host, model, projection) {
+        if (projection === undefined)
+            return;
+        projections.set(host, projection);
+        createFormControl(host, model);
+    },
+    sync(host, state, ctx, root) {
+        const projection = projections.get(host);
+        if (projection !== undefined)
+            controls.get(host)?.sync(projection, state, ctx, root);
+    },
+    install: installFormCallbacks,
+};
+//# sourceMappingURL=form-associated.js.map

package/dist/form-associated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-associated.js","sourceRoot":"","sources":["../src/form-associated.ts"],"names":[],"mappings":"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","sourcesContent":["import { internalsOf } from './element-internals.js';\nimport { afterRender, POST_HYDRATED } from './scheduler.js';\nimport type { Ctx } from './types.js';\nimport type { HostModel } from './host-model.js';\n\n/** A native submitted value, or null to omit this component from the submission. */\nexport type FormControlValue = string | File | FormData | null;\n\n/** Native constraint flags and a validation bubble anchor in the component's render root. */\nexport interface FormControlValidity {\n  readonly flags: ValidityStateFlags;\n  readonly message: string;\n  readonly anchor?: string;\n}\n\n/** Pure model projections applied by Gyral to the host's ElementInternals (ADR 0008). */\nexport interface FormAssociation<S, P> {\n  readonly value: (state: S, ctx: Ctx<P>) => FormControlValue;\n  readonly state?: (state: S, ctx: Ctx<P>) => FormControlValue;\n  readonly validity?: (state: S, ctx: Ctx<P>) => FormControlValidity | undefined;\n}\n\n/** Framework message: the owning native form was reset. */\nexport interface FormReset {\n  readonly _tag: 'FormReset';\n}\n\n/** Framework message: the host or its fieldset changed the effective disabled state. */\nexport interface FormDisabled {\n  readonly _tag: 'FormDisabled';\n  readonly disabled: boolean;\n}\n\n/** Framework message: native session restoration or autofill supplied control state. */\nexport interface FormStateRestore {\n  readonly _tag: 'FormStateRestore';\n  readonly state: FormControlValue;\n  readonly mode: 'restore' | 'autocomplete';\n}\n\nexport type FormMessage = FormReset | FormDisabled | FormStateRestore;\n\nexport interface FormControl {\n  receive(msg: FormMessage): void;\n  sync<S, P>(projection: FormAssociation<S, P>, state: S, ctx: Ctx<P>, root: ParentNode): void;\n}\n\nconst controls = new WeakMap<HTMLElement, FormControl>();\nconst projections = new WeakMap<HTMLElement, FormAssociation<unknown, unknown>>();\n\n/** Native reactions must be installed before customElements.define() reads the prototype. */\nfunction installFormCallbacks(Element: CustomElementConstructor, enabled: boolean): void {\n  if (!enabled) return;\n  Object.defineProperty(Element, 'formAssociated', { value: true });\n  Object.assign(Element.prototype, {\n    formResetCallback(this: HTMLElement): void {\n      controls.get(this)?.receive({ _tag: 'FormReset' });\n    },\n    formDisabledCallback(this: HTMLElement, disabled: boolean): void {\n      controls.get(this)?.receive({ _tag: 'FormDisabled', disabled });\n    },\n    formStateRestoreCallback(\n      this: HTMLElement,\n      state: FormControlValue,\n      mode: 'restore' | 'autocomplete',\n    ): void {\n      controls.get(this)?.receive({ _tag: 'FormStateRestore', state, mode });\n    },\n  });\n}\n\n/** Attach once in the constructor; defer pre-render reactions until hydration has committed. */\nexport function createFormControl(\n  host: HTMLElement,\n  model: Pick<HostModel<unknown, unknown>, 'hasReducer' | 'dispatch'>,\n): FormControl {\n  const dispatch = (msg: FormMessage): void => {\n    if (model.hasReducer(msg._tag)) model.dispatch(msg);\n  };\n  const internals = internalsOf(host);\n  let live = false;\n  const pending: FormMessage[] = [];\n  const control: FormControl = {\n    receive(msg) {\n      if (live) dispatch(msg);\n      else pending.push(msg);\n    },\n    sync(projection, state, ctx, root) {\n      const value = projection.value(state, ctx);\n      if (projection.state === undefined) internals.setFormValue(value);\n      else internals.setFormValue(value, projection.state(state, ctx));\n      const validity = projection.validity?.(state, ctx);\n      const anchor =\n        validity?.anchor === undefined ? undefined : root.querySelector(validity.anchor);\n      if (anchor != null && !(anchor instanceof HTMLElement)) {\n        throw new TypeError('The form validity anchor must select an HTMLElement.');\n      }\n      internals.setValidity(validity?.flags ?? {}, validity?.message ?? '', anchor ?? undefined);\n      live = true;\n      if (pending.length > 0) {\n        const messages = pending.splice(0);\n        afterRender(POST_HYDRATED, () => {\n          for (const msg of messages) dispatch(msg);\n        });\n      }\n    },\n  };\n  controls.set(host, control);\n  return control;\n}\n\nexport const formFeature = {\n  create<S, P>(\n    host: HTMLElement,\n    model: Pick<HostModel<unknown, unknown>, 'hasReducer' | 'dispatch'>,\n    projection: FormAssociation<S, P> | undefined,\n  ): void {\n    if (projection === undefined) return;\n    projections.set(host, projection as unknown as FormAssociation<unknown, unknown>);\n    createFormControl(host, model);\n  },\n  sync(host: HTMLElement, state: unknown, ctx: Ctx<unknown>, root: ParentNode): void {\n    const projection = projections.get(host);\n    if (projection !== undefined) controls.get(host)?.sync(projection, state, ctx, root);\n  },\n  install: installFormCallbacks,\n};\n"]}

package/dist/forms.d.ts

@@ -1,21 +1,27 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { FieldIssue, FormFields, IntentParser, IntentRejected } from './types.js';
-/** A form's schema, shared by the client component and (with @gyral/ssr) the server route. */
-export interface FormDefinition<Schema extends StandardSchemaV1> {
-    readonly _tag: 'FormDefinition';
-    readonly schema: Schema;
+import type { FieldIssue, FormFields, IntentInput, IntentParser, IntentRejected } from './types.js';
+type In<Schema extends StandardSchemaV1> = StandardSchemaV1.InferInput<Schema>;
+type Out<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+/** The definition's field names, when its input is an object; otherwise any string. */
+export type FieldName<Schema extends StandardSchemaV1> = In<Schema> extends Readonly<Record<string, unknown>> ? keyof In<Schema> & string : string;
+export interface FormOptions<Schema extends StandardSchemaV1> {
+    /**
+     * Fields whose submitted values are never sent back: not in `IntentRejected.values`, not in
+     * `values()`, not in the devtools timeline. Any posted field name may be listed, including
+     * fields outside the schema. Names containing `password`, `passcode`, `csrf` or `xsrf` are
+     * secret without being listed (the browser never restores a password field either, and a
+     * CSRF token must come fresh from the server, not from the echo).
+     */
+    readonly secret?: readonly (FieldName<Schema> | (string & {}))[];
 }
-export declare function defineForm<Schema extends StandardSchemaV1>(schema: Schema): FormDefinition<Schema>;
-export type FormValue = FormDataEntryValue | readonly FormDataEntryValue[];
 /**
- * FormData to a plain object. The same function runs on the server, so both sides agree.
- * Repeated names become arrays; a `name[]` suffix always yields an array (named `name`).
- * Values stay strings (or Files): the schema coerces them.
+ * A form's submitted text values, keyed by the definition's fields, for re-rendering the form
+ * with what was typed (sticky fields). The same shape as `IntentRejected.values`: repeated names
+ * (and `name[]`) are arrays; `File`s and secret fields are left out.
  */
-export declare function formDataToObject(data: FormData): Readonly<Record<string, FormValue>>;
-type Out<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
-/** The text fields of a parsed form, for re-filling it after a rejection. */
-export declare function formFields(data: Readonly<Record<string, FormValue>>): FormFields;
+export type FormValues<Schema extends StandardSchemaV1> = In<Schema> extends Readonly<Record<string, unknown>> ? {
+    readonly [K in keyof In<Schema> & string]?: string | readonly string[];
+} : FormFields;
 export type FormResult<T> = {
     readonly ok: true;
     readonly data: T;
@@ -23,22 +29,35 @@ export type FormResult<T> = {
     readonly ok: false;
     readonly rejected: IntentRejected;
 };
-/**
- * Validates submitted form data exactly as `form()` does. The no-JS server path
- * (`formAction` in @gyral/ssr) uses it, so both paths produce the same `IntentRejected`.
- */
-export declare function validateForm<Schema extends StandardSchemaV1>(definition: FormDefinition<Schema> | Schema, intent: string, data: FormData): FormResult<Out<Schema>> | Promise<FormResult<Out<Schema>>>;
+/** A form's schema, shared by the client component and (with `@gyral/ssr`) the server route. */
+export interface FormDefinition<Schema extends StandardSchemaV1> {
+    readonly _tag: 'FormDefinition';
+    readonly schema: Schema;
+    /** The fields listed as secret (names containing `password`, `passcode`, `csrf` or `xsrf` are secret too). */
+    readonly secret: readonly string[];
+    /**
+     * Validates submitted form data exactly as `form()` does; the server's `formAction` uses it,
+     * so both paths produce the same `IntentRejected` (`intent` defaults to `''`).
+     */
+    readonly validate: (data: FormData, intent?: string) => FormResult<Out<Schema>> | Promise<FormResult<Out<Schema>>>;
+    /** The submitted text values without secrets: what a re-rendered form may show again. */
+    readonly values: (data: FormData) => FormValues<Schema>;
+}
+/** Whether `name` is never echoed: declared secret by a form, or a password-like name. */
+export declare function isSecretField(name: string): boolean;
+export declare function defineForm<Schema extends StandardSchemaV1>(schema: Schema, options?: FormOptions<Schema>): FormDefinition<Schema>;
+export type FormValue = FormDataEntryValue | readonly FormDataEntryValue[];
 /**
  * Intent parser for a `<form data-intent>` submission, validated by a schema. `toMsg` also
  * gets the raw `FormData`, for sending the submission to the server (`submitForm` in
- * @gyral/http) after it passed client-side validation.
+ * `@gyral/http`) after it passed client-side validation.
  */
-export declare function form<Schema extends StandardSchemaV1, M>(definition: FormDefinition<Schema> | Schema, toMsg: (data: Out<Schema>, formData: FormData) => M | undefined): IntentParser<M>;
+export declare function form<Schema extends StandardSchemaV1, M>(definition: FormDefinition<Schema> | Schema, toMsg: (data: Out<Schema>, formData: FormData) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;
 /**
  * Intent parser for one control (pair with `data-intent-on="input"` for live checks).
  * Validates `checked` for checkboxes and radios, otherwise `value`.
  */
-export declare function field<Schema extends StandardSchemaV1, M>(schema: Schema, toMsg: (value: Out<Schema>) => M | undefined): IntentParser<M>;
+export declare function field<Schema extends StandardSchemaV1, M>(schema: Schema, toMsg: (value: Out<Schema>) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;
 /**
  * Groups issues by field name. Call it in the `IntentRejected` reducer and keep the result in
  * state: `invalid()` re-applies an error only when it gets a new array.
@@ -46,14 +65,7 @@ export declare function field<Schema extends StandardSchemaV1, M>(schema: Schema
 export declare function fieldErrors(issues: readonly FieldIssue[]): Readonly<Record<string, readonly string[]>>;
 /**
  * A Standard Schema for `IntentRejected` as a server sends it (`formAction` answering JSON).
- * Used by `submitForm` in @gyral/http to recognise a 422 rejection; usable with any decoder.
+ * Used by `submitForm` in `@gyral/http` to recognise a 422 rejection; usable with any decoder.
  */
 export declare const intentRejectedSchema: StandardSchemaV1<unknown, IntentRejected>;
-/** A server's JSON answer to a valid form post that would have redirected without JS. */
-export interface FormRedirected {
-    readonly _tag: 'Redirected';
-    readonly location: string;
-}
-/** The `location` of a `FormRedirected` answer (from `formAction` in @gyral/ssr), if it is one. */
-export declare function redirectedTo(body: unknown): string | undefined;
 export {};