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

package/src/lib/parse-type.ts

@@ -0,0 +1,143 @@
+// Parse the TypeScript-like `type` string a template's prop definition
+// carries into a structured kind the propType mapper can switch on.
+
+export type ParsedType =
+  | { kind: 'boolean' }
+  | { kind: 'number' }
+  | { kind: 'string' }
+  | { kind: 'stringOrNumber' }
+  | {
+      kind: 'enum';
+      /** The literals the select offers. */
+      options: (string | boolean)[];
+      /** Whether the type also takes any string (`string & {}` among its
+       *  members), which a story file may set beside the literals. */
+      open?: boolean;
+      /** Whether the type also takes a structured value (an object, an
+       *  array or a tuple among its members), which a story file may set
+       *  beside the literals. */
+      structural?: boolean;
+    }
+  | { kind: 'complex'; raw: string };
+
+/**
+ * Splits a type's text on its top-level `|`, leaving a `|` inside brackets,
+ * braces, parentheses, angle brackets or a template literal alone.
+ *
+ * @param type - The type as written.
+ * @returns Its union members, trimmed.
+ */
+export function unionMembers(type: string): string[] {
+  const members: string[] = [];
+  let depth = 0;
+  let quote: string | undefined;
+  let current = '';
+  for (const character of type) {
+    if (quote) {
+      if (character === quote) quote = undefined;
+    } else if (character === "'" || character === '"' || character === '`') {
+      quote = character;
+    } else if ('([{<'.includes(character)) {
+      depth += 1;
+    } else if (')]}>'.includes(character)) {
+      depth -= 1;
+    } else if (character === '|' && depth === 0) {
+      members.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += character;
+  }
+  members.push(current.trim());
+  return members.filter(Boolean);
+}
+
+/** A string literal in either quote style. */
+const STRING_LITERAL = /^(['"])[^'"]*\1$/;
+
+/** An open string member, `string & {}`: any string, the literals suggested. */
+function isOpenString(member: string): boolean {
+  return /^\(?\s*string\s*&\s*\{\s*\}\s*\)?$/.test(member);
+}
+
+/** A member with structure a select cannot offer but need not: an object, an
+ *  array or tuple, or a read-only array (a responsive value's breakpoint form). */
+function isStructural(member: string): boolean {
+  return (
+    member.startsWith('{') ||
+    member.startsWith('[') ||
+    member.endsWith('[]') ||
+    member.startsWith('readonly ') ||
+    /^(Readonly)?Array</.test(member)
+  );
+}
+
+export function parseType(type: string): ParsedType {
+  // An optional union (`'a' | 'b' | undefined`, `string | null`) is controlled as
+  // its non-nullish members: the control's unset state already covers the rest.
+  const parts = unionMembers(type).filter(
+    (part) => part !== 'undefined' && part !== 'null'
+  );
+  const t = parts.join(' | ');
+  if (t === 'boolean' || t === 'true | false' || t === 'false | true')
+    return { kind: 'boolean' };
+  if (t === 'number') return { kind: 'number' };
+  if (t === 'string') return { kind: 'string' };
+
+  // `string | number` (primitives only, any order)
+  if (
+    parts.length > 1 &&
+    parts.every((part) => part === 'string' || part === 'number')
+  ) {
+    return { kind: 'stringOrNumber' };
+  }
+
+  // A union of string literals (either quote style, as a driver's source may
+  // spell it), e.g. 'soft' | 'solid', is a select of them. So is one that also
+  // takes any string (`string & {}`) or a structured form such as a responsive
+  // value's breakpoint list: the select offers the literals, and a story file sets
+  // the rest. Any other member - a plain `string`, `number`, `boolean` or `false`
+  // the select could not offer, or a name left unresolved - keeps it complex.
+  const literals = parts.filter((part) => STRING_LITERAL.test(part));
+  if (
+    literals.length > 0 &&
+    parts.every(
+      (part) =>
+        STRING_LITERAL.test(part) || isOpenString(part) || isStructural(part)
+    )
+  ) {
+    return {
+      kind: 'enum',
+      options: literals.map((part) => part.slice(1, -1)),
+      ...(parts.some(isOpenString) ? { open: true } : {}),
+      ...(parts.some(isStructural) ? { structural: true } : {}),
+    };
+  }
+
+  // A finite union of string literals and booleans, e.g. boolean |
+  // 'indeterminate', is a select of each: true, false, then the literals.
+  const booleans: string[] = parts.filter(
+    (part) => part === 'boolean' || part === 'true' || part === 'false'
+  );
+  if (
+    literals.length > 0 &&
+    booleans.length > 0 &&
+    parts.every((part) => STRING_LITERAL.test(part) || booleans.includes(part))
+  ) {
+    const values = new Set<boolean>(
+      booleans.flatMap((part) =>
+        part === 'boolean' ? [true, false] : [part === 'true']
+      )
+    );
+    return {
+      kind: 'enum',
+      options: [
+        ...[true, false].filter((value) => values.has(value)),
+        ...literals.map((part) => part.slice(1, -1)),
+      ],
+    };
+  }
+
+  // Record<...>, SomeInterface[], SelectOption[], opaque bags, etc.
+  return { kind: 'complex', raw: t };
+}

package/src/lib/react-spelling.ts

@@ -0,0 +1,235 @@
+// How React takes the attributes a story gives a component. A story spells
+// an attribute as HTML does, the form every other target takes as it is;
+// React takes `class` as `className`, a `style` string as a style object and
+// the attributes it renames by their React names (`tabindex` as `tabIndex`,
+// `for` as `htmlFor`), unless the component declares a prop by that exact
+// name. Browser-safe, with no imports of its own: the React pane, the React
+// registry and the printed React source share it, and the names React gives
+// the attributes it renames are handed in (the React extension's table).
+
+import type { SlotFill } from './types.js';
+
+/**
+ * A plain-CSS `style` string's declarations, split at each `;` outside a
+ * quoted string and outside parentheses, so a `url("data:...;base64,...")`
+ * stays whole.
+ *
+ * @param css - The declarations as a `style` attribute holds them.
+ * @returns Each declaration's text, as written.
+ */
+export function styleDeclarations(css: string): string[] {
+  const declarations: string[] = [];
+  let quote = '';
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < css.length; i++) {
+    const character = css[i];
+    if (quote) {
+      if (character === '\\') i++;
+      else if (character === quote) quote = '';
+    } else if (character === '"' || character === "'") quote = character;
+    else if (character === '(') depth++;
+    else if (character === ')') depth = Math.max(0, depth - 1);
+    else if (character === ';' && depth === 0) {
+      declarations.push(css.slice(start, i));
+      start = i + 1;
+    }
+  }
+  declarations.push(css.slice(start));
+  return declarations;
+}
+
+/** A CSS property's name in a React style object: camel-cased, a vendor
+ *  prefix capitalized (`WebkitLineClamp`) but for `-ms-` (`msOverflowStyle`),
+ *  a custom property (`--gap`) as written. */
+function stylePropertyName(property: string): string {
+  if (property.startsWith('--')) return property;
+  const unprefixed = property.startsWith('-ms-') ? property.slice(1) : property;
+  return unprefixed.replace(/-([a-z])/g, (_, letter: string) =>
+    letter.toUpperCase()
+  );
+}
+
+/**
+ * A plain-CSS `style` string as the properties of a React style object:
+ * each property camel-cased (a vendor prefix capitalized, `-ms-` as `ms`), a
+ * custom property (`--gap`) kept as written. A `;` inside a quoted string or
+ * parentheses stays in its value. A React style object has no
+ * `!important`, so a value marked with it is kept without the mark: the
+ * browser would drop the whole declaration otherwise.
+ *
+ * @param css - The declarations, `;`-separated.
+ * @returns The style object's properties, in their order.
+ * @example
+ * ```ts
+ * styleProperties('padding-inline: 1ch; --gap: 2px'); // { paddingInline: '1ch', '--gap': '2px' }
+ * ```
+ */
+export function styleProperties(css: string): Record<string, string> {
+  const properties: Record<string, string> = {};
+  for (const declaration of styleDeclarations(css)) {
+    const colon = declaration.indexOf(':');
+    if (colon === -1) continue;
+    const property = declaration.slice(0, colon).trim();
+    if (!property) continue;
+    properties[stylePropertyName(property)] = declaration
+      .slice(colon + 1)
+      .trim()
+      .replace(/\s*!\s*important$/i, '');
+  }
+  return properties;
+}
+
+/** Two classes given under both `class` and `className`, joined. */
+function joinedClassName<Value>(
+  previous: Value | Record<string, string> | undefined,
+  next: Value
+): Value | string {
+  if (previous === undefined || previous === null || previous === '')
+    return next;
+  if (next === undefined || next === null || (next as unknown) === '')
+    return previous as Value;
+  return `${String(previous)} ${String(next)}`;
+}
+
+/**
+ * A component's props as React takes them: `class` as `className`, a
+ * `style` string as a style object, and each attribute React renames by its
+ * React name, unless the component declares a prop by that exact name, which
+ * it takes as it is. Any other prop passes unchanged. A story that gives both
+ * `class` and `className` gets the two joined, in their order.
+ *
+ * @param props - The props, as the story gives them.
+ * @param declares - Whether the component declares a prop of a name.
+ * @param attributeNames - The React name of each attribute React renames,
+ *   by its HTML name.
+ * @returns The props, spelled as React takes them, in their order.
+ * @example
+ * ```ts
+ * reactProps({ class: 'w-48', tabindex: 0 }, () => false, { tabindex: 'tabIndex' });
+ * // { className: 'w-48', tabIndex: 0 }
+ * ```
+ */
+export function reactProps<Value>(
+  props: Record<string, Value>,
+  declares: (name: string) => boolean,
+  attributeNames: Readonly<Record<string, string>>
+): Record<string, Value | Record<string, string> | string> {
+  const spelled: Record<string, Value | Record<string, string> | string> = {};
+  for (const [name, value] of Object.entries(props)) {
+    if (declares(name)) spelled[name] = value;
+    else if (name === 'class' || name === 'className')
+      spelled.className = joinedClassName(spelled.className, value);
+    else if (name === 'style' && typeof value === 'string')
+      spelled.style = styleProperties(value);
+    else
+      spelled[
+        Object.prototype.hasOwnProperty.call(attributeNames, name)
+          ? attributeNames[name]
+          : name
+      ] = value;
+  }
+  return spelled;
+}
+
+/**
+ * A slot fill as React takes it: each component's props in it spelled by
+ * {@link reactProps}, and each attribute of an html element React renames by
+ * its React name (`for` as `htmlFor`). An html element's `class` and `style`
+ * stay as written, which the React emitters spell themselves, and opaque
+ * bodies stay as they are.
+ *
+ * @param fill - The fill.
+ * @param declares - Whether a component declares a prop of a name.
+ * @param attributeNames - The React name of each attribute React renames.
+ * @returns The fill, every component's attributes spelled as React takes them.
+ */
+export function reactFill<Fill extends SlotFill | undefined>(
+  fill: Fill,
+  declares: (component: string, name: string) => boolean,
+  attributeNames: Readonly<Record<string, string>>
+): Fill {
+  return fill && (reactFillOf(fill, declares, attributeNames) as Fill);
+}
+
+/** An html element's attributes, each React renames by its React name
+ *  (`for` as `htmlFor`), in their order. `class` and `style` stay as
+ *  written: the React emitters spell those on an element themselves. */
+function renamedAttributes<Value>(
+  attributes: Record<string, Value>,
+  attributeNames: Readonly<Record<string, string>>
+): Record<string, Value> {
+  return Object.fromEntries(
+    Object.entries(attributes).map(([name, value]) => [
+      Object.prototype.hasOwnProperty.call(attributeNames, name)
+        ? attributeNames[name]
+        : name,
+      value,
+    ])
+  );
+}
+
+function reactFillOf(
+  fill: SlotFill,
+  declares: (component: string, name: string) => boolean,
+  attributeNames: Readonly<Record<string, string>>
+): SlotFill {
+  const spell = (child: SlotFill): SlotFill =>
+    reactFillOf(child, declares, attributeNames);
+  if (fill.kind === 'element')
+    return {
+      ...fill,
+      ...(fill.props
+        ? {
+            props: reactProps(
+              fill.props,
+              (name) => declares(fill.component, name),
+              attributeNames
+            ),
+          }
+        : {}),
+      ...(fill.slots
+        ? {
+            slots: Object.fromEntries(
+              Object.entries(fill.slots).map(([slot, slotFill]) => [
+                slot,
+                spell(slotFill),
+              ])
+            ),
+          }
+        : {}),
+      ...(fill.children ? { children: spell(fill.children) } : {}),
+    };
+  if (fill.kind === 'html')
+    return {
+      ...fill,
+      ...(fill.props
+        ? { props: renamedAttributes(fill.props, attributeNames) }
+        : {}),
+      ...(fill.children ? { children: spell(fill.children) } : {}),
+    };
+  if (fill.kind === 'fragment')
+    return { ...fill, children: fill.children.map(spell) };
+  return fill;
+}
+
+/**
+ * The names a component declares that {@link reactProps} would otherwise
+ * respell: `class`, `style` and the attributes React renames. A component
+ * keeps these as they are in React.
+ *
+ * @param declared - The component's declared prop names.
+ * @param attributeNames - The React name of each attribute React renames.
+ * @returns Those of `declared` React would otherwise respell.
+ */
+export function declaredAttributes(
+  declared: Iterable<string>,
+  attributeNames: Readonly<Record<string, string>>
+): string[] {
+  return [...declared].filter(
+    (name) =>
+      name === 'class' ||
+      name === 'style' ||
+      Object.prototype.hasOwnProperty.call(attributeNames, name)
+  );
+}

package/src/lib/scenario-story.ts

@@ -0,0 +1,97 @@
+// A scenario with slot content of its own: the plan it shows, and the story
+// the generator renders for it beside the component's. The panes render a
+// story's slot content as it was generated and take only props at run time,
+// so such a scenario is a story of its own in every target's registry.
+// Browser-safe: no node imports.
+
+import { sanitize, scenarioStoryId } from './naming.js';
+import type { ResolvedStory, Scenario, SlotPlan } from './types.js';
+
+/**
+ * The slot plan one scenario of a story shows: the scenario's own fills over
+ * the story's, slot by slot. A scenario with no slots of its own shows the
+ * story's plan.
+ *
+ * @param story - The story's plan, if it has one.
+ * @param scenario - The scenario's own plan, if it has one.
+ * @returns The plan the scenario shows, or `undefined` when neither has one.
+ */
+export function scenarioSlotPlan(
+  story: SlotPlan | undefined,
+  scenario: SlotPlan | undefined
+): SlotPlan | undefined {
+  if (scenario === undefined) return story;
+  const named = { ...(story?.named ?? {}), ...(scenario.named ?? {}) };
+  const fill = scenario.default ?? story?.default;
+  return {
+    ...(fill === undefined ? {} : { default: fill }),
+    ...(Object.keys(named).length === 0 ? {} : { named }),
+  };
+}
+
+/**
+ * A resolved story as one of its scenarios shows it: with the scenario's
+ * slot plan over the story's. A scenario with no slots of its own, or no
+ * scenario, shows the story as it is.
+ *
+ * @param model - The component's resolved story.
+ * @param scenario - The scenario, when one is meant.
+ * @returns The story to print or render for that scenario.
+ */
+export function storyOnScenario(
+  model: ResolvedStory,
+  scenario: Scenario | undefined
+): ResolvedStory {
+  return scenario?.slots === undefined
+    ? model
+    : { ...model, slots: scenarioSlotPlan(model.slots, scenario.slots) };
+}
+
+/**
+ * The stories of a component's scenarios that have slot content of their
+ * own: one per such scenario, the component's story with the scenario's
+ * plan, under the id the panes mount it by. The panes render a story's slot
+ * content as it was generated, so a scenario that changes it is a story
+ * beside the component's.
+ *
+ * @param model - The component's resolved story.
+ * @returns The scenario stories, in the scenarios' order; none for a
+ *   component whose scenarios set props alone.
+ */
+export function scenarioStories(model: ResolvedStory): ResolvedStory[] {
+  const componentId = sanitize(model.title);
+  return model.scenarios.flatMap((scenario, index) => {
+    if (scenario.slots === undefined) return [];
+    const slots = scenarioSlotPlan(model.slots, scenario.slots);
+    // The placeholder text a component with no plan starts from is the
+    // preview's own; a scenario that fills the default slot replaces it.
+    const withoutPlaceholder = Object.fromEntries(
+      Object.entries(model.defaultProps).filter(([name]) => name !== 'children')
+    );
+    const fillsDefault =
+      slots?.default !== undefined &&
+      model.previewDefaults?.children !== undefined;
+    return [
+      {
+        ...model,
+        ...(fillsDefault ? { defaultProps: withoutPlaceholder } : {}),
+        slots,
+        scenarioStory: {
+          id: scenarioStoryId(componentId, scenario.id),
+          renderName: `${model.name}_scenario${index}`,
+        },
+      },
+    ];
+  });
+}
+
+/**
+ * The id a pane mounts a resolved story by: a scenario story's own, or the
+ * one derived from the title.
+ *
+ * @param model - The resolved story.
+ * @returns Its id in every target's registry.
+ */
+export function storyRegistryId(model: ResolvedStory): string {
+  return model.scenarioStory?.id ?? sanitize(model.title);
+}

package/src/lib/slot-fill.ts

@@ -0,0 +1,102 @@
+// Component references in a slot fill tree, collected so a generated registry
+// imports them. Kept dependency-free in lib/ so both the generator (model.ts)
+// and the dev middleware's scratch regeneration (emit/scratch.ts) share it without the
+// middleware pulling in the generation-time story file graph.
+
+import type { PartFill, SlotFill } from './types.js';
+
+const SLOT_FILL_KINDS = new Set<SlotFill['kind']>([
+  'text',
+  'element',
+  'html',
+  'fragment',
+  'raw',
+  'scoped',
+  'part',
+]);
+
+/** Adds every component name a fill tree references to `into`: each `element`'s
+ *  component, and the declared `imports` of an opaque `raw` or `scoped` body
+ *  or a part's, unless `parts` is false. */
+export function collectSlotComponents(
+  fill: SlotFill | undefined,
+  into: Set<string>,
+  parts = true
+): void {
+  if (!fill) return;
+  // Fail loudly on a malformed fill rather than letting it flow downstream, where
+  // an emitter silently generates `<undefined>`. The most common slip is an array
+  // where a single SlotFill is expected - multiple children need a fragment.
+  if (
+    typeof fill !== 'object' ||
+    Array.isArray(fill) ||
+    !SLOT_FILL_KINDS.has((fill as SlotFill).kind)
+  ) {
+    throw new Error(
+      `Invalid slot fill: expected a SlotFill object with a known "kind", got ${
+        Array.isArray(fill)
+          ? 'an array - wrap multiple children in { kind: "fragment", children: [...] }'
+          : JSON.stringify(fill)
+      }.`
+    );
+  }
+  if (fill.kind === 'element') {
+    into.add(fill.component);
+    for (const slotFill of Object.values(fill.slots ?? {}))
+      collectSlotComponents(slotFill, into, parts);
+    collectSlotComponents(fill.children, into, parts);
+  } else if (fill.kind === 'html') {
+    collectSlotComponents(fill.children, into, parts);
+  } else if (fill.kind === 'fragment') {
+    for (const child of fill.children)
+      collectSlotComponents(child, into, parts);
+  } else if (
+    fill.kind === 'raw' ||
+    fill.kind === 'scoped' ||
+    (fill.kind === 'part' && parts)
+  ) {
+    // A raw/scoped/part body is opaque, so it declares its component references explicitly.
+    for (const name of fill.imports ?? []) into.add(name);
+  }
+}
+
+/**
+ * The parts a story's slot content calls, by name, in the order first called.
+ * A part is called in the content's tree; a call inside a body is the body's
+ * own markup and declares nothing.
+ *
+ * @param fills - The story's slot fills: its default slot and named slots.
+ * @returns Each part's call, carrying its declaration.
+ * @throws When two calls of one name declare different parts.
+ */
+export function collectParts(
+  fills: Iterable<SlotFill | undefined>
+): Map<string, PartFill> {
+  const parts = new Map<string, PartFill>();
+  const visit = (fill: SlotFill | undefined): void => {
+    if (!fill) return;
+    if (fill.kind === 'element') {
+      for (const slotFill of Object.values(fill.slots ?? {})) visit(slotFill);
+      visit(fill.children);
+    } else if (fill.kind === 'html') {
+      visit(fill.children);
+    } else if (fill.kind === 'fragment') {
+      fill.children.forEach(visit);
+    } else if (fill.kind === 'part') {
+      const known = parts.get(fill.name);
+      if (!known) parts.set(fill.name, fill);
+      else if (declarationOf(known) !== declarationOf(fill))
+        throw new Error(
+          `Two calls of the part ${fill.name} declare it differently; every call carries the same declaration.`
+        );
+    }
+  };
+  for (const fill of fills) visit(fill);
+  return parts;
+}
+
+/** A part's declaration, without the props one call passes, as a key. */
+function declarationOf(part: PartFill): string {
+  const { props: _props, ...declaration } = part;
+  return JSON.stringify(declaration);
+}

package/src/lib/template-files.ts

@@ -0,0 +1,31 @@
+// Which files in a templates directory are component templates: the rule
+// the kit's build reads `src/components/` by, so the preview shows a story
+// for every component the build emits.
+
+/** The extensions of a component template file, as the kit's build reads
+ *  them: JSON, TypeScript and JavaScript in each module form. */
+export const TEMPLATE_FILE_EXTENSIONS = [
+  '.json',
+  '.ts',
+  '.js',
+  '.mjs',
+  '.cjs',
+] as const;
+
+/**
+ * Whether a file name is a component template's: one of
+ * {@link TEMPLATE_FILE_EXTENSIONS}, a declaration file (`.d.ts`) left out.
+ *
+ * @param fileName - The file's name or path.
+ * @returns Whether the kit's build reads it as a template.
+ * @example
+ * isTemplateFile('badge.json'); // true
+ * isTemplateFile('badge.d.ts'); // false
+ */
+export function isTemplateFile(fileName: string): boolean {
+  return (
+    TEMPLATE_FILE_EXTENSIONS.some((extension) =>
+      fileName.endsWith(extension)
+    ) && !fileName.endsWith('.d.ts')
+  );
+}