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

package/application/shells/charcell/components/ComponentStage/index.tsx

@@ -0,0 +1,110 @@
+// A component story: the stage bar (StageBar), which picks the component
+// and its scenario and sets the context the story is shown in. Then the
+// stage's views, each a row the top bar toggles and the address keeps, each
+// under its heading (ViewHeading): the scenario row (ScenarioRow) over the
+// grid (PreviewGrid) of the output row, a preview pane per target, and the
+// code row, each target's source under its pane (CodePane), over the events
+// row (EventsRow), the rows sharing the height in a split the reader can drag
+// (StageSplit). A row after the scenario row is headed on its handle's row,
+// or on a row of its own with none above, with that view's controls at the
+// row's end (ViewControls): output's options, its width (PaneWidth) among
+// them, code's options and wrap toggle
+// (WrapToggle), or the events' options and clear (EventsClear). With no view
+// showing, a note says how to show one.
+//
+// The editor is the scenario row's: it is open while the row shows, where the
+// preview can regenerate, and closed while it is hidden. Closing it keeps its
+// tree, so showing the row again brings the same tree back, until another
+// story or scenario is picked; selecting another story closes the editor, and
+// the row opens it again on the new story. Where there is an editor, the row
+// first shows once it is open, before the page paints, so the row starts at
+// the height of its content with the editor's tree in it; it then stays
+// through another story's selection, at the height the reader left it.
+import { useLayoutEffect, useRef } from 'react';
+import { usePreviewController, usePreviewState } from '../../controller-context';
+import { PaneWidth, usePaneWidthShown } from '../PaneWidth';
+import { PreviewGrid } from '../PreviewGrid';
+import { ScenarioRow } from '../ScenarioRow';
+import { StageSplit } from '../StageSplit';
+import { EventsClear, EventsRow } from '../EventsRow';
+import { CODE_VIEW_OPTION, EVENTS_VIEW_OPTION, OUTPUT_VIEW_OPTION, SCENARIO_VIEW_OPTION } from '../../shell-options';
+import { useStage } from '../../stage-toggles';
+import { StageBar } from '../StageBar';
+import { ViewControls } from '../ViewControls';
+import { ViewHeading } from '../ViewHeading';
+import { WrapToggle } from '../WrapToggle';
+import './index.css';
+
+export function ComponentStage() {
+  const controller = usePreviewController();
+  const selection = usePreviewState((state) => state.selection);
+  const editorOpen = usePreviewState((state) => state.editor.open);
+  // The views and panes the stage shows: in a narrow window the first of each.
+  const { views, panes } = useStage();
+  const scenarioShown = views.has(SCENARIO_VIEW_OPTION);
+  const outputShown = views.has(OUTPUT_VIEW_OPTION);
+  const codeShown = views.has(CODE_VIEW_OPTION);
+  const eventsShown = views.has(EVENTS_VIEW_OPTION);
+  const sourced = usePreviewState((state) => state.code !== undefined);
+  const paneWidthShown = usePaneWidthShown();
+  const selected = controller.catalog.components.find((component) => component.id === selection.id);
+  const editable = controller.capabilities.regeneration && selected !== undefined;
+  const code = Boolean(selected && codeShown && sourced);
+
+  // Whether the scenario row shows: once the editor is open, where there is
+  // one, and from then on until the view is hidden.
+  const rowShown = useRef(false);
+  rowShown.current = Boolean(selected && scenarioShown && (editorOpen || !editable || rowShown.current));
+
+  // The editor follows the scenario row.
+  useLayoutEffect(() => {
+    if (!editable) return;
+    if (scenarioShown && !editorOpen) controller.editor.open();
+    else if (!scenarioShown && editorOpen) controller.editor.close();
+  }, [controller, editable, scenarioShown, editorOpen, selection]);
+
+  return (
+    <div className="ComponentStage">
+      <StageBar />
+      <div className="ComponentStage__body">
+        {!scenarioShown && !outputShown && !code && !eventsShown && (
+          <p className="ComponentStage__note" data-testid="stage-note">
+            No view is showing: turn on scenario, output, code or events in the top bar.
+          </p>
+        )}
+        <StageSplit
+          rows={[
+            { id: 'scenario', shown: rowShown.current, content: <ScenarioRow /> },
+            {
+              id: 'grid',
+              shown: outputShown || code,
+              label: 'resize scenario and panes',
+              content: <PreviewGrid targets={panes} output={outputShown} code={code} />,
+              heading: <ViewHeading>{outputShown || !code ? 'output' : 'code'}</ViewHeading>,
+              controls:
+                outputShown || !code ? (
+                  <ViewControls view="output" options={paneWidthShown ? <PaneWidth /> : undefined} />
+                ) : (
+                  <ViewControls view="code">
+                    <WrapToggle />
+                  </ViewControls>
+                ),
+            },
+            {
+              id: 'events',
+              shown: Boolean(selected && eventsShown),
+              label: outputShown || code ? 'resize panes and events' : 'resize scenario and events',
+              content: <EventsRow />,
+              heading: <ViewHeading>events</ViewHeading>,
+              controls: (
+                <ViewControls view="events">
+                  <EventsClear />
+                </ViewControls>
+              ),
+            },
+          ]}
+        />
+      </div>
+    </div>
+  );
+}

package/application/shells/charcell/components/Control/index.css

@@ -0,0 +1,20 @@
+@layer charcell.components {
+  /* A control's name and its control are two cells of the grid it sits in
+     (the props window's), so the names line up in one column and the
+     controls in the next. */
+  .Control {
+    display: contents;
+  }
+  .Control__label {
+    min-height: var(--charcell-row);
+    display: flex;
+    align-items: center;
+    color: var(--charcell-mid);
+  }
+  .Control__value {
+    min-width: 0;
+    min-height: var(--charcell-row);
+    display: flex;
+    align-items: center;
+  }
+}

package/application/shells/charcell/components/Control/index.tsx

@@ -0,0 +1,118 @@
+// One prop control (text / boolean / number / select / color-select) in the
+// scenario editor's props window: the prop's name and its control, laid as two
+// cells of the window's grid, so every name lines up in one column and every
+// control in the next. A prop left unset shows the default the component
+// declares or documents: in a select's unset option (`(unset: solid)`), as a
+// field's placeholder, and as a boolean's state. Composed from charcell's
+// TextInput and Toggle and the preview's Select. Styled in its index.css.
+import { useId } from 'react';
+import { TextInput, Toggle } from 'charcell/react/unlinked';
+import type { PreviewPropType } from '../../../../../src/shell';
+import { usePreviewController } from '../../controller-context';
+import { Select } from '../Select';
+import { Hint } from '../Hint';
+import './index.css';
+
+type Json = unknown;
+
+/** The default a prop takes while unset, as the reader reads it: the
+ *  component's declared default, or else the one it documents, its quotes
+ *  dropped. */
+function defaultOf(propType: PreviewPropType): string | undefined {
+  if (propType.declaredDefault !== undefined && propType.declaredDefault !== null)
+    return typeof propType.declaredDefault === 'string'
+      ? propType.declaredDefault
+      : JSON.stringify(propType.declaredDefault);
+  return propType.documentedDefault?.replace(/^(['"`])(.*)\1$/, '$2');
+}
+
+export function Control(props: { propType: PreviewPropType; value: Json; onChange: (nextValue: Json) => void }) {
+  const { propType, value, onChange } = props;
+  const controller = usePreviewController();
+  const id = useId();
+  const fallback = defaultOf(propType);
+  let control: React.ReactNode;
+  let labeled = true;
+  if (propType.control === 'boolean') {
+    // Unset, a boolean shows the state its default gives it.
+    const on = value === undefined ? fallback === 'true' : Boolean(value);
+    // The toggle's text is its state; the prop's name names it.
+    labeled = false;
+    control = (
+      <Toggle variant="dense" aria-labelledby={`${id}-label`} label={on ? 'on' : 'off'} pressed={on} onPressedChange={() => onChange(!on)} />
+    );
+  } else if (propType.control === 'number') {
+    const numberRange = propType.number ?? {};
+    control = (
+      <TextInput
+        id={id}
+        variant="dense"
+        type="number"
+        min={numberRange.min}
+        max={numberRange.max}
+        step={numberRange.step}
+        placeholder={fallback}
+        value={value === undefined ? '' : String(value)}
+        onChange={(event) => onChange(event.target.value === '' ? undefined : Number(event.target.value))}
+      />
+    );
+  } else if (propType.control === 'select' || propType.control === 'color-select') {
+    // A select's values are strings or booleans (`boolean | 'indeterminate'`
+    // offers true, false and 'indeterminate'), each written as its text and
+    // read back as the value it stands for.
+    const raw: (string | boolean | null | undefined)[] =
+      propType.control === 'color-select' ? controller.catalog.colorTokens : propType.options ?? [];
+    const unset = fallback === undefined ? '(unset)' : `(unset: ${fallback})`;
+    control = (
+      <Select
+        id={id}
+        value={value === undefined ? '' : String(value)}
+        onChange={(selected) =>
+          onChange(
+            selected === ''
+              ? undefined
+              : raw.find((option) => option !== null && option !== undefined && String(option) === selected) ?? selected
+          )
+        }
+        options={raw.map((option) => ({
+          value: option === null || option === undefined ? '' : String(option),
+          label: option === null || option === undefined ? unset : String(option),
+        }))}
+      />
+    );
+  } else {
+    control = (
+      <TextInput
+        id={id}
+        variant="dense"
+        type="text"
+        placeholder={fallback}
+        value={value === undefined ? '' : String(value)}
+        onChange={(event) => onChange(event.target.value)}
+      />
+    );
+  }
+  return (
+    // The description is a hint over the name: the row itself has no box
+    // to hover.
+    <div className="Control">
+      {/* `<id>-label`, as charcell's Field gives a label: a select and a
+          boolean's toggle name themselves from it. The hint takes it as its
+          trigger's id, so it opens beside the name. */}
+      <Hint text={propType.description} markdown triggerProps={{ id: `${id}-label` }}>
+        {(hint) =>
+          labeled ? (
+            <label {...hint} className="Control__label" htmlFor={id}>
+              {propType.name}
+            </label>
+          ) : (
+            <span {...hint} className="Control__label">
+              {propType.name}
+            </span>
+          )
+        }
+      </Hint>
+      <span className="Control__value">{control}</span>
+    </div>
+  );
+}

package/application/shells/charcell/components/CopyLink/index.tsx

@@ -0,0 +1,35 @@
+// The status bar's `copy link`: the address of what the preview shows now -
+// the story, its scenario and props, the options and the views - which opens
+// it as it is. It says `link copied` for a moment after.
+import { Button } from 'charcell/react/unlinked';
+import { useEffect, useState } from 'react';
+import { Hint } from '../Hint';
+
+/** How long the confirmation shows, in milliseconds. */
+const COPIED_MILLISECONDS = 1500;
+
+export function CopyLink() {
+  const [copied, setCopied] = useState(false);
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), COPIED_MILLISECONDS);
+    return () => clearTimeout(timer);
+  }, [copied]);
+  return (
+    <Hint text="copy the address of what the preview shows now">
+      {(hint) => (
+        <Button
+          {...hint}
+          variant="dense"
+          label={copied ? 'link copied' : 'copy link'}
+          onClick={() =>
+            navigator.clipboard?.writeText(window.location.href).then(
+              () => setCopied(true),
+              () => undefined,
+            )
+          }
+        />
+      )}
+    </Hint>
+  );
+}

package/application/shells/charcell/components/Description/index.css

@@ -0,0 +1,6 @@
+@layer charcell.components {
+  /* The info button's `i`, in italics, as an information sign is set. */
+  .Description__button {
+    font-style: italic;
+  }
+}

package/application/shells/charcell/components/Description/index.tsx

@@ -0,0 +1,24 @@
+// The info button beside a picker in the stage bar: an italic `i`, which opens a
+// charcell Popover holding a description, its markdown rendered (Markdown).
+// Nothing renders without a description. Styled in its index.css.
+import { Button, Popover } from 'charcell/react/unlinked';
+import { Hint } from '../Hint';
+import { Markdown } from '../Markdown';
+import './index.css';
+
+export function Description({ text, label }: { text?: string; label: string }) {
+  if (!text?.trim()) return null;
+  return (
+    <Popover
+      label={label}
+      width={48}
+      trigger={({ triggerProps }) => (
+        <Hint text={label} triggerProps={triggerProps}>
+          {(props) => <Button variant="dense" className="Description__button" label="i" aria-label={label} {...props} />}
+        </Hint>
+      )}
+    >
+      <Markdown text={text} />
+    </Popover>
+  );
+}

package/application/shells/charcell/components/EditorAddDialog/index.css

@@ -0,0 +1,9 @@
+@layer charcell.components {
+  /* The add dialog. Its root is the positioner, the
+     shell's own element: it takes charcell's popover layer, as charcell's own
+     Popover does. */
+  .EditorAddDialog {
+    --z-index: var(--charcell-layer-popover);
+    z-index: var(--charcell-layer-popover);
+  }
+}

package/application/shells/charcell/components/EditorAddDialog/index.tsx

@@ -0,0 +1,158 @@
+// The editor's add-content control: a charcell Popover whose trigger is the
+// `add...` button and whose content is the add form - pick the kind (text,
+// component or html tag), the value (the text, which component, or a tag),
+// the scenario a component comes in at, and - only when there is a choice -
+// which slot to add into. The node itself is the controller's to make
+// (`editor.createNode`); the form only gathers the request.
+import { useId, useState } from 'react';
+import { Portal } from '@zag-js/react';
+import { Button, Field, PopoverDriver, PopoverPanel, TextInput } from 'charcell/react/unlinked';
+import { Hint } from '../Hint';
+import { DEFAULT_SLOT, type EditorNode, type PreviewNodeRequest } from '../../../../../src/shell';
+import { usePreviewController } from '../../controller-context';
+import { Select } from '../Select';
+import './index.css';
+
+type Kind = 'text' | 'component' | 'html';
+
+export function EditorAddDialog(props: { slots: string[]; onAdd: (slot: string, child: EditorNode) => void }) {
+  const { slots, onAdd } = props;
+  const controller = usePreviewController();
+  const { htmlTags } = controller.catalog;
+  // An unlisted story is not offered: it is reachable at its address alone.
+  const components = controller.catalog.components.filter((candidate) => !candidate.unlisted);
+  const [open, setOpen] = useState(false);
+  const textId = useId();
+  const [kind, setKind] = useState<Kind>('text');
+  const [text, setText] = useState('text');
+  const [tag, setTag] = useState(htmlTags[0]);
+  const [component, setComponent] = useState(components[0]?.name ?? '');
+  // Which configuration a component comes in at - `empty` (the default: a blank
+  // node), `default` (the curated defaults and slot content), or a named scenario.
+  const [importAs, setImportAs] = useState('empty');
+  const [slot, setSlot] = useState(slots[0] ?? DEFAULT_SLOT);
+
+  const found = components.find((candidate) => candidate.name === component);
+  // The baseline scenario (its label names the "default" option) and the rest the
+  // dialog offers - excluding the preview's `empty` and the `default` one.
+  const defaultScenario = (found?.scenarios ?? []).find((scenario) => scenario.default);
+  const namedScenarios = (found?.scenarios ?? []).filter((scenario) => !scenario.empty && !scenario.default);
+  // "Empty" is a composable-content concept: the scenario choice is offered only
+  // when the component has slot content to strip (or a named scenario). A
+  // content-less component (an icon) comes in at its default.
+  const hasImportChoice =
+    !!found && (found.slots.default || found.slots.named.length > 0 || namedScenarios.length > 0);
+
+  function add() {
+    let request: PreviewNodeRequest | null = null;
+    if (kind === 'text') request = { kind: 'text', value: text };
+    else if (kind === 'html') request = { kind: 'html', tag };
+    else if (found) {
+      request = {
+        kind: 'component',
+        name: found.name,
+        importAs:
+          importAs === 'empty' || importAs === 'default' ? importAs : { scenario: importAs.replace(/^scenario:/, '') },
+      };
+    }
+    if (request) onAdd(slot, controller.editor.createNode(request));
+    setOpen(false);
+  }
+
+  // charcell's PopoverDriver and Visuals composed directly (controlled open):
+  // the same escape hatch as the panes. The positioner is the dialog's own
+  // element. The panel is at least 32 cells wide and grows past that with its
+  // content, for a long component name.
+  return (
+    <PopoverDriver open={open} onOpenChange={setOpen}>
+      {({ api }) => (
+        <>
+          <Hint text="add content" triggerProps={api.getTriggerProps()}>
+            {(props) => <Button variant="dense" label="add…" {...props} />}
+          </Hint>
+          {api.open && (
+            <Portal>
+              <div className="EditorAddDialog" {...api.getPositionerProps()}>
+                <PopoverPanel minWidth={32} {...api.getContentProps()} data-preview-dialog>
+                  <p>
+                    <Select
+                      label="kind"
+                      testId="add-dialog-kind"
+                      value={kind}
+                      onChange={(value) => setKind(value as Kind)}
+                      options={[
+                        { value: 'text', label: 'text' },
+                        { value: 'component', label: 'component' },
+                        { value: 'html', label: 'html tag' },
+                      ]}
+                    />
+                  </p>
+                  <p>
+                    {kind === 'text' ? (
+                      <Field label="value" htmlFor={textId}>
+                        <TextInput
+                          id={textId}
+                          variant="dense"
+                          type="text"
+                          value={text}
+                          onChange={(event) => setText(event.target.value)}
+                        />
+                      </Field>
+                    ) : kind === 'html' ? (
+                      <Select
+                        label="tag"
+                        testId="add-dialog-tag"
+                        value={tag}
+                        onChange={setTag}
+                        options={htmlTags.map((tag) => ({ value: tag, label: tag }))}
+                      />
+                    ) : (
+                      <Select
+                        label="component"
+                        testId="add-dialog-component"
+                        value={component}
+                        onChange={(value) => {
+                          setComponent(value);
+                          setImportAs('empty');
+                        }}
+                        options={components.map((candidate) => ({ value: candidate.name, label: candidate.name }))}
+                      />
+                    )}
+                  </p>
+                  {kind === 'component' && hasImportChoice && (
+                    <p>
+                      <Select
+                        label="scenario"
+                        testId="add-dialog-scenario"
+                        value={importAs}
+                        onChange={setImportAs}
+                        options={[
+                          { value: 'empty', label: 'empty' },
+                          { value: 'default', label: defaultScenario?.label ?? 'default' },
+                          ...namedScenarios.map((scenario) => ({ value: `scenario:${scenario.id}`, label: scenario.label })),
+                        ]}
+                      />
+                    </p>
+                  )}
+                  {slots.length > 1 && (
+                    <p>
+                      <Select
+                        label="slot"
+                        testId="add-dialog-slot"
+                        value={slot}
+                        onChange={setSlot}
+                        options={slots.map((slot) => ({ value: slot, label: slot }))}
+                      />
+                    </p>
+                  )}
+                  <Button variant="dense" label="add" onClick={add} />{' '}
+                  <Button variant="dense" label="cancel" onClick={() => setOpen(false)} />
+                </PopoverPanel>
+              </div>
+            </Portal>
+          )}
+        </>
+      )}
+    </PopoverDriver>
+  );
+}

package/application/shells/charcell/components/EditorPanel/index.css

@@ -0,0 +1,48 @@
+@layer charcell.components {
+  /* The editor panel's nodes, props and slots are quiet Frames: a window's
+     name is its Frame title with its action in the legend, the drop target's
+     ring goes foreground (`active`), and the lifted clone is raised (a double
+     right and bottom border). Rows carry the spacing: adjacent rings sit a
+     full row apart by their own ring geometry. */
+  .EditorPanel__row {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    min-height: var(--charcell-row);
+    gap: 1ch;
+    row-gap: 0;
+  }
+  .EditorPanel__label {
+    color: var(--charcell-mid);
+  }
+  /* The remove control's own box, pushed to the row's end. */
+  .EditorPanel__remove {
+    display: flex;
+    margin-left: auto;
+  }
+  /* A locked raw or scoped fill, or the content beside the root: on one
+     line, cut to the row. */
+  .EditorPanel__opaque {
+    flex: 1 1 0;
+    min-width: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  /* A props window's controls: the names in one column, the controls in the
+     next, a row each. */
+  .EditorPanel__controls {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    column-gap: 2ch;
+    row-gap: 0;
+  }
+  .EditorPanel__add {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: 1ch;
+    justify-content: flex-end;
+    min-height: var(--charcell-row);
+  }
+}