@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/dist/lib/exported-types.js

@@ -0,0 +1,86 @@
+// The type names a component's generated module exports, which the kit's
+// package entry re-exports with everything else the module exports: the
+// exported declarations among a template's module-scope lines, as each
+// target places them. Browser-safe.
+const IDENTIFIER = '[A-Za-z_$][\\w$]*';
+/** A declaration that names a type: `export interface X`, `export type X =`,
+ *  `export enum X`, `export class X` (each with `declare` or `abstract`). */
+const TYPE_DECLARATION = new RegExp(`^\\s*export\\s+(?:declare\\s+)?(?:(?:abstract\\s+)?class|interface|type|(?:const\\s+)?enum)\\s+(${IDENTIFIER})`);
+/** An export list: `export { A, B as C }` or `export type { A } from '...'`. */
+const EXPORT_LIST = /^\s*export\s+(type\s+)?\{([^}]*)\}/;
+/**
+ * The type names one module-scope line exports. A value-only export list
+ * (`export { a }`) names no type unless a member is marked `type`, as a value
+ * cannot be told from a type there.
+ *
+ * @param line - A verbatim module-scope line.
+ * @returns The type names it exports, in order.
+ */
+export function exportedTypeNamesOf(line) {
+    const declaration = TYPE_DECLARATION.exec(line);
+    if (declaration)
+        return [declaration[1]];
+    const list = EXPORT_LIST.exec(line);
+    if (!list)
+        return [];
+    const typeOnly = list[1] !== undefined;
+    return list[2]
+        .split(',')
+        .map((member) => member.trim())
+        .filter((member) => member !== '' && (typeOnly || /^type\s/.test(member)))
+        .map((member) => member
+        .replace(/^type\s+/, '')
+        .split(/\s+as\s+/)
+        .pop()
+        .trim())
+        .filter((name) => new RegExp(`^${IDENTIFIER}$`).test(name));
+}
+/**
+ * The type names a template's generated module exports in one scripted
+ * target: those its module-scope lines declare, the target's own `imports`
+ * merged in (or in their place, with `importsStrategy: 'replace'`).
+ *
+ * @param template - The component's template.
+ * @param target - The scripted target.
+ * @returns The exported type names, each once.
+ * @example
+ * ```ts
+ * exportedTypeNames({ imports: ['export interface DateValue { day: string }'] }, 'react');
+ * // ['DateValue']
+ * ```
+ */
+export function exportedTypeNames(template, target) {
+    const override = template.extensions?.[target];
+    const own = Array.isArray(override?.imports)
+        ? override.imports.filter((line) => typeof line === 'string')
+        : undefined;
+    const lines = own === undefined
+        ? (template.imports ?? [])
+        : override?.importsStrategy === 'replace'
+            ? own
+            : [...(template.imports ?? []), ...own];
+    return [
+        ...new Set(lines.flatMap((entry) => entry.split('\n').flatMap(exportedTypeNamesOf))),
+    ];
+}
+/**
+ * The type names a component's generated module exports, per scripted
+ * target: none for a component written by hand, whose module the preview
+ * does not read.
+ *
+ * @param component - The component, with the template it was read from.
+ * @param targets - The scripted targets the kit builds.
+ * @returns The names per target that exports any, or `undefined` when none does.
+ */
+export function exportedTypesOf(component, targets) {
+    const template = component.template;
+    if (!template || typeof template !== 'object' || Array.isArray(template))
+        return undefined;
+    const types = {};
+    for (const target of targets) {
+        const names = exportedTypeNames(template, target);
+        if (names.length > 0)
+            types[target] = names;
+    }
+    return Object.keys(types).length > 0 ? types : undefined;
+}

package/dist/lib/html-attributes.d.ts

@@ -0,0 +1,2 @@
+/** Whether `name` is a native HTML attribute a passthrough root forwards. */
+export declare function isHtmlAttribute(name: string): boolean;

package/dist/lib/html-attributes.js

@@ -0,0 +1,111 @@
+// Native attribute names a passthrough component forwards to its root element,
+// so a story file may set them beside the declared props. The global attributes
+// plus those of the elements a passthrough root usually is (form controls,
+// links, media, tables); `aria-*` and `data-*` are matched by prefix. Spelled
+// as in HTML, the form a story file's value reaches every target in.
+const HTML_ATTRIBUTES = new Set([
+    // global
+    'accesskey',
+    'autocapitalize',
+    'autofocus',
+    'class',
+    'contenteditable',
+    'dir',
+    'draggable',
+    'enterkeyhint',
+    'hidden',
+    'id',
+    'inert',
+    'inputmode',
+    'is',
+    'lang',
+    'nonce',
+    'part',
+    'popover',
+    'role',
+    'slot',
+    'spellcheck',
+    'style',
+    'tabindex',
+    'title',
+    'translate',
+    // forms
+    'accept',
+    'action',
+    'autocomplete',
+    'checked',
+    'cols',
+    'dirname',
+    'disabled',
+    'enctype',
+    'for',
+    'form',
+    'formaction',
+    'formenctype',
+    'formmethod',
+    'formnovalidate',
+    'formtarget',
+    'list',
+    'max',
+    'maxlength',
+    'method',
+    'min',
+    'minlength',
+    'multiple',
+    'name',
+    'novalidate',
+    'pattern',
+    'placeholder',
+    'readonly',
+    'required',
+    'rows',
+    'selected',
+    'size',
+    'step',
+    'type',
+    'value',
+    'wrap',
+    'popovertarget',
+    'popovertargetaction',
+    'label',
+    'open',
+    // links and media
+    'alt',
+    'download',
+    'height',
+    'href',
+    'hreflang',
+    'loading',
+    'media',
+    'ping',
+    'referrerpolicy',
+    'rel',
+    'sizes',
+    'src',
+    'srcset',
+    'target',
+    'width',
+    'decoding',
+    'crossorigin',
+    'poster',
+    'controls',
+    'autoplay',
+    'loop',
+    'muted',
+    'playsinline',
+    'preload',
+    // tables and lists
+    'colspan',
+    'rowspan',
+    'headers',
+    'scope',
+    'span',
+    'reversed',
+    'start',
+    'datetime',
+    'cite',
+]);
+/** Whether `name` is a native HTML attribute a passthrough root forwards. */
+export function isHtmlAttribute(name) {
+    return HTML_ATTRIBUTES.has(name) || /^(aria|data)-[a-z0-9-]+$/.test(name);
+}

package/dist/lib/html-warnings.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Summarizes repeated html warnings: the warnings one component gives for
+ * the same reason, such as `baseId is not defined`, become one line counting
+ * the expressions, at the place of the first; a warning whose reason no other
+ * warning of its component shares stays as it is, as does any warning that
+ * is not an expression that could not be evaluated.
+ *
+ * @param warnings - The warnings, as the render gives them.
+ * @returns The warnings, each kind of repeated warning once.
+ * @example
+ * ```ts
+ * summarizeHtmlWarnings([
+ *   "Tabs: could not evaluate baseId + '-list' (baseId is not defined)",
+ *   "Tabs: could not evaluate baseId + '-panel' (baseId is not defined)",
+ * ]);
+ * // ['Tabs: could not evaluate 2 expressions (baseId is not defined)']
+ * ```
+ */
+export declare function summarizeHtmlWarnings(warnings: readonly string[]): string[];

package/dist/lib/html-warnings.js

@@ -0,0 +1,79 @@
+// What a story's html could not evaluate at rest, summarized for reading: a
+// name that only the component's script defines, such as a per-instance id
+// or its state, fails every expression that reads it, so a component that
+// reads it in several places would otherwise repeat one warning per
+// expression and bury the warnings that differ.
+/** A warning as the render words it: `Name: could not evaluate expression (reason)`. */
+const UNEVALUATED = /^(?:(.+?): )?could not evaluate ([\s\S]+)$/;
+/**
+ * Summarizes repeated html warnings: the warnings one component gives for
+ * the same reason, such as `baseId is not defined`, become one line counting
+ * the expressions, at the place of the first; a warning whose reason no other
+ * warning of its component shares stays as it is, as does any warning that
+ * is not an expression that could not be evaluated.
+ *
+ * @param warnings - The warnings, as the render gives them.
+ * @returns The warnings, each kind of repeated warning once.
+ * @example
+ * ```ts
+ * summarizeHtmlWarnings([
+ *   "Tabs: could not evaluate baseId + '-list' (baseId is not defined)",
+ *   "Tabs: could not evaluate baseId + '-panel' (baseId is not defined)",
+ * ]);
+ * // ['Tabs: could not evaluate 2 expressions (baseId is not defined)']
+ * ```
+ */
+export function summarizeHtmlWarnings(warnings) {
+    const groups = new Map();
+    const entries = [];
+    for (const warning of warnings) {
+        const parsed = parseWarning(warning);
+        if (parsed === undefined) {
+            entries.push(warning);
+            continue;
+        }
+        const key = `${parsed.component ?? ''}\u0000${parsed.reason}`;
+        const group = groups.get(key);
+        if (group === undefined) {
+            groups.set(key, { ...parsed, warnings: [warning] });
+            entries.push({ key });
+        }
+        else if (!group.warnings.includes(warning)) {
+            group.warnings.push(warning);
+        }
+    }
+    return entries.map((entry) => {
+        if (typeof entry === 'string')
+            return entry;
+        const group = groups.get(entry.key);
+        if (group.warnings.length === 1)
+            return group.warnings[0];
+        const prefix = group.component === undefined ? '' : `${group.component}: `;
+        return `${prefix}could not evaluate ${group.warnings.length} expressions (${group.reason})`;
+    });
+}
+/** A warning's component and the reason in its closing parentheses, which
+ *  may hold parentheses of their own. */
+function parseWarning(warning) {
+    const match = UNEVALUATED.exec(warning);
+    if (match === null || !warning.endsWith(')'))
+        return undefined;
+    let depth = 0;
+    for (let index = warning.length - 1; index >= 0; index--) {
+        const character = warning[index];
+        if (character === ')')
+            depth++;
+        else if (character === '(') {
+            depth--;
+            if (depth === 0) {
+                if (warning[index - 1] !== ' ')
+                    return undefined;
+                const reason = warning.slice(index + 1, -1);
+                return match[1] === undefined
+                    ? { reason }
+                    : { component: match[1], reason };
+            }
+        }
+    }
+    return undefined;
+}

package/dist/lib/jsx-roots.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A React body as one JSX expression: JSX content that is not one already in
+ * a fragment, anything else as given.
+ *
+ * Content opening with a tag goes in a fragment when it has two or more root
+ * nodes. Content opening with anything an expression cannot open with - a
+ * `{name}` placeholder, punctuation - is text, and goes in one too. Content
+ * opening as an expression can (a word, a number, a bracket, a quote) is an
+ * expression (`row.name`, `open && <Badge />`) unless it reads as text: two
+ * words side by side (`4 messages`), or a word followed by a placeholder or a
+ * tag (`hello {name}`, `remove <Button />`). A body the scanner cannot read
+ * through is left as given.
+ *
+ * @param body - The React body, as the fill gives it.
+ * @returns The body, in `<>...</>` when it is not one JSX expression.
+ * @example
+ * singleJsxRoot('<Button label="keep" /><Button label="empty" />');
+ * // '<><Button label="keep" /><Button label="empty" /></>'
+ * singleJsxRoot('{name}');
+ * // '<>{name}</>'
+ */
+export declare function singleJsxRoot(body: string): string;

package/dist/lib/jsx-roots.js

@@ -0,0 +1,243 @@
+// A React body (a scoped fill's or a part's) is written where JSX takes one
+// expression: an arrow's body, a `return (...)`. Content of two or more root
+// nodes - two sibling elements, an element and text - is no expression there,
+// and neither is text alone (`{name}` after `=>` reads as a block), so each
+// goes in a fragment. Vue and Svelte bodies are markup, which takes them as
+// they are. A plain scanner rather than a parser: the printed source also runs
+// in the browser.
+/** Words that stand before an operand, so a word after them is no text. */
+const PREFIX_KEYWORDS = new Set(['typeof', 'void', 'new', 'await', 'delete']);
+/** Words that stand between operands, so the words beside them are no text. */
+const INFIX_KEYWORDS = new Set(['in', 'instanceof', 'as', 'satisfies']);
+/**
+ * A React body as one JSX expression: JSX content that is not one already in
+ * a fragment, anything else as given.
+ *
+ * Content opening with a tag goes in a fragment when it has two or more root
+ * nodes. Content opening with anything an expression cannot open with - a
+ * `{name}` placeholder, punctuation - is text, and goes in one too. Content
+ * opening as an expression can (a word, a number, a bracket, a quote) is an
+ * expression (`row.name`, `open && <Badge />`) unless it reads as text: two
+ * words side by side (`4 messages`), or a word followed by a placeholder or a
+ * tag (`hello {name}`, `remove <Button />`). A body the scanner cannot read
+ * through is left as given.
+ *
+ * @param body - The React body, as the fill gives it.
+ * @returns The body, in `<>...</>` when it is not one JSX expression.
+ * @example
+ * singleJsxRoot('<Button label="keep" /><Button label="empty" />');
+ * // '<><Button label="keep" /><Button label="empty" /></>'
+ * singleJsxRoot('{name}');
+ * // '<>{name}</>'
+ */
+export function singleJsxRoot(body) {
+    const trimmed = body.trim();
+    if (trimmed === '')
+        return body;
+    if (trimmed.startsWith('<')) {
+        const roots = countRoots(trimmed);
+        return roots !== undefined && roots > 1 ? `<>${trimmed}</>` : body;
+    }
+    const opensExpression = /^[A-Za-z0-9_$([!+\-~.'"`]/.test(trimmed);
+    return !opensExpression || readsAsText(trimmed) ? `<>${trimmed}</>` : body;
+}
+/** Whether content that opens as an expression can is text instead: two
+ *  words side by side, or a word before a placeholder or a tag, outside
+ *  brackets. */
+function readsAsText(content) {
+    let depth = 0;
+    // The word last read at the top level, while only whitespace follows it.
+    let previousWord;
+    let index = 0;
+    while (index < content.length) {
+        const character = content[index];
+        if (character === '"' || character === "'" || character === '`') {
+            const end = stringEnd(content, index);
+            // A quote that never closes is an apostrophe in text.
+            if (end === undefined)
+                return true;
+            index = end;
+            previousWord = undefined;
+            continue;
+        }
+        if (depth === 0) {
+            const word = /^[A-Za-z0-9_$]+/.exec(content.slice(index))?.[0];
+            if (word) {
+                const spaced = index > 0 && /\s/.test(content[index - 1]);
+                if (previousWord !== undefined &&
+                    spaced &&
+                    !PREFIX_KEYWORDS.has(previousWord) &&
+                    !INFIX_KEYWORDS.has(previousWord) &&
+                    !INFIX_KEYWORDS.has(word))
+                    return true;
+                previousWord = word;
+                index += word.length;
+                continue;
+            }
+            if (/\s/.test(character)) {
+                index++;
+                continue;
+            }
+            if (previousWord !== undefined && character === '{')
+                return true;
+            if (character === '<' && /[A-Za-z>]/.test(content[index + 1] ?? '')) {
+                const elementClose = elementEnd(content, index);
+                if (elementClose !== undefined) {
+                    // A tag after a word is text beside an element; after an operator
+                    // it is an operand, read past whole.
+                    if (previousWord !== undefined)
+                        return true;
+                    index = elementClose;
+                    continue;
+                }
+            }
+            // A word joined to what follows by punctuation (`row.name`) is one
+            // expression, not text.
+            previousWord = undefined;
+        }
+        if (character === '(' || character === '[' || character === '{')
+            depth++;
+        else if (character === ')' || character === ']' || character === '}')
+            depth--;
+        index++;
+    }
+    return false;
+}
+/** The root nodes of JSX content, or `undefined` when it does not read through. */
+function countRoots(content) {
+    let roots = 0;
+    let index = 0;
+    while (index < content.length) {
+        const character = content[index];
+        if (/\s/.test(character)) {
+            index++;
+            continue;
+        }
+        const end = character === '<'
+            ? elementEnd(content, index)
+            : character === '{'
+                ? braceEnd(content, index)
+                : textEnd(content, index);
+        if (end === undefined)
+            return undefined;
+        roots++;
+        index = end;
+    }
+    return roots;
+}
+/** The index past a run of text, at the next tag or expression. */
+function textEnd(content, start) {
+    let index = start;
+    while (index < content.length &&
+        content[index] !== '<' &&
+        content[index] !== '{')
+        index++;
+    return index;
+}
+/** The index past the element (or fragment) that opens at `start`. */
+function elementEnd(content, start) {
+    let depth = 0;
+    let index = start;
+    while (index < content.length) {
+        const character = content[index];
+        if (character === '{') {
+            const end = braceEnd(content, index);
+            if (end === undefined)
+                return undefined;
+            index = end;
+            continue;
+        }
+        if (character !== '<') {
+            index++;
+            continue;
+        }
+        const closing = content[index + 1] === '/';
+        const end = tagEnd(content, index);
+        if (end === undefined)
+            return undefined;
+        const selfClosing = !closing && content[end - 2] === '/';
+        if (closing)
+            depth--;
+        else if (!selfClosing)
+            depth++;
+        index = end;
+        if (depth === 0)
+            return index;
+        if (depth < 0)
+            return undefined;
+    }
+    return undefined;
+}
+/** The index past a tag's `>`, its attribute strings and expressions skipped. */
+function tagEnd(content, start) {
+    let index = start + 1;
+    while (index < content.length) {
+        const character = content[index];
+        if (character === '>')
+            return index + 1;
+        if (character === '"' || character === "'") {
+            const end = content.indexOf(character, index + 1);
+            if (end === -1)
+                return undefined;
+            index = end + 1;
+            continue;
+        }
+        if (character === '{') {
+            const end = braceEnd(content, index);
+            if (end === undefined)
+                return undefined;
+            index = end;
+            continue;
+        }
+        index++;
+    }
+    return undefined;
+}
+/** The index past the `}` that balances the `{` at `start`, strings skipped. */
+function braceEnd(content, start) {
+    let depth = 0;
+    let index = start;
+    while (index < content.length) {
+        const character = content[index];
+        if (character === '"' || character === "'" || character === '`') {
+            const end = stringEnd(content, index);
+            if (end === undefined)
+                return undefined;
+            index = end;
+            continue;
+        }
+        if (character === '{')
+            depth++;
+        else if (character === '}') {
+            depth--;
+            if (depth === 0)
+                return index + 1;
+        }
+        index++;
+    }
+    return undefined;
+}
+/** The index past a string literal opening at `start`, escapes and a template's
+ *  `${...}` skipped. */
+function stringEnd(content, start) {
+    const quote = content[start];
+    let index = start + 1;
+    while (index < content.length) {
+        const character = content[index];
+        if (character === '\\') {
+            index += 2;
+            continue;
+        }
+        if (character === quote)
+            return index + 1;
+        if (quote === '`' && character === '$' && content[index + 1] === '{') {
+            const end = braceEnd(content, index + 1);
+            if (end === undefined)
+                return undefined;
+            index = end;
+            continue;
+        }
+        index++;
+    }
+    return undefined;
+}

package/dist/lib/module-of-source.d.ts

@@ -0,0 +1,18 @@
+/** The token a source's `moduleBase` names its target with. */
+export declare const TARGET_TOKEN = "{target}";
+/**
+ * The module a source's components are imported from for one target: the
+ * source's `moduleBase` with `{target}` replaced by the target, or, when it
+ * has no `{target}`, the target as a subpath of it.
+ *
+ * @param moduleBase - The source's `moduleBase`.
+ * @param target - The target, such as `'react'`.
+ * @returns The module specifier.
+ * @example
+ * ```ts
+ * moduleOfSource('my-ui-kit', 'react'); // 'my-ui-kit/react'
+ * moduleOfSource('@acme/{target}', 'react'); // '@acme/react'
+ * moduleOfSource('acme-{target}', 'vue'); // 'acme-vue'
+ * ```
+ */
+export declare function moduleOfSource(moduleBase: string, target: string): string;

package/dist/lib/module-of-source.js

@@ -0,0 +1,24 @@
+// The module a source's components are imported from for one target, shared by
+// the generator (Node) and the controller's source printer (browser).
+/** The token a source's `moduleBase` names its target with. */
+export const TARGET_TOKEN = '{target}';
+/**
+ * The module a source's components are imported from for one target: the
+ * source's `moduleBase` with `{target}` replaced by the target, or, when it
+ * has no `{target}`, the target as a subpath of it.
+ *
+ * @param moduleBase - The source's `moduleBase`.
+ * @param target - The target, such as `'react'`.
+ * @returns The module specifier.
+ * @example
+ * ```ts
+ * moduleOfSource('my-ui-kit', 'react'); // 'my-ui-kit/react'
+ * moduleOfSource('@acme/{target}', 'react'); // '@acme/react'
+ * moduleOfSource('acme-{target}', 'vue'); // 'acme-vue'
+ * ```
+ */
+export function moduleOfSource(moduleBase, target) {
+    return moduleBase.includes(TARGET_TOKEN)
+        ? moduleBase.split(TARGET_TOKEN).join(target)
+        : `${moduleBase}/${target}`;
+}

package/dist/lib/naming.d.ts

@@ -0,0 +1,29 @@
+export declare function sanitize(value: string): string;
+/** The id of the preview's own Empty scenario, which renders a component
+ *  with its slots empty: no scenario of a story's takes it. */
+export declare const EMPTY_SCENARIO_ID = "empty";
+/**
+ * The id a pane mounts the story of one scenario by, when the scenario has
+ * slot content of its own: the component's id and the scenario's, with two
+ * hyphens between, which no component id holds.
+ *
+ * @param componentId - The component's story id.
+ * @param scenarioId - The scenario's id.
+ * @returns The scenario story's id.
+ * @example
+ * ```ts
+ * scenarioStoryId('components-notice', 'warning'); // 'components-notice--warning'
+ * ```
+ */
+export declare function scenarioStoryId(componentId: string, scenarioId: string): string;
+export declare function storyId(title: string, exportName: string): string;
+/**
+ * The name a kit's build gives a template without a component node, from its
+ * file: the stem's alphanumeric runs in PascalCase, `_` before a leading
+ * digit, `Component` when nothing is left (`theme-toggle.ts` → `ThemeToggle`,
+ * `2up.grid.ts` → `_2upGrid`). A copy of `componentNameFromFilePath` in
+ * scaffold-ui-kit's `template-sources.ts`, the source of truth, which this
+ * package cannot import; the two must agree, since the name namespaces the
+ * `data-jte-node` markers the kit's stylesheet selects.
+ */
+export declare function componentNameFromFile(file: string): string;