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

package/src/landing.ts

@@ -0,0 +1,58 @@
+// The entry a kit names for the preview to open on (`preview.landing`),
+// checked against the kit's stories: the generator and the check both refuse
+// a story or scenario the kit has none of. A view's id is the views module's,
+// which only the browser loads, so the preview's controller checks that one.
+
+import { sanitize } from './lib/naming.js';
+import type {
+  PreviewLandingConfiguration,
+  ResolvedStory,
+} from './lib/types.js';
+
+/** The id of the synthetic scenario that renders a story with no content. */
+const EMPTY_SCENARIO_ID = 'empty';
+
+/**
+ * What is wrong with the landing entry a kit names, against its stories:
+ * a component with no story, or a scenario the story does not have. A
+ * view's id is not checked here. Empty when the entry is sound or unset.
+ *
+ * @param landing - The kit's `preview.landing`.
+ * @param stories - The kit's browseable stories: omitted components and those
+ *   that are not standalone left out.
+ * @returns One message per problem.
+ * @example
+ * ```ts
+ * landingProblems({ component: 'components-button', scenario: 'primary' }, stories);
+ * ```
+ */
+export function landingProblems(
+  landing: PreviewLandingConfiguration | undefined,
+  stories: readonly ResolvedStory[]
+): string[] {
+  if (!landing || !('component' in landing)) return [];
+  const story = stories.find(
+    (candidate) => sanitize(candidate.title) === landing.component
+  );
+  if (!story)
+    return [
+      `preview.landing names component '${landing.component}', which has no story; a story's id is the one the preview's address carries as component=`,
+    ];
+  const scenario = landing.scenario;
+  if (scenario === undefined) return [];
+  const hasContent =
+    story.contentSlots.default || story.contentSlots.named.length > 0;
+  const scenarios = [
+    ...(hasContent ? [EMPTY_SCENARIO_ID] : []),
+    ...story.scenarios.map((candidate) => candidate.id),
+  ];
+  return scenarios.includes(scenario)
+    ? []
+    : [
+        `preview.landing names scenario '${scenario}' of '${landing.component}', which has ${
+          scenarios.length > 0
+            ? `the scenarios ${scenarios.join(', ')}`
+            : 'no scenarios'
+        }`,
+      ];
+}

package/src/lib/exported-types.ts

@@ -0,0 +1,114 @@
+// 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.
+
+import type { Target } from './types.js';
+
+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: string): string[] {
+  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 parts of a template the exported types are read from. */
+export interface ExportingTemplate {
+  imports?: string[];
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * 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: ExportingTemplate,
+  target: Target
+): string[] {
+  const override = template.extensions?.[target] as
+    | { imports?: unknown; importsStrategy?: unknown }
+    | undefined;
+  const own = Array.isArray(override?.imports)
+    ? override.imports.filter(
+        (line): line is string => 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: { template?: unknown },
+  targets: readonly Target[]
+): Partial<Record<Target, string[]>> | undefined {
+  const template = component.template;
+  if (!template || typeof template !== 'object' || Array.isArray(template))
+    return undefined;
+  const types: Partial<Record<Target, string[]>> = {};
+  for (const target of targets) {
+    const names = exportedTypeNames(template as ExportingTemplate, target);
+    if (names.length > 0) types[target] = names;
+  }
+  return Object.keys(types).length > 0 ? types : undefined;
+}

package/src/lib/html-attributes.ts

@@ -0,0 +1,113 @@
+// 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: string): boolean {
+  return HTML_ATTRIBUTES.has(name) || /^(aria|data)-[a-z0-9-]+$/.test(name);
+}

package/src/lib/html-warnings.ts

@@ -0,0 +1,81 @@
+// 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: readonly string[]): string[] {
+  const groups = new Map<
+    string,
+    { component?: string; reason: string; warnings: string[] }
+  >();
+  const entries: Array<string | { key: string }> = [];
+  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: string
+): { component?: string; reason: string } | undefined {
+  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/src/lib/jsx-roots.ts

@@ -0,0 +1,238 @@
+// 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: string): string {
+  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: string): boolean {
+  let depth = 0;
+  // The word last read at the top level, while only whitespace follows it.
+  let previousWord: string | undefined;
+  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: string): number | undefined {
+  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: string, start: number): number {
+  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: string, start: number): number | undefined {
+  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: string, start: number): number | undefined {
+  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: string, start: number): number | undefined {
+  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: string, start: number): number | undefined {
+  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/src/lib/module-of-source.ts

@@ -0,0 +1,26 @@
+// 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: string, target: string): string {
+  return moduleBase.includes(TARGET_TOKEN)
+    ? moduleBase.split(TARGET_TOKEN).join(target)
+    : `${moduleBase}/${target}`;
+}

package/src/lib/naming.ts

@@ -0,0 +1,65 @@
+// Id / title helpers. The id algorithm (lowercase, non-alphanumerics → '-',
+// collapse, trim) keeps component ids deterministic and identical across the
+// per-target registries and the host manifest - which is what the
+// nav ↔ render lookup and the side-by-side iframe panes depend on. Pinned by
+// naming.test.ts.
+
+export function sanitize(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-+/g, '-');
+}
+
+/** 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 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 function scenarioStoryId(
+  componentId: string,
+  scenarioId: string
+): string {
+  return `${componentId}--${scenarioId}`;
+}
+
+export function storyId(title: string, exportName: string): string {
+  return `${sanitize(title)}--${sanitize(exportName)}`;
+}
+
+/**
+ * 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 function componentNameFromFile(file: string): string {
+  const base = file.slice(
+    Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')) + 1
+  );
+  const dot = base.lastIndexOf('.');
+  const stem = dot > 0 ? base.slice(0, dot) : base;
+  const name = stem
+    .split(/[^a-zA-Z0-9]+/)
+    .filter((segment) => segment.length > 0)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join('');
+  if (name === '') return 'Component';
+  return /^[0-9]/.test(name) ? `_${name}` : name;
+}