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

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

@@ -0,0 +1,99 @@
+// The component stage's body: its rows, top to bottom, in a stacked charcell
+// Splitter - the scenario row while the scenario view shows, the grid of the
+// output and code rows (PreviewGrid) while either shows, and the events row
+// while the events view shows - each handle between two rows dragging the
+// boundary a whole row at a time. A row after the first is headed on its
+// handle's row, its heading at the start and its controls at the end, around
+// the grip; a headed row with no row above has the same row to itself,
+// without a grip. SplitGrid has no cell spanning its columns, so the scenario
+// and events rows sit over and under the grid rather than in it.
+//
+// The scenario row starts at its content's height - its picker row and, where
+// the preview can regenerate, the editor's tree - and keeps at least its ring
+// and one row inside it; the events row starts a few rows tall. The grid
+// takes the rest. The split measures the scenario row, and measures again as
+// its content changes, unless the reader has moved the boundary since.
+//
+// The grid's panel stays in the split while the grid has no row showing,
+// hidden and out of the split's panels, and the whole split is hidden while
+// no view shows, so the panes keep their place in the tree, and their frames,
+// whichever views open and close.
+import { Fragment, useMemo, type ReactNode } from 'react';
+import {
+  SplitterDriver,
+  SplitterHandle,
+  SplitterHandleRow,
+  SplitterPanel,
+  SplitterVisual,
+} from 'charcell/react/unlinked';
+import './index.css';
+
+/** The fewest rows the scenario and events rows keep: a ring and one row inside. */
+const LEAST_ROWS = 3;
+
+/** The rows the events row starts at beside the others. */
+const EVENTS_ROWS = 8;
+
+/** 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 function StageSplit({ rows }: { rows: StageRow[] }) {
+  const shown = rows.filter((row) => row.shown);
+  const key = shown.map((row) => row.id).join(',');
+  // The panels follow which rows show, and nothing else.
+  const panels = useMemo(() => {
+    const ids = key === '' ? [] : key.split(',');
+    return ids.map((id) =>
+      ids.length === 1
+        ? { id }
+        : id === 'scenario'
+          ? { id, minimumCells: LEAST_ROWS, defaultCells: 'content' as const }
+          : id === 'events'
+            ? { id, minimumCells: LEAST_ROWS, defaultCells: EVENTS_ROWS }
+            : { id },
+    );
+  }, [key]);
+  return (
+    <div className="StageSplit" hidden={shown.length === 0}>
+      <SplitterDriver orientation="vertical" panels={panels}>
+        {({ api }) => (
+          <SplitterVisual orientation="vertical" fill {...api.getRootProps()}>
+            {rows.map((row) => {
+              const index = shown.indexOf(row);
+              const above = index > 0 ? shown[index - 1] : undefined;
+              // The grid stays in the tree while hidden, in the same place,
+              // so its panes keep their frames; another row leaves.
+              if (!row.shown && row.id !== 'grid') return null;
+              return (
+                <Fragment key={row.id}>
+                  {above && (
+                    <SplitterHandle
+                      label={row.label ?? `resize ${above.id} and ${row.id}`}
+                      {...api.getResizeTriggerProps({ id: `${above.id}:${row.id}` })}
+                    />
+                  )}
+                  {row.shown && row.heading !== undefined && (
+                    <SplitterHandleRow start={row.heading} end={row.controls} />
+                  )}
+                  <SplitterPanel {...(row.shown ? api.getPanelProps({ id: row.id }) : { hidden: true })}>
+                    {row.content}
+                  </SplitterPanel>
+                </Fragment>
+              );
+            })}
+          </SplitterVisual>
+        )}
+      </SplitterDriver>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+// The shell's bottom status bar: the panes' state (PaneStatus) and a copy of
+// the preview's address (CopyLink) at the start; at the end, the options
+// placed in the status bar (a global option of a group of the kit's own
+// naming, unless the kit places it elsewhere), the kit's `status-bar` slot,
+// and a hint of the shell's keys.
+import { Bar } from '../Bar';
+import { CopyLink } from '../CopyLink';
+import { KeyHints } from '../KeyHints';
+import { OptionControls } from '../OptionControls';
+import { PaneStatus } from '../PaneStatus';
+import { SlotOutlet } from '../SlotOutlet';
+
+export function StatusBar() {
+  return (
+    <Bar
+      variant="status"
+      joined
+      end={
+        <>
+          <OptionControls placement="status-bar" />
+          <SlotOutlet name="status-bar" />
+          <KeyHints />
+        </>
+      }
+    >
+      <PaneStatus />
+      <CopyLink />
+    </Bar>
+  );
+}

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

@@ -0,0 +1,15 @@
+@layer charcell.components {
+  /* The options, the slot and the view's own control, spaced as a band's
+     items are. */
+  .ViewControls {
+    display: flex;
+    align-items: center;
+    gap: 2ch;
+  }
+  /* In a popover, the options a row each. */
+  .ViewControls__options {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+  }
+}

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

@@ -0,0 +1,58 @@
+// The end of a view's heading row: the options placed in the view's region,
+// with the view's own options after them (the output's width), the kit's
+// slot for the view (`<view>-end`), and the view's own control (the wrap
+// toggle, the events' clear). A view the shell's `popovers` names, the
+// output by default, holds its options in a charcell Popover; any other lays
+// them in the row. No options, no popover. Styled in its index.css.
+import { Button, Popover } from 'charcell/react/unlinked';
+import { Hint } from '../Hint';
+import type { ReactNode } from 'react';
+import type { CharcellView } from '../../configuration';
+import { useShellConfiguration } from '../../controller-context';
+import { OptionControls, useHasOptionControls } from '../OptionControls';
+import { SlotOutlet } from '../SlotOutlet';
+import './index.css';
+
+/** The views whose options sit in a popover unless the kit says otherwise. */
+const POPOVER_VIEWS: CharcellView[] = ['output'];
+
+export 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;
+}) {
+  const popover = useShellConfiguration().popovers?.[view] ?? POPOVER_VIEWS.includes(view);
+  const hasOptions = useHasOptionControls(view) || ownOptions !== undefined;
+  const options = !hasOptions ? null : popover ? (
+    <Popover
+      label={`${view} options`}
+      trigger={({ triggerProps }) => (
+        <Hint text={`the ${view}'s options`} triggerProps={triggerProps}>
+          {(props) => <Button variant="dense" label="options…" {...props} />}
+        </Hint>
+      )}
+    >
+      <div className="ViewControls__options">
+        <OptionControls placement={view} />
+        {ownOptions}
+      </div>
+    </Popover>
+  ) : (
+    <>
+      <OptionControls placement={view} />
+      {ownOptions}
+    </>
+  );
+  return (
+    <span className="ViewControls">
+      {options}
+      <SlotOutlet name={`${view}-end`} />
+      {children}
+    </span>
+  );
+}

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

@@ -0,0 +1,13 @@
+@layer charcell.components {
+  /* A row tall, its name bold. The row it sits on places it a cell in from
+     the row's start. charcell's reset flattens headings, so the weight is
+     stated here. */
+  .ViewHeading {
+    margin: 0;
+    min-height: var(--charcell-row);
+    display: flex;
+    align-items: center;
+    font: inherit;
+    font-weight: 700;
+  }
+}

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

@@ -0,0 +1,8 @@
+// A view's heading on the row above it: the view's name, as the top bar's
+// view toggle names it - on the handle row between it and the view above, or
+// on a row of its own. Styled in its index.css.
+import './index.css';
+
+export function ViewHeading({ children }: { children: string }) {
+  return <h2 className="ViewHeading">{children}</h2>;
+}

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

@@ -0,0 +1,9 @@
+@layer charcell.components {
+  /* A custom view's one pane, its Frame filling the stage's place as the
+     grid's panes do (charcell's `fill`). */
+  .ViewStage {
+    flex: 1;
+    display: flex;
+    min-height: 0;
+  }
+}

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

@@ -0,0 +1,25 @@
+// A custom view: the stage bar (StageBar), the output heading with its
+// controls (ViewControls), then the view, rendered through
+// the generic view iframe, which the controller mounts and drives (the ready
+// handshake delivers the current options, replayed on reload). One branch
+// serves every registered view - no special-casing.
+import { usePreviewController } from '../../controller-context';
+import { PreviewPane } from '../PreviewPane';
+import { HeadingRow } from '../HeadingRow';
+import { ViewControls } from '../ViewControls';
+import { StageBar } from '../StageBar';
+import './index.css';
+
+export function ViewStage({ viewId }: { viewId: string }) {
+  const controller = usePreviewController();
+  const view = controller.catalog.views.find((candidate) => candidate.id === viewId);
+  return (
+    <>
+      <StageBar />
+      <HeadingRow heading="output" end={<ViewControls view="output" />} />
+      <div className="ViewStage">
+        <PreviewPane title={(view?.label ?? viewId).toLowerCase()} viewId={viewId} />
+      </div>
+    </>
+  );
+}

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

@@ -0,0 +1,27 @@
+// The code panes' wrap toggle, one for every pane, at the end of the code
+// view's heading row: the shell's `wrap` option, so the address keeps it.
+// On, a long line wraps at its pane's edge; off, it runs on and the source
+// scrolls across. A kit's own code block follows it too, told through the
+// controller (KitCodeBlock).
+import { Toggle } from 'charcell/react/unlinked';
+import { usePreviewController, usePreviewState } from '../../controller-context';
+import { WRAP_OPTION } from '../../shell-options';
+import { Hint } from '../Hint';
+
+export function WrapToggle() {
+  const controller = usePreviewController();
+  const wrapped = usePreviewState((state) => state.options[WRAP_OPTION] !== false);
+  return (
+    <Hint text="wrap long lines in every code pane" around>
+      {(hint) => (
+        <Toggle
+          variant="dense"
+          {...hint}
+          label="wrap"
+          pressed={wrapped}
+          onPressedChange={() => controller.actions.setOption(WRAP_OPTION, !wrapped)}
+        />
+      )}
+    </Hint>
+  );
+}

package/application/shells/charcell/configuration.ts

@@ -0,0 +1,45 @@
+// What a kit configures the charcell shell with: content for its named slots
+// and where each option group goes. The types alone; `index.tsx` takes them.
+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/application/shells/charcell/controller-context.ts

@@ -0,0 +1,27 @@
+// The shell's own way of reaching its controller and its configuration: two
+// React contexts the root provides, and hooks over them. The controller SDK
+// holds no context of its own; these belong to this shell.
+import { createContext, useContext } from 'react';
+import type { PreviewController, PreviewState } from '../../../src/shell';
+import { usePreview } from '../../../src/react';
+import type { CharcellShellConfiguration } from './configuration';
+
+export const PreviewControllerContext = createContext<PreviewController | null>(null);
+
+export const ShellConfigurationContext = createContext<CharcellShellConfiguration>({});
+
+export function usePreviewController(): PreviewController {
+  const controller = useContext(PreviewControllerContext);
+  if (!controller) throw new Error('The charcell shell is rendered outside its controller context.');
+  return controller;
+}
+
+/** A slice of the controller's state, re-rendering when it changes. */
+export function usePreviewState<Selected>(selector: (state: PreviewState) => Selected): Selected {
+  return usePreview(usePreviewController(), selector);
+}
+
+/** The slot fills and group placement the shell was made with. */
+export function useShellConfiguration(): CharcellShellConfiguration {
+  return useContext(ShellConfigurationContext);
+}

package/application/shells/charcell/fit-labels.ts

@@ -0,0 +1,42 @@
+// A row of short labels cut to a number of cells, a whole cell at a time, for
+// controls that must never show a fraction of a character.
+
+/** What stands for the letters a cut label has lost: the one ellipsis glyph,
+ *  a single cell where three dots would take three. */
+const ELLIPSIS = '\u2026';
+
+/** The fewest cells a cut label's text takes: one letter and the ellipsis. */
+const LEAST_CUT_CELLS = 2;
+
+/** The cells a label takes beside its text: one of padding at each side. */
+const PADDING_CELLS = 2;
+
+/**
+ * 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 function fitLabels(labels: readonly string[], cells: number | undefined): string[] {
+  if (cells === undefined) return [...labels];
+  for (let last = labels.length - 1; last >= 0; last -= 1) {
+    const before = labels.slice(0, last);
+    const taken = before.reduce((sum, label) => sum + [...label].length + PADDING_CELLS, 0);
+    const room = cells - taken - PADDING_CELLS;
+    const letters = [...labels[last]!];
+    if (room >= letters.length) return [...before, labels[last]!];
+    if (room >= LEAST_CUT_CELLS) return [...before, `${letters.slice(0, room - 1).join('')}${ELLIPSIS}`];
+  }
+  return [];
+}

package/application/shells/charcell/html-warnings.ts

@@ -0,0 +1,18 @@
+// What the html pane and the html code pane say about the expressions the
+// story's html could not evaluate at rest: a count, and a hint that says what
+// that means before listing them, one to a line.
+
+/** The count the html's warnings show as: `1 warning`, `2 warnings`. */
+export function htmlWarningsLabel(warnings: readonly string[]): string {
+  return `${warnings.length} ${warnings.length === 1 ? 'warning' : 'warnings'}`;
+}
+
+/** The hint over the count, in markdown: what the html leaves out, then
+ *  each warning as code on a line of its own. */
+export function htmlWarningsHint(warnings: readonly string[]): string {
+  return [
+    'The html leaves out what it cannot evaluate at rest, so the parts it decides show at a default or not at all:',
+    '',
+    ...warnings.map((warning) => `- \`${warning.replace(/`/g, "'")}\``),
+  ].join('\n');
+}

package/application/shells/charcell/index.tsx

@@ -0,0 +1,82 @@
+// The charcell shell: the preview's interface drawn in charcell's terminal
+// look. `charcellShell(configuration)` makes a shell with fills for its named
+// slots and a mapping of option groups to its regions; the module's default
+// export is the shell with no configuration, so a kit can name this module
+// as its `preview.shell`. The shell is built on the preview's
+// public shell contract and React bindings alone.
+import { createElement, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { defineShell, PREVIEW_SHELL_API_VERSION, type PreviewController, type PreviewShell } from '../../../src/shell';
+import { CharcellApplication } from './shell';
+import type { CharcellRegion, CharcellShellConfiguration, CharcellSlotFill, CharcellSlotName } from './configuration';
+
+export type { CharcellRegion, CharcellShellConfiguration, CharcellSlotFill, CharcellSlotName };
+
+/**
+ * Make the charcell shell, with content for its slots and a placement for
+ * the kit's option groups.
+ *
+ * @param configuration - The slot fills and the group placement.
+ * @returns The shell, for a kit's shell module to default-export.
+ * @example
+ * ```tsx
+ * import { charcellShell, reactFill } from '@scaffold-ui-kit/preview/shells/charcell';
+ *
+ * export default charcellShell({
+ *   slots: {
+ *     'top-bar-end': reactFill((controller) => <KitVersionPicker controller={controller} />),
+ *     'status-bar': (element, controller) => mountBadge(element, controller),
+ *   },
+ *   groups: { canvas: 'status-bar' },
+ * });
+ * ```
+ */
+export function charcellShell(configuration: CharcellShellConfiguration = {}): PreviewShell {
+  return defineShell({
+    apiVersion: PREVIEW_SHELL_API_VERSION,
+    // Whether the navigation shows, which of the stage's four views show (the
+    // scenario row, the preview panes, the code panes and the events log),
+    // and whether the code panes wrap their lines, kept in the address.
+    options: [
+      { id: 'navigation', label: 'navigation', default: true },
+      { id: 'scenario', label: 'scenario', default: false },
+      { id: 'output', label: 'output', default: true },
+      { id: 'code', label: 'code', default: false },
+      { id: 'events', label: 'events', default: false },
+      { id: 'wrap', label: 'wrap', default: true },
+    ],
+    mount(root, controller) {
+      const reactRoot = createRoot(root);
+      reactRoot.render(createElement(CharcellApplication, { controller, configuration }));
+      return () => reactRoot.unmount();
+    },
+  });
+}
+
+/**
+ * A slot fill written in React: `render` runs as a component of its own
+ * React tree inside the slot's element, so it may use hooks, such as
+ * `usePreview(controller, selector)` from `@scaffold-ui-kit/preview/react`.
+ *
+ * @param render - Renders the fill for the preview's controller.
+ * @returns The fill, for a slot of {@link charcellShell}.
+ * @example
+ * ```tsx
+ * reactFill((controller) => <span>{controller.catalog.kitName}</span>)
+ * ```
+ */
+export function reactFill(render: (controller: PreviewController) => ReactNode): CharcellSlotFill {
+  return (element, controller) => {
+    const root = createRoot(element);
+    root.render(createElement(ReactFill, { controller, render }));
+    // The shell unmounts its slots from inside its own React commit, and a
+    // root cannot be unmounted while another is rendering: so, just after.
+    return () => queueMicrotask(() => root.unmount());
+  };
+}
+
+function ReactFill(props: { controller: PreviewController; render: (controller: PreviewController) => ReactNode }) {
+  return props.render(props.controller);
+}
+
+export default charcellShell();

package/application/shells/charcell/page-loading.html

@@ -0,0 +1,57 @@
+<!-- What the host page shows under this shell until the shell mounts over
+     it: the shell's page module gives this file as the page's root. -->
+<style>
+  /* Nothing at all for the first 300ms, so a quick load has no flash, and
+     then a note in the middle of the page, its dots counting up. Spaces
+     hold the dots' place, so the word stays put. The note is set as the
+     shell's text is, in charcell's face at its size on a cell one character
+     wide and two tall, and sits on a whole cell counted from the page's
+     corner, the one nearest the middle, so it stands where the shell's own
+     text will. The page's head declares the face and preloads its font. */
+  .PreviewPageLoading {
+    position: fixed;
+    inset: 0;
+    font:
+      0.875rem/2ch 'Charcell Overpass Mono',
+      ui-monospace,
+      monospace;
+    color: #808080;
+  }
+  .PreviewPageLoading::after {
+    content: 'loading';
+    position: absolute;
+    left: round(down, calc((100% - 10ch) / 2), 1ch);
+    top: round(down, calc((100% - 2ch) / 2), 2ch);
+    white-space: pre;
+    visibility: hidden;
+    animation:
+      PreviewPageLoading-show 0s 300ms forwards,
+      PreviewPageLoading-dots 1.2s 300ms steps(1, end) infinite;
+  }
+  @keyframes PreviewPageLoading-show {
+    to {
+      visibility: visible;
+    }
+  }
+  @keyframes PreviewPageLoading-dots {
+    0% {
+      content: 'loading\00a0\00a0\00a0';
+    }
+    25% {
+      content: 'loading.\00a0\00a0';
+    }
+    50% {
+      content: 'loading..\00a0';
+    }
+    75%,
+    100% {
+      content: 'loading...';
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .PreviewPageLoading::after {
+      animation: PreviewPageLoading-show 0s 300ms forwards;
+    }
+  }
+</style>
+<div class="PreviewPageLoading" role="status" aria-label="loading"></div>

package/application/shells/charcell/placement.ts

@@ -0,0 +1,24 @@
+// Where this shell shows an option's control: a story option and a global
+// option of the context group (the group of an option that names none) in
+// the output view's region, the context the panes show the story in; a
+// global option of the kit's group in the top bar, and of any other group in
+// the status bar - unless the kit's `groups` mapping places the option's
+// group elsewhere.
+import { CONTEXT_OPTION_GROUP, KIT_OPTION_GROUP, optionGroup, type PreviewOptionDescriptor } from '../../../src/shell';
+import type { CharcellRegion } from './configuration';
+
+/**
+ * The region an option's control renders in. A group named in `groups` goes
+ * where the mapping says, whatever the option's scope.
+ */
+export function optionPlacement(
+  option: Pick<PreviewOptionDescriptor, 'scope' | 'group'>,
+  groups: Record<string, CharcellRegion> = {},
+): CharcellRegion {
+  const group = optionGroup(option);
+  const mapped = groups[group];
+  if (mapped) return mapped;
+  if (option.scope === 'story') return 'output';
+  if (group === KIT_OPTION_GROUP) return 'top-bar';
+  return group === CONTEXT_OPTION_GROUP ? 'output' : 'status-bar';
+}

package/application/shells/charcell/shell-options.ts

@@ -0,0 +1,23 @@
+// The ids of the shell's own options, as the controller's state keys them.
+import { shellOptionId } from '../../../src/shell';
+
+/** Whether the navigation shows. */
+export const NAVIGATION_OPTION = shellOptionId('navigation');
+
+/** Whether the scenario view shows: the stage's top row, holding the
+ *  scenario picker, the story's context and the editor. */
+export const SCENARIO_VIEW_OPTION = shellOptionId('scenario');
+
+/** Whether the output view shows: the row of preview panes. */
+export const OUTPUT_VIEW_OPTION = shellOptionId('output');
+
+/** Whether the code view shows: the row of code panes, each target's source
+ *  under its preview pane. */
+export const CODE_VIEW_OPTION = shellOptionId('code');
+
+/** Whether the events view shows: the log of the events the story's panes
+ *  recorded. */
+export const EVENTS_VIEW_OPTION = shellOptionId('events');
+
+/** Whether the code panes wrap their source's long lines: on by default. */
+export const WRAP_OPTION = shellOptionId('wrap');

package/application/shells/charcell/shell.css

@@ -0,0 +1,37 @@
+/*
+ * The charcell shell's own styling. The terminal look itself is charcell
+ * (`charcell/css/full`: tokens, reset, base, and the Tree / Frame / Select /
+ * Splitter / Toggle / Button / Field / TextInput components the shell
+ * composes) - the shell's stylesheets carry only what is the shell's: the
+ * viewport layout, the bands, the layout zones, the slots, the editor
+ * panel's internals, and the controls' fields. This one declares the layers
+ * and styles the page; each component styles itself, in an `index.css` beside
+ * its `index.tsx` that the component imports. All values ride charcell's
+ * tokens; no palette of its own. The custom properties are the one styling surface the
+ * shell promises; its class names and markup are its own.
+ *
+ * Each of the shell's components is a block of its own, named as the
+ * component is (`Application`, `Bar`, `EditorPanel`), with `Block__element`
+ * and `Block--modifier` classes. A block styles its own elements only: a
+ * charcell component that fills its place in a layout takes charcell's own
+ * `fill`, and where one needs any other size or place, the shell wraps it in
+ * an element of its own and styles that.
+ *
+ * The rules sit in charcell's cascade layers, as a charcell component's do:
+ * the page's in `charcell.base`, the blocks in `charcell.components`. A kit
+ * that adjusts the shell writes its rules in `charcell.overrides`, or outside
+ * any layer, and they win without a fight over specificity.
+ */
+
+@layer charcell.reset, charcell.base, charcell.components, charcell.overrides;
+
+/* The page: the screen (Application) sits centered in it, by margins of its
+   own; the body is a flex container only so those margins stay the screen's
+   rather than collapsing into the body's. */
+@layer charcell.base {
+  body {
+    height: 100vh;
+    display: flex;
+    overflow: hidden;
+  }
+}