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

package/dist/controller/catalog.js

@@ -0,0 +1,367 @@
+// The catalog a preview controller is created with: everything static about
+// the kit being previewed, in the shape a shell reads (a navigation tree, short
+// titles, the Empty scenario in place). The preview's bootstrap builds it from
+// the generated manifest with `catalogFromManifest`; another producer can build
+// one by hand. Browser-safe: no node imports, type-only imports.
+import { EMPTY_SCENARIO_ID } from '../lib/naming.js';
+import { PREVIEW_SCRIPTED_TARGETS, PREVIEW_TARGETS, } from '../protocol.js';
+import { DEFAULT_SLOT, HTML_TAGS, isContainer, } from './editor-tree.js';
+/** 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 const DEFAULT_PANE_WIDTHS = [
+    { label: 'small', width: 375 },
+    { label: 'medium', width: 768 },
+    { label: 'large', width: 1280 },
+];
+const DEFAULT_SOURCES = [
+    { id: 'core', label: 'Components', order: 0 },
+];
+/**
+ * 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 function catalogFromManifest(manifest, views = []) {
+    const sources = (manifest.sources?.length ? manifest.sources : DEFAULT_SOURCES)
+        .slice()
+        .sort((a, b) => a.order - b.order);
+    const rootSourceId = sources[0].id;
+    const targets = PREVIEW_TARGETS.filter((target) => manifest.targets?.includes(target) ?? target !== 'html');
+    const emptyScenario = {
+        id: EMPTY_SCENARIO_ID,
+        label: manifest.labels?.emptyScenario ?? 'Empty',
+        props: {},
+        empty: true,
+    };
+    const components = manifest.components.map((component) => {
+        const source = component.source ?? rootSourceId;
+        const hasContent = component.slots.default || component.slots.named.length > 0;
+        return {
+            id: component.id,
+            name: component.name,
+            ...(component.description !== undefined
+                ? { description: component.description }
+                : {}),
+            title: component.title,
+            shortTitle: stripSourcePrefix(component.title, sources.find((candidate) => candidate.id === source)),
+            source,
+            standalone: component.standalone !== false,
+            unlisted: component.unlisted === true,
+            propTypes: component.propTypes,
+            events: component.events ?? [],
+            bindings: component.bindings ?? [],
+            defaultProps: component.defaultProps,
+            previewDefaults: component.previewDefaults ?? {},
+            scenarios: hasContent
+                ? [emptyScenario, ...component.scenarios]
+                : [...component.scenarios],
+            slots: component.slots,
+            ...(component.content ? { content: component.content } : {}),
+            ...(component.around ? { around: component.around } : {}),
+            ...(component.options
+                ? {
+                    options: component.options,
+                }
+                : {}),
+            targets: (component.targets ?? PREVIEW_SCRIPTED_TARGETS).filter((target) => targets.includes(target)),
+        };
+    });
+    const catalogViews = views
+        .filter((view) => !view.componentTree)
+        .map((view) => ({
+        id: view.id,
+        label: view.label,
+        source: view.source ?? rootSourceId,
+        order: view.order ?? 0,
+        framework: view.framework ?? 'dom',
+    }))
+        .sort((a, b) => a.order - b.order);
+    return {
+        kitName: manifest.kitName ?? 'kit',
+        ...(manifest.kitVersion ? { kitVersion: manifest.kitVersion } : {}),
+        targets,
+        sources,
+        components,
+        views: catalogViews,
+        ...(manifest.codeBlock ? { codeBlock: manifest.codeBlock } : {}),
+        navigation: buildNavigation(sources, components, views),
+        htmlTags: [...HTML_TAGS],
+        colorTokens: (manifest.colorOptions ?? []).map((token) => token ?? null),
+        paneWidths: (manifest.paneWidths ?? DEFAULT_PANE_WIDTHS)
+            .map((paneWidth) => ({ ...paneWidth }))
+            .sort((a, b) => a.width - b.width),
+        ...(manifest.landing
+            ? {
+                landing: 'view' in manifest.landing
+                    ? { kind: 'view', id: manifest.landing.view }
+                    : {
+                        kind: 'component',
+                        id: manifest.landing.component,
+                        ...(manifest.landing.scenario !== undefined
+                            ? { scenario: manifest.landing.scenario }
+                            : {}),
+                    },
+            }
+            : {}),
+        imports: manifest.imports ?? {},
+        svelteMode: manifest.svelteMode ?? 'legacy',
+        reactAttributeNames: manifest.reactAttributeNames ?? {},
+    };
+}
+function stripSourcePrefix(title, source) {
+    const prefix = source ? `${source.label}/` : '';
+    return prefix && title.startsWith(prefix)
+        ? title.slice(prefix.length)
+        : title;
+}
+/** A source's stories as a category tree: titles (minus the source's label)
+ *  split on `/` into folders and leaves, folders first, each level alphabetical. */
+function buildTitleTree(components, rootLabel) {
+    const root = { label: rootLabel, children: [] };
+    const prefix = `${rootLabel}/`;
+    for (const component of components) {
+        const rest = component.title.startsWith(prefix)
+            ? component.title.slice(prefix.length)
+            : component.title;
+        const segments = rest.split('/');
+        let node = root;
+        segments.forEach((segment, index) => {
+            let child = node.children.find((candidate) => candidate.label === segment);
+            if (!child) {
+                child = { label: segment, children: [] };
+                node.children.push(child);
+            }
+            if (index === segments.length - 1)
+                child.component = component;
+            node = child;
+        });
+    }
+    const sort = (treeNode) => {
+        treeNode.children.sort((a, b) => {
+            const aFolder = a.children.length > 0;
+            const bFolder = b.children.length > 0;
+            if (aFolder !== bFolder)
+                return aFolder ? -1 : 1;
+            return a.label.localeCompare(b.label);
+        });
+        treeNode.children.forEach(sort);
+    };
+    sort(root);
+    return root;
+}
+function titleTreeToNavigation(node, parentKey) {
+    const key = `${parentKey}/${node.label}`;
+    if (node.children.length > 0) {
+        return {
+            kind: 'group',
+            key,
+            label: node.label,
+            children: node.children.map((child) => titleTreeToNavigation(child, key)),
+        };
+    }
+    const component = node.component;
+    return {
+        kind: 'component',
+        id: component.id,
+        label: node.label,
+        title: component.title,
+    };
+}
+/** A source's component tree as one group, or `null` when it has no stories. */
+function componentsEntry(source, components, entryLabel) {
+    const stories = components.filter((component) => component.standalone &&
+        !component.unlisted &&
+        component.source === source.id);
+    if (stories.length === 0)
+        return null;
+    const root = buildTitleTree(stories, source.label);
+    const key = `components:${source.id}`;
+    return {
+        kind: 'group',
+        key,
+        label: entryLabel,
+        children: root.children.map((child) => titleTreeToNavigation(child, key)),
+    };
+}
+/** The label of a source's component tree where no view sets one. */
+const COMPONENT_TREE_LABEL = 'Components';
+/** A source's entries: its views and its component tree, by `order`. A source
+ *  with stories whose views set no component tree gets one, labeled
+ *  `Components`, first among the entries of its order. */
+function sourceEntries(source, rootSourceId, components, views) {
+    const scoped = views.filter((view) => (view.source ?? rootSourceId) === source.id);
+    const entries = scoped.map((view) => ({
+        order: view.order ?? 0,
+        entry: view.componentTree
+            ? componentsEntry(source, components, view.label)
+            : {
+                kind: 'view',
+                id: view.id,
+                label: view.label,
+            },
+    }));
+    if (!scoped.some((view) => view.componentTree))
+        entries.unshift({
+            order: 0,
+            entry: componentsEntry(source, components, COMPONENT_TREE_LABEL),
+        });
+    // A stable sort: the default tree stays ahead of the views of its order.
+    return entries
+        .sort((a, b) => a.order - b.order)
+        .map(({ entry }) => entry)
+        .filter((entry) => entry !== null);
+}
+function buildNavigation(sources, components, views) {
+    const rootSourceId = sources[0].id;
+    const nodes = [];
+    for (const source of sources) {
+        const entries = sourceEntries(source, rootSourceId, components, views);
+        if (source.id === rootSourceId)
+            nodes.push(...entries);
+        else if (entries.length > 0)
+            nodes.push({
+                kind: 'group',
+                key: `source:${source.id}`,
+                label: source.label,
+                children: entries,
+            });
+    }
+    return nodes;
+}
+/**
+ * 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 function scenarioChoices(component, capabilities) {
+    if (!component)
+        return [];
+    const baseline = component.scenarios.find((scenario) => scenario.default);
+    const others = component.scenarios.filter((scenario) => !scenario.default && (capabilities.regeneration || !scenario.empty));
+    if (others.length === 0)
+        return [];
+    return [
+        baseline
+            ? { value: baseline.id, label: `${baseline.label} (default)` }
+            : { value: '', label: '(default)' },
+        ...others.map((scenario) => ({
+            value: scenario.id,
+            label: scenario.label,
+        })),
+    ];
+}
+/**
+ * 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 function storyFrameKey(target, story) {
+    return [
+        target,
+        story.component,
+        ...(story.scenario !== undefined ? [story.scenario] : []),
+        ...(story.props !== undefined ? [JSON.stringify(story.props)] : []),
+    ].join(':');
+}
+/**
+ * The scenario a component starts on: its default-flagged one, else `''`,
+ * the anonymous default.
+ *
+ * @param component - The component.
+ * @returns The scenario id.
+ */
+export function defaultScenarioId(component) {
+    return component?.scenarios.find((scenario) => scenario.default)?.id ?? '';
+}
+/**
+ * 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 function nodeSlots(catalog, node) {
+    let name;
+    if ('root' in node)
+        name = node.root;
+    else if (!isContainer(node))
+        return [];
+    else if (node.kind === 'html')
+        return [DEFAULT_SLOT];
+    else
+        name = node.component;
+    const slots = catalog.components.find((component) => component.name === name)?.slots;
+    if (!slots)
+        return [];
+    return [...(slots.default ? [DEFAULT_SLOT] : []), ...slots.named];
+}
+/**
+ * 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 function nodeAddSlots(catalog, node) {
+    const name = 'root' in node
+        ? node.root
+        : isContainer(node) && node.kind !== 'html'
+            ? node.component
+            : undefined;
+    const scopeRequired = name === undefined
+        ? []
+        : (catalog.components.find((component) => component.name === name)?.slots
+            .scopeRequired ?? []);
+    return nodeSlots(catalog, node).filter((slot) => !scopeRequired.includes(slot));
+}