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

package/dist/declarations/src/emit/manifest.d.ts

@@ -0,0 +1,138 @@
+import type { ContentSlots, JsonValue, PreviewLabels, PreviewLandingConfiguration, PreviewPaneWidth, PreviewPersistence, SlotPlan, StoryAround, PreviewBinding, ResolvedStory, PreviewPropType, Target } from '../lib/types.js';
+import type { PreviewTarget } from '../protocol.js';
+import type { ViewFramework } from '../views.js';
+export interface ManifestComponent {
+    id: string;
+    name: string;
+    title: string;
+    /** What the component is, from its template. Absent when it has none. */
+    description?: string;
+    category: string;
+    /** Each prop's control and its declaration (type as written, whether it is
+     *  required, the component's own default). */
+    propTypes: PreviewPropType[];
+    /** The props that are events: functions returning nothing, which the
+     *  component calls as things happen. Absent when there are none. */
+    events?: string[];
+    /** The component's two-way props. Absent when there are none. */
+    bindings?: PreviewBinding[];
+    defaultProps: Record<string, JsonValue>;
+    /** The values in `defaultProps` the preview starts from on its own (a kit
+     *  hint's), which a consumer's source leaves out. Absent when there are none. */
+    previewDefaults?: Record<string, JsonValue>;
+    scenarios: {
+        id: string;
+        label: string;
+        /** What the scenario shows, from the story file. Absent when it has none. */
+        description?: string;
+        props: Record<string, JsonValue>;
+        /** The option values picking the scenario sets. Absent when it sets none. */
+        options?: Record<string, string | boolean>;
+        default?: boolean;
+        generated?: boolean;
+        /** The slot content the scenario shows, when it has content of its own:
+         *  its fills over the story's. Absent when it shows the story's. */
+        content?: SlotPlan;
+        /** The id the panes mount the scenario's story by, when it has content
+         *  of its own. Absent when the panes mount the component's story. */
+        story?: string;
+    }[];
+    /** The slots this component accepts - the editor's add-content targets. */
+    slots: ContentSlots;
+    /** `false` for a component with no story of its own: present for the
+     *  editor's picker, hidden from the story navigation (see
+     *  Story.standalone). Absent ⇒ a normal browseable story. */
+    standalone?: boolean;
+    /** A story reachable at its address but left out of the navigation, the
+     *  editor's picker and the counts (see Story.unlisted). Absent ⇒ listed. */
+    unlisted?: boolean;
+    /** The story file's curated slot content, so the per-story editor seeds its tree
+     *  from what the browse view already renders. Absent
+     *  when the component has no story file slot plan. */
+    content?: SlotPlan;
+    /** The content the story renders beside the component (see Story.around).
+     *  Absent when it has none. */
+    around?: StoryAround;
+    /** Per-story preview-option defaults / availability (see Story.options). Absent
+     *  when the component curates none. */
+    options?: Record<string, JsonValue | false>;
+    /** The preview source this component belongs to (`ManifestSource.id`). The host groups
+     *  the navigation by source; core components are `'core'`. */
+    source: string;
+    /** The targets this component renders into, within the kit's own. The host shows
+     *  a pane + toggle per kit target and disables the rest; a React-only fixture of
+     *  another package's components lists just `react`. */
+    targets: Target[];
+}
+/** A navigation source - the kit's own components or another package's. The host renders one
+ *  collapsible section per source, in `order`, its `label` the heading. */
+export interface ManifestSource {
+    id: string;
+    label: string;
+    order: number;
+    /** The package the source's components import from, per target
+     *  `<moduleBase>/<target>`, or `<moduleBase>` with `{target}` replaced by
+     *  the target when it names one. */
+    moduleBase?: string;
+}
+/** How a consumer imports one of the kit's components. */
+export interface ManifestImport {
+    /** The name the component is exported under. */
+    exportName: string;
+    /** The names it declares that React would otherwise respell (`class`,
+     *  `style`, an attribute React renames, such as `tabindex`), which React
+     *  takes as they are; any other attribute a story gives it is spelled as
+     *  React takes it. Absent when it declares none. */
+    declaredAttributes?: string[];
+    /** The module it is imported from, per target the kit builds. */
+    modules: Partial<Record<Target, string>>;
+    /** The type names its module exports, per target the kit builds, which
+     *  the module a consumer imports it from exports too. Absent where it
+     *  exports none. */
+    types?: Partial<Record<Target, string[]>>;
+}
+export interface Manifest {
+    /** The kit's name (the kit configuration's `name`) - the host's kit selector. */
+    kitName: string;
+    /** The kit's version (its package.json `version`) - the host's version label. */
+    kitVersion?: string;
+    colorOptions: (string | null)[];
+    /** What the kit builds that the host offers a pane for, and for these
+     *  alone: its targets, and `html` when it builds html. */
+    targets: PreviewTarget[];
+    /** The sources, for the navigation's per-source sections (ordered by the host). */
+    sources: ManifestSource[];
+    /** The kit's own code block, when it names one: the framework it mounts
+     *  with. A shell mounts it in place of its own code view. */
+    codeBlock?: {
+        framework: ViewFramework;
+    };
+    components: ManifestComponent[];
+    /** How a consumer imports each of the kit's components, by name: every
+     *  component, those with no story of their own included, so a story's
+     *  source can import what its slot content names. */
+    imports?: Record<string, ManifestImport>;
+    /** The host's own copy (the synthetic empty scenario's label), in the kit's casing. */
+    labels: {
+        emptyScenario: string;
+    };
+    /** Where the host remembers what a person chose (`preview.persistence`).
+     *  Absent means `'url'`. */
+    persistence?: PreviewPersistence;
+    /** The widths a shell offers to lay the story panes out at
+     *  (the configuration module's `previewPaneWidths`). Absent means the preview's own. */
+    paneWidths?: PreviewPaneWidth[];
+    /** The mode the kit builds its Svelte target in (`svelte.mode`), which a
+     *  story's Svelte source follows. Absent means `legacy`. */
+    svelteMode?: 'legacy' | 'runes';
+    /** The entry the host opens on when its address names none
+     *  (`preview.landing`). Absent means the first listed story. */
+    landing?: PreviewLandingConfiguration;
+    /** How React spells the HTML attributes it renames (`tabindex` as
+     *  `tabIndex`), by their HTML names, which a story's React source spells
+     *  a component's attributes with. */
+    reactAttributeNames?: Record<string, string>;
+}
+export declare function buildManifest(models: ResolvedStory[], sources: ManifestSource[], colorTokens?: (string | null | undefined)[], kitName?: string, labels?: PreviewLabels, kitVersion?: string, persistence?: PreviewPersistence, targets?: PreviewTarget[], imports?: Record<string, ManifestImport>, codeBlock?: {
+    framework: ViewFramework;
+}, paneWidths?: PreviewPaneWidth[], svelteMode?: 'legacy' | 'runes', reactAttributeNames?: Readonly<Record<string, string>>, landing?: PreviewLandingConfiguration): Manifest;

package/dist/declarations/src/emit/source.d.ts

@@ -0,0 +1,87 @@
+import type { JsonValue, SlotFill, StoryAround, Target } from '../lib/types.js';
+/**
+ * A two-way prop the story gives, which the printed source binds to state of
+ * its own so the component's changes come back: React holds it in `useState`
+ * and passes the setter as `changeProp`, Vue binds it with `v-model` (bare
+ * with `vueModel`) or `v-model:<prop>`, and Svelte with `bind:<prop>`.
+ */
+export interface SourceBinding {
+    /** The two-way prop. */
+    prop: string;
+    /** The event prop called with each new value. Without one, React prints
+     *  the prop's value alone, as it has no way to hear a change. */
+    changeProp?: string;
+    /** The prop the component's own value starts from when the two-way prop
+     *  is not given, which the source leaves out while it gives the prop. */
+    defaultProp?: string;
+    /** Whether a Vue consumer binds the prop with a bare `v-model`. */
+    vueModel?: boolean;
+    /** The prop's type as the component declares it, which types the state
+     *  where the value alone would read narrower. */
+    declaredType?: string;
+    /** Whether the component takes type parameters, so its prop's type is
+     *  the consumer's to infer rather than to name. */
+    generic?: boolean;
+}
+/** A story resolved for printing: its root component, props and slot content. */
+export interface SourceStory {
+    /** The root component's local name (its export name). */
+    component: string;
+    /** The props to print, already merged and filtered. */
+    props: Record<string, JsonValue>;
+    /** Default-slot content. */
+    children?: SlotFill;
+    /** Named-slot content, keyed by slot name. */
+    named: Record<string, SlotFill>;
+    /** The content beside the component, printed as its siblings: React holds
+     *  them in a fragment, Vue's template and Svelte's markup list them. */
+    around?: StoryAround;
+    /** Import lines' modules per local component name, and the names the
+     *  component declares that React would otherwise respell
+     *  (`declaredAttributes`: `class`, `style`, an attribute React renames),
+     *  which React takes as they are. */
+    imports: Map<string, {
+        module: string;
+        exported: string;
+        declaredAttributes?: string[];
+    }>;
+    /** The root component's two-way props, those given in `props` bound to
+     *  state of the source's own. */
+    bindings?: SourceBinding[];
+    /** The mode the kit builds its Svelte target in, which the state a bound
+     *  prop is held in follows: `$state` in runes mode, a plain `let` in
+     *  legacy mode (the default). */
+    svelteMode?: 'legacy' | 'runes';
+    /** How React spells the HTML attributes it renames (`tabindex` as
+     *  `tabIndex`), by their HTML names. A story spells a component's
+     *  attributes as HTML does; React's source takes `class` as `className`,
+     *  a `style` string as a style object and these by their React names,
+     *  unless the component declares a prop by that name. Without it, only
+     *  `class` and `style` are respelled. */
+    reactAttributeNames?: Readonly<Record<string, string>>;
+    /** The type names the kit's package entries export, each with the module
+     *  it is imported from for this target: a bound prop's state is typed by
+     *  its declared type where it names these and the language's own types
+     *  alone, importing them. */
+    exportedTypes?: ReadonlyMap<string, string>;
+}
+/** The story as a React component module, the attributes it gives a
+ *  component spelled as React takes them (see `reactAttributeNames`). */
+export declare function reactSource(given: SourceStory): string;
+/** The story as a Vue single-file component. */
+export declare function vueSource(given: SourceStory): string;
+/** The story as a Svelte component. */
+export declare function svelteSource(given: SourceStory): string;
+/**
+ * A story's props in the order the component declares them, so the source
+ * prints them alike however they were gathered (the template's defaults, the
+ * story file's, a scenario's); a prop the component does not declare follows,
+ * in the order given.
+ *
+ * @param props - The props to print.
+ * @param declared - The component's prop names, in declaration order.
+ * @returns The same props, reordered.
+ */
+export declare function inDeclarationOrder(props: Record<string, JsonValue>, declared: readonly string[]): Record<string, JsonValue>;
+/** The printer per target. */
+export declare const SOURCE_PRINTERS: Record<Target, (story: SourceStory) => string>;

package/dist/declarations/src/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/declarations/src/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/declarations/src/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;

package/dist/declarations/src/lib/react-spelling.d.ts

@@ -0,0 +1,68 @@
+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 declare function styleDeclarations(css: string): string[];
+/**
+ * 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 declare function styleProperties(css: string): Record<string, string>;
+/**
+ * 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 declare function reactProps<Value>(props: Record<string, Value>, declares: (name: string) => boolean, attributeNames: Readonly<Record<string, string>>): Record<string, Value | Record<string, string> | string>;
+/**
+ * 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 declare function reactFill<Fill extends SlotFill | undefined>(fill: Fill, declares: (component: string, name: string) => boolean, attributeNames: Readonly<Record<string, string>>): 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 declare function declaredAttributes(declared: Iterable<string>, attributeNames: Readonly<Record<string, string>>): string[];

package/dist/declarations/src/lib/scenario-story.d.ts

@@ -0,0 +1,41 @@
+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 declare function scenarioSlotPlan(story: SlotPlan | undefined, scenario: SlotPlan | undefined): SlotPlan | undefined;
+/**
+ * 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 declare function storyOnScenario(model: ResolvedStory, scenario: Scenario | undefined): ResolvedStory;
+/**
+ * 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 declare function scenarioStories(model: ResolvedStory): ResolvedStory[];
+/**
+ * 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 declare function storyRegistryId(model: ResolvedStory): string;

package/dist/declarations/src/lib/slot-fill.d.ts

@@ -0,0 +1,15 @@
+import type { PartFill, SlotFill } from './types.js';
+/** 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 declare function collectSlotComponents(fill: SlotFill | undefined, into: Set<string>, parts?: boolean): void;
+/**
+ * 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 declare function collectParts(fills: Iterable<SlotFill | undefined>): Map<string, PartFill>;