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

package/dist/controller/source.js

@@ -0,0 +1,236 @@
+// A story's source printed in the browser from the catalog: the code a
+// consumer writes per target, importing from the kit's package entries,
+// with the props a person sets and the slot content the story or the editor's
+// tree holds. The printers are pure, so the source follows every change
+// without a round trip; the html source, which renders the kit's templates,
+// is the server's (html-source.ts). Browser-safe.
+import { inDeclarationOrder, SOURCE_PRINTERS, } from '../emit/source.js';
+import { collectSlotComponents } from '../lib/slot-fill.js';
+import { moduleOfSource } from '../lib/module-of-source.js';
+import { defaultScenarioId, } from './catalog.js';
+import { cleanRecord, toPayload } from './editor-tree.js';
+function withoutUndefined(props) {
+    const out = {};
+    for (const [name, value] of Object.entries(props))
+        if (value !== undefined)
+            out[name] = value;
+    return out;
+}
+/**
+ * Whether a story's default-slot text is the component's name the preview
+ * shows in a default slot the story leaves unfilled, which a consumer never
+ * writes: the preview's own starting text, while the scenario does not give
+ * `children` itself.
+ */
+export function isPlaceholder(component, text, input) {
+    return (component.previewDefaults.children === text &&
+        !('children' in (input.scenario?.props ?? {})));
+}
+/**
+ * Resolve what a story's source prints. Without a tree, the slot content is
+ * the story's own and a string `children` is its default-slot text; with the
+ * editor's tree, the root's props and content are the tree's. A prop is left
+ * out while it holds the component's declared default, or the preview's own
+ * starting value that the scenario does not set, as is the component's name
+ * the preview shows in a default slot the story leaves unfilled.
+ */
+export function resolveSourceStory(component, input) {
+    let props;
+    let children;
+    let named;
+    if (input.tree) {
+        const payload = toPayload(input.tree);
+        const { children: _children, ...rootProps } = input.props;
+        props = cleanRecord(rootProps);
+        children = payload.slots?.default;
+        named = payload.slots?.named ?? {};
+    }
+    else {
+        const { children: text, ...rest } = input.props;
+        props = withoutUndefined(rest);
+        // A scenario with content of its own shows that in place of the story's.
+        const content = input.scenario?.content ?? component.content;
+        children =
+            content?.default ??
+                (typeof text === 'string' && !isPlaceholder(component, text, input)
+                    ? { kind: 'text', value: text }
+                    : undefined);
+        named = content?.named ?? {};
+    }
+    const declared = new Map(component.propTypes.map((propType) => [propType.name, propType]));
+    const scenarioProps = input.scenario?.props ?? {};
+    for (const [name, value] of Object.entries(props)) {
+        const declaredDefault = declared.get(name)?.declaredDefault;
+        const previewDefault = component.previewDefaults[name];
+        if ((declaredDefault !== undefined &&
+            JSON.stringify(declaredDefault) === JSON.stringify(value)) ||
+            (previewDefault !== undefined &&
+                !(name in scenarioProps) &&
+                JSON.stringify(previewDefault) === JSON.stringify(value)))
+            delete props[name];
+    }
+    props = inDeclarationOrder(props, component.propTypes.map((propType) => propType.name));
+    // A two-way prop the story gives is controlled: its source binds it.
+    const bindings = (component.bindings ?? [])
+        .filter((binding) => binding.prop in props)
+        .map((binding) => {
+        const declaredType = declared.get(binding.prop)?.declaredType;
+        return {
+            prop: binding.prop,
+            ...(binding.changeProp !== undefined
+                ? { changeProp: binding.changeProp }
+                : {}),
+            ...(binding.defaultProp !== undefined
+                ? { defaultProp: binding.defaultProp }
+                : {}),
+            ...(binding.vueModel ? { vueModel: true } : {}),
+            ...(binding.generic ? { generic: true } : {}),
+            ...(declaredType !== undefined ? { declaredType } : {}),
+        };
+    });
+    // The content beside the component is the story's, with or without the
+    // editor's tree: no edit reaches it.
+    const around = component.around;
+    return {
+        component: component.name,
+        props,
+        ...(children ? { children } : {}),
+        named,
+        ...(around ? { around } : {}),
+        ...(bindings.length > 0 ? { bindings } : {}),
+    };
+}
+/** The import of each component a story names, for one target: its root,
+ *  then what its slot content holds, in order. */
+function importsFor(catalog, story, target) {
+    const names = new Set();
+    collectSlotComponents(story.children, names);
+    for (const fill of [
+        ...Object.values(story.named),
+        story.around?.before,
+        story.around?.after,
+    ])
+        collectSlotComponents(fill, names);
+    const base = catalog.sources[0]?.moduleBase ?? catalog.kitName;
+    const imports = new Map();
+    for (const name of [story.component, ...names]) {
+        if (imports.has(name))
+            continue;
+        const known = catalog.imports[name];
+        imports.set(name, {
+            module: known?.modules[target] ?? moduleOfSource(base, target),
+            exported: known?.exportName ?? name,
+            ...(known?.declaredAttributes
+                ? { declaredAttributes: known.declaredAttributes }
+                : {}),
+        });
+    }
+    return imports;
+}
+/** The type names the kit's components' modules export, for one target,
+ *  each with the module a consumer imports it from: the story's own
+ *  component's, then the first other component's to export it. A name a
+ *  component is imported under is a value, never a type here. */
+function exportedTypesFor(catalog, target, component) {
+    const base = catalog.sources[0]?.moduleBase ?? catalog.kitName;
+    // A component's own name, or the name it is exported under, is a value.
+    const values = new Set(Object.entries(catalog.imports).flatMap(([name, known]) => [
+        name,
+        known.exportName,
+    ]));
+    const types = new Map();
+    // The story's own component first, so its type wins a name another
+    // component's module exports too.
+    const own = catalog.imports[component];
+    const entries = [
+        ...(own ? [own] : []),
+        ...Object.entries(catalog.imports)
+            .filter(([name]) => name !== component)
+            .map(([, known]) => known),
+    ];
+    for (const known of entries)
+        for (const type of known.types?.[target] ?? [])
+            if (!types.has(type) && !values.has(type))
+                types.set(type, known.modules[target] ?? moduleOfSource(base, target));
+    return types;
+}
+/**
+ * Print a resolved story in each of `targets`: a two-way prop it gives
+ * bound to state of the source's own, in the catalog's Svelte mode.
+ *
+ * @param catalog - The catalog the components' imports are read from.
+ * @param story - The story, resolved.
+ * @param targets - The targets to print.
+ * @returns The source per target.
+ */
+export function printSourceStory(catalog, story, targets) {
+    const sources = {};
+    for (const target of targets) {
+        sources[target] = SOURCE_PRINTERS[target]({
+            component: story.component,
+            props: story.props,
+            ...(story.children ? { children: story.children } : {}),
+            named: story.named,
+            ...(story.around ? { around: story.around } : {}),
+            imports: importsFor(catalog, story, target),
+            ...(story.bindings ? { bindings: story.bindings } : {}),
+            ...(catalog.svelteMode ? { svelteMode: catalog.svelteMode } : {}),
+            ...(catalog.reactAttributeNames
+                ? { reactAttributeNames: catalog.reactAttributeNames }
+                : {}),
+            exportedTypes: exportedTypesFor(catalog, target, story.component),
+        });
+    }
+    return sources;
+}
+/**
+ * Print any story of the catalog as the source a consumer writes, per
+ * target the component renders in: the component with the props of the
+ * scenario over its defaults and `props` over those, its slot content, and
+ * imports from the kit's package entry for each target. A prop is left
+ * out while it holds the component's declared default. It takes the story
+ * reference `frames.mountStory` takes, so a shell can show the code beside a
+ * detached pane. The html source is the preview's own (`state.code.html`)
+ * and is not printed here.
+ *
+ * @param catalog - The controller's catalog.
+ * @param story - The story: a component's id, a scenario (omitted, the one
+ *   the story starts on; `''`, the anonymous default) and props over its own.
+ * @returns The source per target, in the component's targets.
+ * @throws When the component or the scenario is unknown.
+ * @example
+ * ```ts
+ * const { react } = printStorySource(controller.catalog, { component: 'components-button', scenario: 'ghost' });
+ * ```
+ */
+export function printStorySource(catalog, story) {
+    const component = catalog.components.find((candidate) => candidate.id === story.component);
+    if (!component)
+        throw new Error(`The catalog has no component "${story.component}" to print.`);
+    const scenarioId = story.scenario ?? defaultScenarioId(component);
+    const scenario = component.scenarios.find((candidate) => candidate.id === scenarioId);
+    if (scenarioId !== '' && !scenario)
+        throw new Error(`The story "${component.id}" has no scenario "${scenarioId}".`);
+    const seeded = { ...component.defaultProps, ...(scenario?.props ?? {}) };
+    // The Empty scenario is the story's props with no slot content.
+    const props = {
+        ...(scenario?.empty ? withoutChildren(seeded) : seeded),
+        ...withoutUndefined(story.props ?? {}),
+    };
+    const resolved = scenario?.empty
+        ? resolveSourceStory(component, {
+            props,
+            scenario,
+            tree: {
+                root: component.name,
+                props: withoutChildren(props),
+                slots: {},
+            },
+        })
+        : resolveSourceStory(component, { props, scenario });
+    return printSourceStory(catalog, resolved, component.targets);
+}
+function withoutChildren(props) {
+    const { children: _children, ...rest } = props;
+    return rest;
+}

package/dist/controller/store.d.ts

@@ -0,0 +1,27 @@
+import type { PreviewController, PreviewState } from './create-preview-controller.js';
+/** A readable store: `subscribe` calls `listener` with the current value
+ *  immediately, then with each new value, until the returned function is called. */
+export interface PreviewStore<Value> {
+    subscribe(listener: (value: Value) => void): () => void;
+}
+/**
+ * A store of the controller's state, or of a slice of it. Each subscriber is
+ * called with the current slice when it subscribes, and again only when the
+ * slice changes by identity, so `selector` returns a field of the state (or a
+ * primitive derived from it) rather than a fresh object or array.
+ *
+ * @param controller - The controller to read.
+ * @param selector - Picks the slice; the whole state when omitted.
+ * @returns The store.
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { previewStore } from '@scaffold-ui-kit/preview/shell';
+ *   const preview = previewStore(controller);
+ *   const scenario = previewStore(controller, (state) => state.scenario);
+ * </script>
+ *
+ * <p>{$preview.selection.id}: {$scenario}</p>
+ * ```
+ */
+export declare function previewStore<Selected = PreviewState>(controller: Pick<PreviewController, 'getState' | 'subscribe'>, selector?: (state: PreviewState) => Selected): PreviewStore<Selected>;

package/dist/controller/store.js

@@ -0,0 +1,40 @@
+// A store view of the preview controller: an object with one `subscribe`
+// method that calls its listener with the current value at once and again
+// whenever the value changes. That is the Svelte store contract, so a Svelte
+// shell reads it with `$store` or `fromStore`, and it suits any other
+// store-shaped consumer. Framework-neutral and browser-safe.
+/**
+ * A store of the controller's state, or of a slice of it. Each subscriber is
+ * called with the current slice when it subscribes, and again only when the
+ * slice changes by identity, so `selector` returns a field of the state (or a
+ * primitive derived from it) rather than a fresh object or array.
+ *
+ * @param controller - The controller to read.
+ * @param selector - Picks the slice; the whole state when omitted.
+ * @returns The store.
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { previewStore } from '@scaffold-ui-kit/preview/shell';
+ *   const preview = previewStore(controller);
+ *   const scenario = previewStore(controller, (state) => state.scenario);
+ * </script>
+ *
+ * <p>{$preview.selection.id}: {$scenario}</p>
+ * ```
+ */
+export function previewStore(controller, selector = (state) => state) {
+    return {
+        subscribe(listener) {
+            let current = selector(controller.getState());
+            listener(current);
+            return controller.subscribe((state) => {
+                const next = selector(state);
+                if (Object.is(next, current))
+                    return;
+                current = next;
+                listener(next);
+            });
+        },
+    };
+}

package/dist/declarations/application/shells/charcell/components/Application/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function Application(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Bar/index.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import './index.css';
+export declare function Bar({ variant, joined, unruled, flush, lead, end, children, }: {
+    variant?: 'header' | 'status';
+    joined?: boolean;
+    unruled?: boolean;
+    flush?: boolean;
+    lead?: ReactNode;
+    end?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/CodePane/index.d.ts

@@ -0,0 +1,5 @@
+import type { PreviewTarget } from '../../../../../src/shell';
+import './index.css';
+export declare function CodePane({ target }: {
+    target: PreviewTarget;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/ComponentStage/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function ComponentStage(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Control/index.d.ts

@@ -0,0 +1,9 @@
+import type { PreviewPropType } from '../../../../../src/shell';
+import './index.css';
+type Json = unknown;
+export declare function Control(props: {
+    propType: PreviewPropType;
+    value: Json;
+    onChange: (nextValue: Json) => void;
+}): import("react").JSX.Element;
+export {};

package/dist/declarations/application/shells/charcell/components/CopyLink/index.d.ts

@@ -0,0 +1 @@
+export declare function CopyLink(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Description/index.d.ts

@@ -0,0 +1,5 @@
+import './index.css';
+export declare function Description({ text, label }: {
+    text?: string;
+    label: string;
+}): import("react").JSX.Element | null;

package/dist/declarations/application/shells/charcell/components/EditorAddDialog/index.d.ts

@@ -0,0 +1,6 @@
+import { type EditorNode } from '../../../../../src/shell';
+import './index.css';
+export declare function EditorAddDialog(props: {
+    slots: string[];
+    onAdd: (slot: string, child: EditorNode) => void;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/EditorPanel/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function EditorPanel(): import("react").JSX.Element | null;

package/dist/declarations/application/shells/charcell/components/EventsRow/index.d.ts

@@ -0,0 +1,4 @@
+import './index.css';
+export declare function EventsRow(): import("react").JSX.Element;
+/** The events row's `clear`, at the end of its heading row. */
+export declare function EventsClear(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/HeadingRow/index.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+import './index.css';
+export declare function HeadingRow({ heading, end }: {
+    heading: string;
+    end?: ReactNode;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Hint/index.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import './index.css';
+export declare function Hint({ text, markdown, triggerProps, around, focusable, label, children, }: {
+    text?: string;
+    markdown?: boolean;
+    triggerProps?: Record<string, unknown>;
+    around?: boolean;
+    focusable?: boolean;
+    label?: string;
+    children: (triggerProps: Record<string, unknown>) => ReactNode;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/HtmlWarnings/index.d.ts

@@ -0,0 +1,5 @@
+export declare function HtmlWarnings({ warnings, className, attributes, }: {
+    warnings: readonly string[];
+    className?: string;
+    attributes?: Record<string, string>;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/KeyHints/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function KeyHints(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/KitCodeBlock/index.d.ts

@@ -0,0 +1,5 @@
+import type { PreviewTarget } from '../../../../../src/shell';
+import './index.css';
+export declare function KitCodeBlock({ target }: {
+    target: PreviewTarget;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Markdown/index.d.ts

@@ -0,0 +1,3 @@
+export declare function Markdown({ text }: {
+    text: string;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Navigation/index.d.ts

@@ -0,0 +1,8 @@
+import { type Dispatch, type SetStateAction } from 'react';
+import './index.css';
+export declare function Navigation({ collapsed, onCollapsedChange, }: {
+    /** The keys of the collapsed groups. */
+    collapsed: ReadonlySet<string>;
+    /** Sets the keys as a group opens or collapses, as a state setter does. */
+    onCollapsedChange: Dispatch<SetStateAction<ReadonlySet<string>>>;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/NavigationSplit/index.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+import './index.css';
+export declare function NavigationSplit({ navigation, main, shown }: {
+    navigation: ReactNode;
+    main: ReactNode;
+    shown: boolean;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/OptionControls/index.d.ts

@@ -0,0 +1,7 @@
+import type { CharcellRegion } from '../../configuration';
+export declare function OptionControls({ placement }: {
+    placement: CharcellRegion;
+}): import("react").JSX.Element;
+/** Whether any option the current story offers is placed in a region - so a
+ *  bar can leave out an empty zone. */
+export declare function useHasOptionControls(placement: CharcellRegion): boolean;

package/dist/declarations/application/shells/charcell/components/PaneStatus/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function PaneStatus(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/PaneWidth/index.d.ts

@@ -0,0 +1,4 @@
+/** Whether there is a width to pick: the catalog offers some, or one is
+ *  chosen. */
+export declare function usePaneWidthShown(): boolean;
+export declare function PaneWidth(): import("react").JSX.Element | null;

package/dist/declarations/application/shells/charcell/components/PreviewGrid/index.d.ts

@@ -0,0 +1,7 @@
+import type { PreviewTarget } from '../../../../../src/shell';
+import './index.css';
+export declare function PreviewGrid({ targets, output, code }: {
+    targets: PreviewTarget[];
+    output: boolean;
+    code: boolean;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/PreviewPane/index.d.ts

@@ -0,0 +1,9 @@
+import { type PreviewTarget } from '../../../../../src/shell';
+import './index.css';
+export declare function PreviewPane(props: {
+    title: string;
+} & ({
+    target: PreviewTarget;
+} | {
+    viewId: string;
+})): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/PromptBar/index.d.ts

@@ -0,0 +1 @@
+export declare function PromptBar(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/ScenarioRow/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function ScenarioRow(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/Select/index.d.ts

@@ -0,0 +1,16 @@
+export interface SelectOption {
+    label: string;
+    value: string;
+}
+export declare function Select(props: {
+    /** Omit for a bare trigger (no inline label), e.g. the editor's node pickers. */
+    label?: string;
+    /** A bare trigger's id, for a label of the caller's own to point at. */
+    id?: string;
+    value: string;
+    options: SelectOption[];
+    /** Omit for a display-only select. */
+    onChange?: (value: string) => void;
+    /** Stamped on the trigger for tests to open the widget. */
+    testId?: string;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/SlotOutlet/index.d.ts

@@ -0,0 +1,5 @@
+import type { CharcellSlotName } from '../../configuration';
+import './index.css';
+export declare function SlotOutlet({ name }: {
+    name: CharcellSlotName;
+}): import("react").JSX.Element | null;

package/dist/declarations/application/shells/charcell/components/StageBar/index.d.ts

@@ -0,0 +1,2 @@
+import './index.css';
+export declare function StageBar(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/StageSplit/index.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import './index.css';
+/** One of the stage's rows, as the split holds it. */
+export interface StageRow {
+    id: 'scenario' | 'grid' | 'events';
+    content: ReactNode;
+    shown: boolean;
+    /** The row's heading and controls, on the row above it; the scenario row
+     *  heads itself. */
+    heading?: ReactNode;
+    controls?: ReactNode;
+    /** The handle above it, named for a reader. */
+    label?: string;
+}
+export declare function StageSplit({ rows }: {
+    rows: StageRow[];
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/StatusBar/index.d.ts

@@ -0,0 +1 @@
+export declare function StatusBar(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/ViewControls/index.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+import type { CharcellView } from '../../configuration';
+import './index.css';
+export declare function ViewControls({ view, options: ownOptions, children, }: {
+    view: CharcellView;
+    /** The view's own options, shown after the kit's; omit when it has none. */
+    options?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/ViewHeading/index.d.ts

@@ -0,0 +1,4 @@
+import './index.css';
+export declare function ViewHeading({ children }: {
+    children: string;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/ViewStage/index.d.ts

@@ -0,0 +1,4 @@
+import './index.css';
+export declare function ViewStage({ viewId }: {
+    viewId: string;
+}): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/components/WrapToggle/index.d.ts

@@ -0,0 +1 @@
+export declare function WrapToggle(): import("react").JSX.Element;

package/dist/declarations/application/shells/charcell/configuration.d.ts

@@ -0,0 +1,31 @@
+import type { PreviewController } from '../../../src/shell';
+/** One of the stage's views, each headed by a row whose end holds its
+ *  options, its slot and its own control. */
+export type CharcellView = 'scenario' | 'output' | 'code' | 'events';
+/** A region of the charcell shell an option group can be placed in: the top
+ *  bar, the end of the stage bar (the bar with the component select), the
+ *  end of a view's heading row, and the status bar. */
+export type CharcellRegion = 'top-bar' | 'stage-bar' | CharcellView | 'status-bar';
+/** A named slot of the charcell shell: the end of the top bar, the end of the
+ *  stage bar, the end of a view's heading row, and the status bar. */
+export type CharcellSlotName = 'top-bar-end' | 'stage-bar-end' | 'scenario-end' | 'output-end' | 'code-end' | 'events-end' | 'status-bar';
+/**
+ * Content for a slot: mounts into `element` when the shell renders the slot
+ * and may return a function that unmounts it. Written in any framework or in
+ * plain DOM; `reactFill` wraps a React render function.
+ */
+export type CharcellSlotFill = (element: HTMLElement, controller: PreviewController) => (() => void) | void;
+/** What `charcellShell` takes. */
+export interface CharcellShellConfiguration {
+    /** Content for the shell's named slots. */
+    slots?: Partial<Record<CharcellSlotName, CharcellSlotFill>>;
+    /** Where each option group goes, by group name, over the shell's own
+     *  placement: a story option, and a global option of the `context` group
+     *  (or of none), in the output view's region; a global option of the `kit`
+     *  group in the top bar, and of any other group in the status bar. */
+    groups?: Record<string, CharcellRegion>;
+    /** Which views hold their options in a popover at the end of
+     *  their heading row, rather than in the row itself: the output's by
+     *  default. */
+    popovers?: Partial<Record<CharcellView, boolean>>;
+}

package/dist/declarations/application/shells/charcell/controller-context.d.ts

@@ -0,0 +1,9 @@
+import type { PreviewController, PreviewState } from '../../../src/shell';
+import type { CharcellShellConfiguration } from './configuration';
+export declare const PreviewControllerContext: import("react").Context<PreviewController | null>;
+export declare const ShellConfigurationContext: import("react").Context<CharcellShellConfiguration>;
+export declare function usePreviewController(): PreviewController;
+/** A slice of the controller's state, re-rendering when it changes. */
+export declare function usePreviewState<Selected>(selector: (state: PreviewState) => Selected): Selected;
+/** The slot fills and group placement the shell was made with. */
+export declare function useShellConfiguration(): CharcellShellConfiguration;

package/dist/declarations/application/shells/charcell/fit-labels.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Fit padded labels, side by side, into a number of cells. The last label
+ * gives way first: it loses a letter at a time behind an ellipsis, and once
+ * only a letter and the ellipsis would be left it goes, and the one before it
+ * starts giving way.
+ *
+ * @param labels - The labels, in their reading order.
+ * @param cells - The cells there are, or `undefined` before they are known.
+ * @returns The labels that fit, as they should read; empty if none does.
+ * @example
+ * ```ts
+ * fitLabels(['reload', 'open'], 14); // ['reload', 'open']
+ * fitLabels(['reload', 'open'], 11); // ['reload']
+ * fitLabels(['reload', 'open'], 8); // ['reload']
+ * fitLabels(['reload', 'open'], 3); // []
+ * ```
+ */
+export declare function fitLabels(labels: readonly string[], cells: number | undefined): string[];

package/dist/declarations/application/shells/charcell/html-warnings.d.ts

@@ -0,0 +1,5 @@
+/** The count the html's warnings show as: `1 warning`, `2 warnings`. */
+export declare function htmlWarningsLabel(warnings: readonly string[]): string;
+/** The hint over the count, in markdown: what the html leaves out, then
+ *  each warning as code on a line of its own. */
+export declare function htmlWarningsHint(warnings: readonly string[]): string;