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

package/dist/controller/catalog.d.ts

@@ -0,0 +1,339 @@
+import type { Manifest } from '../emit/manifest.js';
+import type { PreviewBinding, PreviewPaneWidth, PreviewPropType, StoryAround } from '../lib/types.js';
+import type { OptionValue } from '../options.js';
+import { type PreviewScriptedTarget, type PreviewTarget } from '../protocol.js';
+import type { PreviewView, ViewFramework } from '../views.js';
+import { type EditorNode, type EditorState, type SlotPlan } from './editor-tree.js';
+export type { PreviewBinding, PreviewPropType } from '../lib/types.js';
+/** One scenario of a component: a named set of root props, and the option
+ *  values it shows them under. */
+export interface PreviewScenario {
+    id: string;
+    /** The picker label. */
+    label: string;
+    /** What the scenario shows, from the component's story file; markdown allowed.
+     *  Absent when the story file gives none. */
+    description?: string;
+    /** The props the scenario lays over the component's defaults. */
+    props: Record<string, unknown>;
+    /** The option values picking the scenario sets, by option id: the setting
+     *  it shows the component in, such as a color mode or a surface. Absent
+     *  when it sets none. */
+    options?: Record<string, OptionValue>;
+    /** The component's baseline: selected first and shown as the default. */
+    default?: boolean;
+    /** The preview's own Empty scenario: the story's props with no slot content.
+     *  Only a component that accepts slot content has one. */
+    empty?: boolean;
+    /** Generated from one enum value or boolean, listed after the curated ones. */
+    generated?: boolean;
+    /** The slot content the scenario shows, when its story file gives it
+     *  content of its own: its fills over the story's, slot by slot. Absent
+     *  when it shows the story's content. */
+    content?: SlotPlan;
+    /** The id the panes mount the scenario by, when it has content of its
+     *  own. The preview's to use: a shell names a scenario by its `id`. */
+    story?: string;
+}
+/** A component of the kit, with its stories' data. */
+export interface PreviewComponent {
+    /** The story's id, unique across the kit: its title in lower case with
+     *  every run of other characters a hyphen, `components-layout-card` for
+     *  `Components/Layout/Card`. The selection, the address (`?component=`) and
+     *  the testing helpers name the story by it. */
+    id: string;
+    /** The component's export name, as the editor's tree refers to it. */
+    name: string;
+    /** What the component is and when to reach for it, from its template's
+     *  `description`; markdown allowed. Absent when the template gives none. */
+    description?: string;
+    /** The full title, the source label included: `Components/Layout/Card`. */
+    title: string;
+    /** The title without its source label: `Layout/Card`. */
+    shortTitle: string;
+    /** The source the component belongs to (`PreviewSource.id`). */
+    source: string;
+    /** Whether the component has a story of its own. One that is not (a
+     *  compound's part, a shared building block) is offered to the editor,
+     *  not browseable as a story. */
+    standalone: boolean;
+    /** A story left out of what a reader browses - the navigation, an
+     *  editor's component picker, the component count - but generated and
+     *  reachable as any other: by its id, at its address, and through the
+     *  testing helpers. A shell that lists components leaves these out. */
+    unlisted: boolean;
+    /** Each prop's control and declaration. */
+    propTypes: PreviewPropType[];
+    /** The component's events: the props it declares as functions that
+     *  return nothing, such as `onSelect: (value: string) => void`, which it
+     *  calls as things happen. A function prop that returns something, such as
+     *  a `highlight` or a `getPageUrl`, is not one, and is left as given.
+     *  A story's panes record each call (`state.events`). */
+    events: string[];
+    /** The component's two-way props, in prop order. A story that gives one
+     *  takes each value its change prop reports, so a click in any pane
+     *  changes the story's props (`state.props`), as `actions.setProps`
+     *  does. A story that leaves it out lets the component keep its own. */
+    bindings: PreviewBinding[];
+    /** The props the story starts from: the component's declared defaults,
+     *  with the kit's hints and the story file's `defaultProps` over them. */
+    defaultProps: Record<string, unknown>;
+    /** The values in `defaultProps` the preview starts from on its own, from
+     *  the kit's control hints, which neither the component declares nor its
+     *  story file sets. A consumer's source leaves a prop out while it holds this
+     *  value and the scenario does not set it. */
+    previewDefaults: Record<string, unknown>;
+    scenarios: PreviewScenario[];
+    /** The slots the component accepts content into, and those among them
+     *  (`default` for the default slot) whose content must take their scope. */
+    slots: {
+        default: boolean;
+        named: string[];
+        scopeRequired?: string[];
+    };
+    /** The curated slot content a story renders with; the editor seeds its tree from it. */
+    content?: SlotPlan;
+    /** The content the story renders beside the component, as its siblings:
+     *  `before` and `after` it. The editor holds it unchanged, outside its root. */
+    around?: StoryAround;
+    /** Story option defaults, keyed by option id; `false` marks the option unavailable. */
+    options?: Record<string, OptionValue | false>;
+    /** The targets the component renders in, within the catalog's
+     *  `targets`. Html is not listed: where the kit builds html, every
+     *  story has an html pane, which says so when the story has no markup. */
+    targets: PreviewScriptedTarget[];
+}
+/** A source: the kit's own components or another package's, in `order`. */
+export interface PreviewSource {
+    id: string;
+    label: string;
+    order: number;
+    /** The package the source's components are imported from, as
+     *  `<moduleBase>/<target>`, or `<moduleBase>` with `{target}` replaced by
+     *  the target when it names one, when known. */
+    moduleBase?: string;
+}
+/** How a consumer imports one of the kit's components. */
+export interface PreviewImport {
+    /** 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<PreviewScriptedTarget, string>>;
+    /** The type names its module exports, per target, which the module a
+     *  consumer imports it from exports too: a story's source names a prop's
+     *  type by one of them. Absent where it exports none. */
+    types?: Partial<Record<PreviewScriptedTarget, string[]>>;
+}
+/** A custom view a kit registers, as the catalog lists it. */
+export interface PreviewCatalogView {
+    /** The selection id. */
+    id: string;
+    label: string;
+    /** The source whose entries list the view. */
+    source: string;
+    order: number;
+    /** The framework the view mounts with. */
+    framework: ViewFramework;
+}
+/** One entry of the navigation tree: a view, a component story, or a group of entries. */
+export type PreviewNavigationNode = {
+    kind: 'view';
+    id: string;
+    label: string;
+} | {
+    kind: 'component';
+    id: string;
+    label: string;
+    title: string;
+} | {
+    kind: 'group';
+    key: string;
+    label: string;
+    children: PreviewNavigationNode[];
+};
+/**
+ * Everything static about a kit's preview. A controller is created with one
+ * and never changes it; a shell renders its navigation and reads its
+ * components, views and option vocabulary.
+ */
+export interface PreviewCatalog {
+    /** The kit's name. */
+    kitName: string;
+    /** The kit's package version, when known. */
+    kitVersion?: string;
+    /** What the kit builds, in order: its targets, then `html` when it
+     *  builds html. A shell offers a pane and a toggle for these alone. */
+    targets: PreviewTarget[];
+    /** The sources, in order; the first is the kit's own. */
+    sources: PreviewSource[];
+    /** Every component, those with no story of their own and unlisted stories included, with its
+     *  scenarios (the Empty one in place). */
+    components: PreviewComponent[];
+    /** The custom views, in order. */
+    views: PreviewCatalogView[];
+    /** The kit's own code block, when it names one: the framework it mounts
+     *  with. A shell mounts it (`frames.mountCode`) in place of its own code
+     *  view. */
+    codeBlock?: {
+        framework: ViewFramework;
+    };
+    /** The navigation tree: the kit's own source hoisted, other sources grouped. */
+    navigation: PreviewNavigationNode[];
+    /** The plain HTML tags an editor may offer for a wrapper node. */
+    htmlTags: string[];
+    /** The color tokens a color control offers; `null` is the unset choice. */
+    colorTokens: (string | null)[];
+    /** The widths a shell offers to lay the story panes out at, besides
+     *  fitting them to its own space (`state.paneWidth`), narrowest first:
+     *  the kit's `paneWidths`, or `DEFAULT_PANE_WIDTHS`. */
+    paneWidths: PreviewPaneWidth[];
+    /** The entry the preview opens on when its address names none, as the
+     *  kit names it (`landing`); absent, the first listed story. */
+    landing?: PreviewLanding;
+    /** The mode the kit builds its Svelte target in (`svelte.mode` in
+     *  the kit configuration): what a story's Svelte source holds a
+     *  bound prop's state in, `$state` in runes mode and a plain `let` in
+     *  legacy mode. */
+    svelteMode: 'legacy' | 'runes';
+    /** How a consumer imports each of the kit's components, by component name,
+     *  those with no story of their own included: what a story's source
+     *  imports. A component missing here is imported by its own name from the
+     *  first source's `moduleBase`. */
+    imports: Record<string, PreviewImport>;
+    /** How React spells the HTML attributes it renames (`tabindex` as
+     *  `tabIndex`, `for` as `htmlFor`), by their HTML names: a story's React
+     *  source spells the attributes it gives a component with them. */
+    reactAttributeNames: Record<string, string>;
+}
+/** The manifest fields `catalogFromManifest` reads. */
+export type CatalogManifest = Pick<Manifest, 'components'> & Partial<Pick<Manifest, 'kitName' | 'kitVersion' | 'targets' | 'sources' | 'colorOptions' | 'labels' | 'imports' | 'codeBlock' | 'paneWidths' | 'landing' | 'svelteMode' | 'reactAttributeNames'>>;
+/** The entry the preview opens on when its address names none: a custom
+ *  view, or a component's story on one of its scenarios (by id) or, without
+ *  one, on its baseline. */
+export type PreviewLanding = {
+    kind: 'view';
+    id: string;
+} | {
+    kind: 'component';
+    id: string;
+    scenario?: string;
+};
+/** The widths a shell offers to lay the story panes out at when the kit
+ *  names none: a small screen's, a medium one's and a large one's. */
+export declare const DEFAULT_PANE_WIDTHS: readonly PreviewPaneWidth[];
+/**
+ * Build a catalog from the generated manifest and the kit's registered views.
+ *
+ * Components that accept slot content get the Empty scenario ahead of their
+ * own, labeled as the manifest says. Each component's `shortTitle` drops its
+ * source's label prefix. The navigation lists each source's views and its
+ * component tree interleaved by `order`; a source whose views set no
+ * component tree lists its components under `Components`, first among the
+ * entries of order 0. Components that are not standalone and unlisted stories stay in
+ * `components` but out of the navigation. The kit's targets are the manifest's,
+ * the three targets when it names none, with `html` only where it names
+ * it, and each component's targets are narrowed to the targets among them.
+ * The pane widths are the manifest's, narrowest first, or
+ * `DEFAULT_PANE_WIDTHS` when it names none, the Svelte mode the
+ * manifest's, `legacy` when it names none, and the landing entry the
+ * manifest's.
+ *
+ * @param manifest - The generated manifest.
+ * @param views - The kit's registered views (rendered views and component-tree markers).
+ * @returns The catalog.
+ */
+export declare function catalogFromManifest(manifest: CatalogManifest, views?: PreviewView[]): PreviewCatalog;
+/** One choice of a scenario picker. */
+export interface ScenarioChoice {
+    /** The scenario id; `''` is the anonymous default. */
+    value: string;
+    label: string;
+}
+/**
+ * The scenario picker's choices for a component: its baseline first, labeled
+ * as the default, then the rest. The Empty scenario renders through a
+ * regeneration, so it is left out where the preview cannot regenerate, as in
+ * a static build. Empty when the component offers no choice beyond its
+ * default, so a shell can leave the picker out.
+ *
+ * @param component - The component.
+ * @param capabilities - What the preview can do: the controller's
+ *   `capabilities`.
+ * @returns The choices, or an empty list.
+ * @example
+ * ```ts
+ * const choices = scenarioChoices(component, controller.capabilities);
+ * ```
+ */
+export declare function scenarioChoices(component: PreviewComponent | undefined, capabilities: {
+    regeneration: boolean;
+}): ScenarioChoice[];
+/** A story to mount in a detached pane: a component, a scenario and props. */
+export interface PreviewStoryReference {
+    /** The component's story id (`PreviewComponent.id`). */
+    component: string;
+    /** The scenario's id; `''` is the anonymous default. Omitted, the story's
+     *  starting scenario, as selecting the story picks it. */
+    scenario?: string;
+    /** Props laid over the scenario's. */
+    props?: Record<string, unknown>;
+}
+/**
+ * The key a detached story pane's readiness is reported under in the
+ * state's `storyFrames`: the target, the component, then the scenario and
+ * the props as given. Two panes of the same story, scenario and props share
+ * a key, and it reads `ready` once either has loaded.
+ *
+ * @param target - The target the pane renders in.
+ * @param story - The story, as passed to `frames.mountStory`.
+ * @returns The key, such as `react:components-button:ghost`.
+ * @example
+ * ```ts
+ * const ready = state.storyFrames[storyFrameKey('vue', { component: id, scenario: 'ghost' })] === 'ready';
+ * ```
+ */
+export declare function storyFrameKey(target: PreviewScriptedTarget, story: PreviewStoryReference): string;
+/**
+ * The scenario a component starts on: its default-flagged one, else `''`,
+ * the anonymous default.
+ *
+ * @param component - The component.
+ * @returns The scenario id.
+ */
+export declare function defaultScenarioId(component: PreviewComponent | undefined): string;
+/**
+ * The slots a node of the editor's tree holds content in: a component's
+ * default slot (when it has one) and then its named slots, as the catalog
+ * records them; an HTML tag's default slot; nothing for text or an opaque
+ * fill. The tree itself counts as its root component's node.
+ *
+ * @param catalog - The catalog the node's component is looked up in.
+ * @param node - A node of the tree, or the tree itself for its root.
+ * @returns The slot names, the default slot first.
+ * @example
+ * ```ts
+ * const tree = controller.getState().editor.tree!;
+ * for (const slot of nodeSlots(controller.catalog, tree)) render(slot, tree.slots[slot] ?? []);
+ * ```
+ */
+export declare function nodeSlots(catalog: Pick<PreviewCatalog, 'components'>, node: EditorNode | EditorState): string[];
+/**
+ * The slots the editor can add plain content to in a node of its tree: the
+ * node's slots ({@link nodeSlots}) without those whose content must take
+ * their scope, which take only a scoped fill the editor cannot author. Such a
+ * slot still holds and shows the fill a story gives it.
+ *
+ * @param catalog - The catalog the node's component is looked up in.
+ * @param node - A node of the tree, or the tree itself for its root.
+ * @returns The slot names, the default slot first.
+ * @example
+ * ```ts
+ * const targets = nodeAddSlots(controller.catalog, controller.getState().editor.tree!);
+ * ```
+ */
+export declare function nodeAddSlots(catalog: Pick<PreviewCatalog, 'components'>, node: EditorNode | EditorState): string[];