@drhomet/mithaq 0.0.0-stage → 0.1.1

package/dist/rich-text/rich-text.js

@@ -0,0 +1,372 @@
+// No React and no DOM: the server checks a write with the same node list the browser draws with.
+import { HorizontalRuleNode } from '@lexical/extension';
+import { LinkNode } from '@lexical/link';
+import { ListItemNode, ListNode } from '@lexical/list';
+import { HeadingNode, QuoteNode } from '@lexical/rich-text';
+import { $getDocument, $getRoot, $isDecoratorNode, $isElementNode, $getState, $setState, createEditor, createState, DecoratorNode, LineBreakNode, ParagraphNode, RootNode, TabNode, TextNode, } from 'lexical';
+/**
+ * How deep a rich text value may nest, how large it may be and how many nodes it may hold,
+ * all checked before any Lexical code reads it.
+ */
+export const richTextBounds = { depth: 64, bytes: 512 * 1024, nodes: 10_000 };
+// Depth is checked before `JSON.stringify` walks a hostile value. An object met
+// twice is refused, so one reachable many ways is not walked once per way.
+const within = (value, depth, seen = new WeakSet()) => {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    if (depth <= 0)
+        return `The value nests deeper than ${richTextBounds.depth} levels.`;
+    if (seen.has(value))
+        return 'The value holds one object in two places.';
+    seen.add(value);
+    for (const one of Object.values(value)) {
+        const refused = within(one, depth - 1, seen);
+        if (refused)
+            return refused;
+    }
+    return undefined;
+};
+/** Whether a link may point here: `http`, `https`, `mailto`, `tel`, a fragment or a path. */
+export const safeUrl = (url) => {
+    if (typeof url !== 'string')
+        return false;
+    // eslint-disable-next-line no-control-regex
+    const cleaned = url.trim().replace(/[\x00-\x1f\x7f]/g, '');
+    if (cleaned.startsWith('#') || cleaned.startsWith('/') || cleaned.startsWith('./') || cleaned.startsWith('../'))
+        return true;
+    const protocol = cleaned.match(/^([a-z][a-z0-9+\-.]*):(?=.)/i)?.[1]?.toLowerCase();
+    // A web address must name a host: refuses `https://`, `http:///path` (read as
+    // a host named `path`), `https://@` and the like.
+    if (protocol === 'http' || protocol === 'https') {
+        try {
+            return /^https?:\/\/[^/?#\\\s]/i.test(cleaned) && /[\p{L}\p{N}]/u.test(new URL(cleaned).hostname);
+        }
+        catch {
+            return false;
+        }
+    }
+    return protocol === 'mailto' || protocol === 'tel';
+};
+const held = (node, key) => node[key];
+/**
+ * Why a value is no Lexical editor state a `richText` column may hold, or nothing. Runs before
+ * any Lexical code reads the value; a `style` is refused, since no editor of the project writes one.
+ */
+export const richTextGuard = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return 'The value is no object.';
+    const nested = within(value, richTextBounds.depth);
+    if (nested)
+        return nested;
+    if (new TextEncoder().encode(JSON.stringify(value)).length > richTextBounds.bytes)
+        return `The value is larger than ${richTextBounds.bytes} bytes.`;
+    const root = held(value, 'root');
+    if (!root || typeof root !== 'object' || Array.isArray(root) || held(root, 'type') !== 'root')
+        return 'The value has no root of type "root".';
+    if (!Array.isArray(held(root, 'children')))
+        return 'The root holds no list of children.';
+    let count = 0;
+    const walk = (node) => {
+        if (!node || typeof node !== 'object' || Array.isArray(node) || typeof held(node, 'type') !== 'string')
+            return 'A node is no object with a string type.';
+        if (++count > richTextBounds.nodes)
+            return `The value holds more than ${richTextBounds.nodes} nodes.`;
+        const type = held(node, 'type');
+        if (Object.hasOwn(node, 'text') && typeof held(node, 'text') !== 'string')
+            return `A node of type "${type}" holds text that is no string.`;
+        if (typeof held(node, 'text') === 'string') {
+            for (const key of ['format', 'detail']) {
+                if (Object.hasOwn(node, key) && !Number.isInteger(held(node, key)))
+                    return `A node of type "${type}" holds a ${key} that is no whole number.`;
+            }
+        }
+        for (const key of ['style', 'textStyle']) {
+            if (Object.hasOwn(node, key) && held(node, key) !== '')
+                return `A node of type "${type}" holds a ${key}, and this editor writes none.`;
+        }
+        if ((type === 'link' || type === 'autolink') && !safeUrl(held(node, 'url')))
+            return `A link points at an address that is not http, https, mailto, tel or a path.`;
+        if (!Object.hasOwn(node, 'children'))
+            return undefined;
+        const children = held(node, 'children');
+        if (!Array.isArray(children))
+            return `A node of type "${type}" holds children that are no list.`;
+        for (const child of children) {
+            const refused = walk(child);
+            if (refused)
+                return refused;
+        }
+        return undefined;
+    };
+    return walk(root);
+};
+/** Whether a value passes `richTextGuard`, which is all the kind itself asks of one. */
+export const isRichText = (value) => richTextGuard(value) === undefined;
+/** The node classes the registry's editor draws. A project's list spreads it: `[...defaultNodes, CalloutNode]`. */
+export const defaultNodes = [HeadingNode, QuoteNode, ListNode, ListItemNode, LinkNode, HorizontalRuleNode];
+/** The nodes every Lexical editor registers whatever it is given. */
+const coreNodes = [RootNode, ParagraphNode, TextNode, LineBreakNode, TabNode];
+/** Every node type a list of classes can read, the core ones included. */
+export const typesOf = (nodes) => new Set([...coreNodes, ...nodes].map((node) => node.getType()));
+/**
+ * The first node type under a value's `root` that `types` does not hold, or nothing, and `''`
+ * past the depth bound. Read off the JSON, since a production Lexical minifies its errors.
+ */
+export const unknownType = ({ node, types, depth = richTextBounds.depth }) => {
+    if (!node || typeof node !== 'object')
+        return undefined;
+    if (depth <= 0)
+        return '';
+    const held = node;
+    if (typeof held.type === 'string' && !types.has(held.type))
+        return held.type;
+    for (const child of Array.isArray(held.children) ? held.children : []) {
+        const type = unknownType({ node: child, types, depth: depth - 1 });
+        if (type !== undefined)
+            return type;
+    }
+    return undefined;
+};
+// Set by `richTextReader` around its own synchronous parse alone, so a value is
+// never checked against another build's list.
+let holdingFiles;
+const formats = ['', 'left', 'start', 'center', 'right', 'end', 'justify'];
+const formatState = createState('format', { parse: (value) => (formats.includes(value) ? value : '') });
+// The node's own id, not the file's: an ObjectID's hex.
+const uploadIdState = createState('id', { parse: (value) => (typeof value === 'string' ? value : '') });
+const relationToState = createState('relationTo', {
+    parse: (value) => {
+        if (value === undefined)
+            return '';
+        if (typeof value !== 'string' || !value)
+            throw new Error('An upload names the kayan its file is a row of, as a string under relationTo.');
+        if (holdingFiles && !holdingFiles.has(value))
+            throw new Error(`An upload's relationTo "${value}" is no kayan of this build that holds files.`);
+        return value;
+    },
+});
+const valueState = createState('value', {
+    parse: (value) => {
+        if (value === undefined)
+            return '';
+        if (typeof value !== 'string' || !value || value.length > 255)
+            throw new Error("An upload's value is the id of its file's row, a string.");
+        return value;
+    },
+});
+/** The extra fields Payload's editor asks of an upload, such as a caption, kept as they were written and drawn by nothing here. */
+const fieldsState = createState('fields', { parse: (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : null) });
+/**
+ * A file inside rich text, in the JSON Payload's editor writes (`type: 'upload'`, `version: 3`).
+ * DOM-free, so the server checks a write with it. A project opts in: `[...defaultNodes, UploadNode]`.
+ */
+export class UploadNode extends DecoratorNode {
+    $config() {
+        return this.config('upload', {
+            extends: DecoratorNode,
+            stateConfigs: [
+                { stateConfig: formatState, flat: true },
+                { stateConfig: uploadIdState, flat: true },
+                { stateConfig: relationToState, flat: true },
+                { stateConfig: valueState, flat: true },
+                { stateConfig: fieldsState, flat: true },
+            ],
+        });
+    }
+    /** Refused where either half of what the node points at is missing, which an absent key leaves at its default. */
+    updateFromJSON(json) {
+        const node = super.updateFromJSON(json);
+        if (!$getState(node, relationToState) || !$getState(node, valueState))
+            throw new Error('An upload names its relationTo and its value.');
+        return node;
+    }
+    /** Every key, defaults included, as Payload's editor writes it. */
+    exportJSON() {
+        return {
+            ...super.exportJSON(),
+            type: 'upload',
+            version: 3,
+            format: $getState(this, formatState),
+            id: $getState(this, uploadIdState),
+            relationTo: $getState(this, relationToState),
+            value: $getState(this, valueState),
+            fields: $getState(this, fieldsState),
+        };
+    }
+    getRelationTo() {
+        return $getState(this, relationToState);
+    }
+    getValue() {
+        return $getState(this, valueState);
+    }
+    getFormat() {
+        return $getState(this, formatState);
+    }
+    /** Points the node at one file, with a fresh node id: an ObjectID's twelve bytes in hex. */
+    setUpload(relationTo, value) {
+        const id = Array.from(crypto.getRandomValues(new Uint8Array(12)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+        return $setState($setState($setState(this, uploadIdState, id), relationToState, relationTo), valueState, value);
+    }
+    createDOM() {
+        return $getDocument().createElement('div');
+    }
+    updateDOM() {
+        return false;
+    }
+    isInline() {
+        return false;
+    }
+    decorate() {
+        return null;
+    }
+}
+/** Whether a node is a decorator or holds one at any depth. */
+const $holdsDecorator = (node) => $isDecoratorNode(node) || ($isElementNode(node) && node.getChildren().some($holdsDecorator));
+/**
+ * A reader of `richText` values over a node list: the guard walk, then a headless parse.
+ * `uploads` names the kayan an `UploadNode` may point at.
+ */
+export const richTextReader = (nodes, uploads) => {
+    const types = typesOf(nodes);
+    const holding = uploads && new Set(uploads);
+    // Made with the reader at `buildAsas`, so a list Lexical cannot register fails
+    // the build rather than the first write.
+    const editor = createEditor({ nodes: [...nodes], onError: (error) => { throw error; } });
+    return (value) => {
+        const refused = richTextGuard(value);
+        if (refused)
+            return { refused };
+        const type = unknownType({ node: value.root, types });
+        if (type) {
+            return {
+                refused: `No node of this editor is of type "${type}". Add its class to the nodes passed to richText({ nodes }), or convert or remove the node before writing.`,
+                type,
+            };
+        }
+        // Restored rather than cleared, so a nested parse never leaves the outer one without its list.
+        const before = holdingFiles;
+        try {
+            holdingFiles = holding;
+            return editor.parseEditorState(value).read(() => ({ text: $getRoot().getTextContent(), holdsDecorator: $holdsDecorator($getRoot()) }));
+        }
+        catch (error) {
+            return { refused: `The editor could not read the value: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        finally {
+            holdingFiles = before;
+        }
+    };
+};
+/**
+ * How a stored `richText` value is read back: a root with children and nothing more,
+ * so a value holding a node the project has since dropped still reads.
+ */
+export const storedRichText = (value) => {
+    const root = value && typeof value === 'object' && !Array.isArray(value) ? value.root : undefined;
+    return root && typeof root === 'object' && root.type === 'root' && Array.isArray(root.children) ? { text: '' } : { refused: 'The stored value is no editor state.' };
+};
+// Canonical through Lexical's own `toJSON`, so converting again changes nothing,
+// and read once more, since the canonical value is larger.
+const settle = (convert, nodes) => {
+    if (!Array.isArray(nodes))
+        return { refused: 'The converters were handed no "nodes", and pick none of their own. Pass the project\'s list: nodes: [...defaultNodes, ...].' };
+    try {
+        const { value, dropped } = convert();
+        const reader = richTextReader(nodes);
+        const before = reader(value);
+        if ('refused' in before)
+            return { refused: before.refused };
+        const editor = createEditor({ nodes: [...nodes], onError: (error) => { throw error; } });
+        // Lexical writes every default key, so a value inside the bounds can grow past them.
+        const canonical = JSON.parse(JSON.stringify(editor.parseEditorState(value).toJSON()));
+        const after = reader(canonical);
+        return 'refused' in after ? { refused: after.refused } : { value: canonical, dropped };
+    }
+    catch (error) {
+        return { refused: `The value could not be converted: ${error instanceof Error ? error.message : String(error)}` };
+    }
+};
+/** Payload's own node types, which no class of `defaultNodes` reads: kept where the project's list registers one, dropped where it does not. */
+const payloadTypes = new Set(['upload', 'relationship', 'block', 'inlineBlock']);
+/**
+ * A value Payload's lexical editor stored, as one this editor reads, with what could not come across.
+ * A link the editor would not write is replaced by its text; a `style` is cleared.
+ */
+export const convertPayloadToLexical = ({ data, nodes }) => settle(() => {
+    const types = typesOf(nodes);
+    const dropped = [];
+    // Bounded like `unknownType`; a node met twice is refused, so one reachable many
+    // ways is never walked once for each way.
+    const seen = new WeakSet();
+    const walk = (node, path, depth) => {
+        if (!node || typeof node !== 'object' || Array.isArray(node) || depth <= 0)
+            return [node];
+        if (seen.has(node))
+            throw new Error(`The value holds the node at ${path} in two places.`);
+        seen.add(node);
+        const next = { ...node };
+        const type = String(next.type);
+        const drop = (reason) => dropped.push({ path, type, reason });
+        // Only a string is quoted in a reason: anything else may be too large or deep to write out.
+        const quote = (value) => (typeof value === 'string' ? JSON.stringify(value) : 'a value that is not a string');
+        if (payloadTypes.has(type) && !types.has(type)) {
+            drop(`No node of this editor is of type "${type}", so it was left out.`);
+            return [];
+        }
+        for (const key of ['style', 'textStyle']) {
+            if (Object.hasOwn(next, key) && next[key] !== '') {
+                drop(`Its ${key}, ${quote(next[key])}, was cleared, since this editor writes none.`);
+                next[key] = '';
+            }
+        }
+        if (Array.isArray(next.children))
+            next.children = next.children.flatMap((child, index) => walk(child, `${path}.children[${index}]`, depth - 1));
+        // Payload's postgres adapter writes a numeric id where a collection's ids are serial.
+        if (type === 'upload' && typeof next.value === 'number' && Number.isFinite(next.value))
+            next.value = String(next.value);
+        if (type !== 'link' && type !== 'autolink')
+            return [next];
+        const { fields, id: _id, ...link } = next;
+        const held = fields && typeof fields === 'object' ? fields : undefined;
+        let url = held ? held.url : link.url;
+        // Lexical's own autolink marks one its writer unlinked.
+        if (next.isUnlinked === true) {
+            drop('It was an autolink its writer had unlinked, so only its text was kept.');
+            return next.children ?? [];
+        }
+        if (held?.linkType === 'internal' || (held?.doc && !url)) {
+            drop('It linked to a Payload document, which this editor has no link for, so only its text was kept.');
+            return next.children ?? [];
+        }
+        if (typeof url === 'string' && url.startsWith('www.'))
+            url = `https://${url}`;
+        if (!safeUrl(url)) {
+            drop(`Its address is ${quote(url)}, not http, https, mailto, tel or a path, so only its text was kept.`);
+            return next.children ?? [];
+        }
+        // `noopener`, so the page a new tab opens cannot reach this one.
+        const blank = held?.newTab === true;
+        const tab = held ? { target: blank ? '_blank' : null, rel: blank ? 'noopener' : null } : {};
+        return [{ ...link, type: 'link', url, ...tab }];
+    };
+    return { value: { root: walk(data?.root, 'root', richTextBounds.depth)[0] }, dropped };
+}, nodes);
+/** Plain text as a value: a blank line starts a paragraph, a newline is a `linebreak` and a tab a `tab`. */
+export const convertPlaintextToLexical = ({ text, nodes }) => settle(() => ({
+    value: {
+        root: {
+            type: 'root',
+            children: text
+                .replace(/\r\n?/g, '\n')
+                .split('\n\n')
+                .map((paragraph) => ({
+                type: 'paragraph',
+                children: paragraph
+                    .split(/(\n|\t)/)
+                    .filter(Boolean)
+                    .map((part) => (part === '\n' ? { type: 'linebreak' } : part === '\t' ? { type: 'tab', text: '\t' } : { type: 'text', text: part })),
+            })),
+        },
+    },
+    dropped: [],
+}), nodes);

package/dist/screen/client.d.ts

@@ -0,0 +1,153 @@
+export { afterCommitHeader } from '../asas/runner/errors.ts';
+export { allowedType } from '../storage/allowed-type.ts';
+export { compareDecimals, decimalDigits, isDecimal } from '../base/decimal.ts';
+export type { ButtonClient, ClientField, ClientKayan, FrameClient, LeafClient, NavEntry, NodeClient, PageClient, RegionsClient, ScreenClient, ScreenPageClient, } from './index.ts';
+import type { ClientField, NavEntry, PageClient, ScreenClient } from './index.ts';
+export { compareValues, matchesWhere, same } from '../mithaq/where.ts';
+/** How copy is resolved: a key, and what to show when nothing answers it. */
+export type Translate = (key: string, fallback?: string) => string | undefined;
+/** What `GET /api/access` answers for the actor. */
+export type AccessReport = {
+    /** The screens this actor may enter, by name, and no other. */
+    readonly screens?: readonly string[];
+    /** Every catalog key the actor holds, `'*'` for all, absent where no access target grades. */
+    readonly permissions?: '*' | readonly string[];
+    readonly collections?: Readonly<Record<string, {
+        readonly read?: boolean;
+        readonly create?: boolean;
+        readonly update?: boolean;
+        readonly delete?: boolean;
+        readonly operations?: Readonly<Record<string, boolean>>;
+        readonly fields?: Readonly<Record<string, {
+            readonly create?: boolean;
+            readonly read?: boolean;
+            readonly update?: boolean;
+        }>>;
+    } | undefined>>;
+};
+/**
+ * A router no type was given: every kayan and every operation a name held in a
+ * string, which is what registry code that learns its kayan at runtime holds.
+ */
+export type AnyRouter = Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+type SchemaOf<Procedure, Side extends 'inputSchema' | 'outputSchema', Otherwise> = Procedure extends {
+    readonly '~orpc': Readonly<Partial<Record<Side, infer Schema>>>;
+} ? Schema extends {
+    readonly '~standard': {
+        readonly types?: infer Types;
+    };
+} ? Types extends Record<Side extends 'inputSchema' ? 'input' : 'output', infer Value> ? Value : Otherwise : Otherwise : Otherwise;
+/**
+ * Posts one operation of one kayan to `POST /api/<kayan>/<operation>`, typed by the built router:
+ * `FetchClient<typeof asas.router>`. A `Date` in the answer arrives as its ISO string.
+ */
+export type FetchClient<R = AnyRouter> = <K extends keyof R & string, O extends keyof R[K] & string>(call: {
+    kayan: K;
+    operation: O;
+    input: SchemaOf<R[K][O], 'inputSchema', Record<string, unknown>>;
+    draft?: boolean;
+    autosave?: boolean;
+}) => Promise<SchemaOf<R[K][O], 'outputSchema', unknown>>;
+/** One stored row, as a read answers it. */
+export type Row = Record<string, unknown>;
+/** Whether the access report lets its actor hold one catalog key: a screen's, an operation's, or any other key. */
+export declare const holds: (report: AccessReport, key: string) => boolean;
+export declare const packageName: RegExp;
+/** Every `ui()` reference a projection prints, `./src/file.tsx#Export` or `<package>:./src/file.tsx#Export`. */
+export declare const referencesIn: (value: unknown) => string[];
+/** The screen's nav as one actor sees it: every entry whose key the actor holds, and every entry that names none. */
+export declare const navOf: (screen: Pick<ScreenClient, 'nav'>, report: AccessReport) => NavEntry[];
+export type ProviderProps<Node = unknown> = {
+    children: Node;
+};
+/** A shell, at the root of a page's tree: its regions drawn. The nav is `mithaq/admin/react` `useNav()`. */
+export type ShellProps<Regions extends readonly string[] = readonly string[], Node = unknown> = {
+    regions: Record<Regions[number], Node>;
+};
+/** A page of the screen's own, drawn whole: what its file's `loader` answered, if it exports one. */
+export type PageProps<Data = unknown> = {
+    loaderData?: Data;
+};
+/**
+ * What a page's `loader` reads with, as the actor of the request: `client`, `request` and the
+ * access report. It reads the same rows on the server and in the browser.
+ */
+export type LoaderTools = {
+    client: FetchClient;
+    request: (path: string, init?: RequestInit) => Promise<Response>;
+    access: AccessReport;
+    maxLimit: number;
+};
+/** A layout nested in a region: its regions drawn, and the page it frames. */
+export type LayoutProps<Regions extends readonly string[] = readonly string[], Node = unknown> = {
+    regions: Record<Regions[number], Node>;
+    page: PageClient;
+};
+/** A component node, and a kayan page drawn whole: the page it sits on. */
+export type ComponentProps = {
+    page: PageClient;
+};
+/** A field's control: the field, its value and the one way to change it. */
+export type ControlProps = {
+    field: ClientField;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    readOnly: boolean;
+    issue: string | null;
+};
+/** A list's cell: the field, its value, and the row it sits in. */
+export type CellProps = {
+    field: ClientField;
+    value: unknown;
+    row: Row;
+};
+/** What an empty list draws: the page the list sits on. */
+export type EmptyProps = {
+    page: PageClient;
+};
+/** What a list's `menu` draws inside one row's menu: the row, and `open`, which draws a node beside the list until `null`. */
+export type MenuProps<Node = unknown> = {
+    row: Row;
+    open: (node: Node | null) => void;
+};
+/** A button that names a component: its operation, the run that asks the confirm first, and whether the form is busy. */
+export type ButtonProps = {
+    operation: string;
+    run: (input: Row) => Promise<void>;
+    busy: boolean;
+};
+export { regionsIn, studioText, studioTree, type StudioNode } from './studio.ts';
+export { kindOf, nodeKinds, type NodeKind, type NodeOf } from './studio.ts';
+/** The controls the copied registry supplies, each with the kinds whose value it reports. */
+export declare const builtInScreenKinds: {
+    readonly text: readonly ["text", "email", "date", "datetime", "decimal"];
+    readonly email: readonly ["email"];
+    readonly number: readonly ["number", "integer"];
+    readonly integer: readonly ["integer"];
+    readonly decimal: readonly ["decimal"];
+    readonly checkbox: readonly ["checkbox"];
+    readonly datetime: readonly ["datetime"];
+    readonly date: readonly ["date"];
+    readonly textArray: readonly ["textArray"];
+    readonly uuid: readonly ["uuid"];
+    readonly relationship: readonly ["relationship", "upload"];
+    readonly join: readonly ["join"];
+    readonly switch: readonly ["checkbox"];
+    readonly radio: readonly ["text"];
+    readonly toggleGroup: readonly ["text"];
+    readonly select: readonly ["text"];
+    readonly nativeSelect: readonly ["text"];
+    readonly slider: readonly ["number"];
+    readonly otp: readonly ["text"];
+    readonly combobox: readonly ["text"];
+    readonly textarea: readonly ["text"];
+    readonly toggle: readonly ["checkbox"];
+    readonly buttonGroup: readonly ["text"];
+    readonly checkboxGroup: readonly ["textArray"];
+    readonly calendar: readonly ["date"];
+};
+/** Every control and cell the copied registry ships, by the name it looks each up by. */
+export declare const registryControls: readonly [...("buttonGroup" | "calendar" | "checkbox" | "checkboxGroup" | "combobox" | "date" | "datetime" | "decimal" | "email" | "integer" | "nativeSelect" | "number" | "otp" | "radio" | "relationship" | "select" | "slider" | "switch" | "text" | "textArray" | "textarea" | "toggle" | "toggleGroup" | "uuid")[], "richText", "upload"];
+export declare const registryCells: readonly ['text', 'email', 'number', 'integer', 'decimal', 'checkbox', 'datetime', 'date', 'textArray', 'uuid', 'relationship', 'join', 'richText', 'upload'];
+/** The built-in controls that draw a field's `options`; the build refuses one over a field that declares none. */
+export declare const choiceControls: string[];

package/dist/screen/client.js

@@ -0,0 +1,68 @@
+// Every runtime import of this entry imports nothing but types, so a browser
+// receives no server code and no framework.
+export { afterCommitHeader } from '../asas/runner/errors.js';
+export { allowedType } from '../storage/allowed-type.js';
+export { compareDecimals, decimalDigits, isDecimal } from '../base/decimal.js';
+export { compareValues, matchesWhere, same } from '../mithaq/where.js';
+/** Whether the access report lets its actor hold one catalog key: a screen's, an operation's, or any other key. */
+export const holds = (report, key) => {
+    const dot = key.indexOf('.');
+    const [resource, action] = [key.slice(0, dot), key.slice(dot + 1)];
+    if (resource === 'screen')
+        return report.screens?.includes(action) === true;
+    const operations = report.collections?.[resource]?.operations;
+    if (operations && Object.hasOwn(operations, action))
+        return operations[action] === true;
+    return report.permissions === '*' || report.permissions?.includes(key) === true;
+};
+// A reference prints the package name into a glob's base, `/node_modules/<name>/`,
+// so no path up, absolute path or space may cross.
+const npmName = '(?:@[a-z0-9~-][a-z0-9._~-]*/)?[a-z0-9~-][a-z0-9._~-]*';
+export const packageName = new RegExp(`^${npmName}$`, 'i');
+const reference = new RegExp(`^(?:${npmName}:)?\\./[^#]+#[\\p{ID_Start}$_][\\p{ID_Continue}$]*$`, 'iu');
+/** Every `ui()` reference a projection prints, `./src/file.tsx#Export` or `<package>:./src/file.tsx#Export`. */
+export const referencesIn = (value) => typeof value === 'string'
+    ? reference.test(value) ? [value] : []
+    : value && typeof value === 'object' ? Object.values(value).flatMap(referencesIn) : [];
+/** The screen's nav as one actor sees it: every entry whose key the actor holds, and every entry that names none. */
+export const navOf = (screen, report) => screen.nav.filter((entry) => entry.permission === undefined || holds(report, entry.permission));
+export { regionsIn, studioText, studioTree } from './studio.js';
+export { kindOf, nodeKinds } from './studio.js';
+/** The controls the copied registry supplies, each with the kinds whose value it reports. */
+export const builtInScreenKinds = {
+    text: ['text', 'email', 'date', 'datetime', 'decimal'],
+    email: ['email'],
+    number: ['number', 'integer'],
+    integer: ['integer'],
+    decimal: ['decimal'],
+    checkbox: ['checkbox'],
+    datetime: ['datetime'],
+    date: ['date'],
+    textArray: ['textArray'],
+    uuid: ['uuid'],
+    // A file is a row of a storage kayan, so the picker of rows draws it too.
+    relationship: ['relationship', 'upload'],
+    join: ['join'],
+    switch: ['checkbox'],
+    radio: ['text'],
+    toggleGroup: ['text'],
+    select: ['text'],
+    nativeSelect: ['text'],
+    slider: ['number'],
+    otp: ['text'],
+    combobox: ['text'],
+    textarea: ['text'],
+    toggle: ['checkbox'],
+    buttonGroup: ['text'],
+    checkboxGroup: ['textArray'],
+    calendar: ['date'],
+};
+/** Every control and cell the copied registry ships, by the name it looks each up by. */
+export const registryControls = [
+    ...Object.keys(builtInScreenKinds).filter((name) => name !== 'join'),
+    'richText',
+    'upload',
+];
+export const registryCells = ['text', 'email', 'number', 'integer', 'decimal', 'checkbox', 'datetime', 'date', 'textArray', 'uuid', 'relationship', 'join', 'richText', 'upload'];
+/** The built-in controls that draw a field's `options`; the build refuses one over a field that declares none. */
+export const choiceControls = ['radio', 'toggleGroup', 'select', 'nativeSelect', 'combobox', 'buttonGroup', 'checkboxGroup'];

package/dist/screen/generate.d.ts

@@ -0,0 +1,14 @@
+import { type ScreenClient } from './index.ts';
+/**
+ * Writes each screen's `screen.json`, `types.ts`, `files.ts` and route files under `into`, and answers the
+ * stale files. With `check` it writes nothing. `into` must sit under a TanStack Router `routes` folder.
+ */
+export declare const generateScreens: ({ root, screens, into, locales, check, }: {
+    root: URL;
+    screens: Readonly<Record<string, ScreenClient>>;
+    into: URL;
+    locales?: readonly string[];
+    check?: boolean;
+}) => Promise<string[]>;
+/** The command, given the project's own root, answering the code it exits with. */
+export declare const run: (project: URL, check: boolean) => Promise<number>;