@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/help/HelpSection.tsx

@@ -1,5 +1,19 @@
-// The left rail's Manual: how the editor works, the tool table and the keymap,
-// rendered where a first-time author actually looks.
+// The manual: the dialog the app menu's Help row opens.
+//
+// ── WHY A DIALOG AND NOT A PANEL SECTION ────────────────────────────────
+//
+// The left rail is the layer outliner. The manual is a five-line first-run
+// guide, thirteen tool rows and fifty-six shortcut rows, and the full MCP guide is
+// setup documentation. The Shot outliner now keeps only a compact MCP status
+// and connection footer tied to the open Project. Parking the complete manual
+// in the column the author reads to find a layer made that column harder to
+// scan. A `<details>` made that cost one summary line at rest, which is one
+// line more than a reference nobody has open deserves, and it read the whole
+// manual into a 232px column when opened.
+//
+// The shared `Dialog` (packages/ui) is what the export dialog and the material
+// picker already use, so Escape, the focus trap and `aria-modal` are answered
+// once for the lane rather than three times.
 //
 // ── ONE LIST, PINNED BY A TEST ──────────────────────────────────────────
 //
@@ -10,181 +24,193 @@
 // walks every row through `resolveKey`. A binding change without a manual
 // edit is a red test, not a stale manual.
 //
-// No store, no context: this section is static prose over static tables,
-// which is what lets the test mount it bare. The agent connect steps moved to
-// the File tab's MCP section (McpSection.tsx), where an author actually looks.
+// THE TABLE ITSELF MOVED to `state/shortcuts.ts` once the app menu became its
+// second reader: a data table reached through a React component drags a Dialog
+// into `state/menu.ts`, which is JSX-free on purpose. Re-exported here because
+// this is where every caller already looks for it.
+//
+// No store, no context: the content is static prose over static tables, which
+// is what lets the test mount it bare.
+import { Dialog } from "@dailies-studio/ui";
+import { McpSection } from "../files/McpSection.js";
 import { SHOT_TOOLS, specOf } from "../../tools.js";
-import type { KeyAction, KeyEventLike } from "../../state/keymap.js";
+import { layoutSpec } from "../../state/layouts.js";
+import { VIEW_MODE_SPECS } from "../../state/viewMode.js";
+import {
+  MATERIAL_SHORTCUTS,
+  STORYBOARD_SHORTCUTS,
+  SHORTCUTS,
+  SHORTCUT_GROUPS,
+  comboOf,
+  formatCombo,
+  toolKey,
+} from "../../state/shortcuts.js";
+import type { ShortcutGroup } from "../../state/shortcuts.js";
 
-export interface ShortcutRow {
-  /** What the manual shows, house glyph style (⌘ ⇧ ⌥ — ⌘ is Ctrl on Windows). */
-  combo: string;
-  does: string;
-  group: "View" | "Working view" | "Edit" | "Animate & camera";
-  /** The event this combo produces, so the test can ask the keymap itself. */
-  probe: KeyEventLike;
-  /** Arrows answer differently with a selection; everything else omits it. */
-  hasSelection?: boolean;
-  /** The pen's two rows answer differently with a path open, and ONLY with one
-   *  open — Escape means deselect the rest of the time, which is why the
-   *  context carries "holds points" and not "the pen tool is armed". */
-  penActive?: boolean;
-  /** Escape's third meaning: leave one level of isolation. It only answers
-   *  that with NOTHING selected, so the row carries the bit and the test
-   *  probes with `hasSelection` false. */
-  isolation?: boolean;
-  /** The modal starters (G/R/S) answer only with the cursor over the working
-   *  pane — the same letters arm tools everywhere else, and both readings
-   *  have rows. */
-  workingPane?: boolean;
-  /** The axis and terminator rows answer only while a transform is LIVE. */
-  transformModal?: boolean;
-  /** The action `resolveKey(probe)` must return. */
-  action: KeyAction["kind"];
-}
+export { MATERIAL_SHORTCUTS, SHORTCUTS, STORYBOARD_SHORTCUTS };
+export type { ShortcutRow } from "../../state/shortcuts.js";
 
-const probe = (
-  key: string,
-  m: { shift?: boolean; ctrl?: boolean; alt?: boolean; code?: string } = {},
-): KeyEventLike => ({
-  key,
-  shiftKey: m.shift === true,
-  altKey: m.alt === true,
-  ctrlKey: m.ctrl === true,
-  metaKey: false,
-  ...(m.code === undefined ? {} : { code: m.code }),
-});
+/**
+ * The material graph's keys, listed apart from the four groups below.
+ *
+ * They live in their own table because they answer a DIFFERENT question of the
+ * keymap: every row here resolves with `materialGraph: true`, meaning the key
+ * landed inside the node canvas, and the same combo means something else
+ * everywhere else (P is a tool, ⌘G groups layers). Folding them into
+ * `SHORTCUTS` would make that table's own test walk them through the wrong
+ * context and assert the wrong answer.
+ *
+ * Typed as a `ShortcutGroup` rather than left a bare literal: a section heading
+ * that no row can carry is a heading over an empty list.
+ */
+const MATERIAL_GROUP: ShortcutGroup = "Material nodes";
 
-export const SHORTCUTS: readonly ShortcutRow[] = [
-  { group: "View", combo: "Space", does: "Play / pause", probe: probe(" "), action: "playToggle" },
-  { group: "View", combo: "← →", does: "Step one frame (nothing selected)", probe: probe("ArrowRight"), action: "step" },
-  { group: "View", combo: "1 / 2 / 3", does: "Working / split / camera view", probe: probe("1"), action: "stageLayout" },
-  { group: "View", combo: "[", does: "Hide / show the left panel", probe: probe("["), action: "togglePanel" },
-  { group: "View", combo: "]", does: "Hide / show the right panel", probe: probe("]"), action: "togglePanel" },
-  { group: "View", combo: ".", does: "Hide every panel", probe: probe("."), action: "togglePanel" },
-  { group: "View", combo: "\\", does: "Fit the timeline", probe: probe("\\"), action: "fitTimeline" },
-  { group: "View", combo: "⌘+ / ⌘−", does: "Zoom in / out", probe: probe("=", { ctrl: true }), action: "zoom" },
-  { group: "View", combo: "⌘0", does: "Zoom to 100%", probe: probe("0", { ctrl: true }), action: "zoomReset" },
-  { group: "View", combo: "Home", does: "Fit the active pane", probe: probe("Home"), action: "fit" },
-  { group: "View", combo: "⇧C", does: "Fit the active pane (Blender's frame all)", probe: probe("c", { shift: true }), action: "fit" },
-  { group: "View", combo: "Z", does: "Cycle working-pane shading (solid / wire / material / rendered)", probe: probe("z"), action: "shadingCycle" },
-  { group: "View", combo: "⇧Z", does: "Wireframe on / off", probe: probe("z", { shift: true }), action: "wireframeToggle" },
+/** The board's keys, apart for the same reason: every row resolves only with
+ *  `storyboard: true`, and Delete means "remove a layer" outside it. */
+const STORYBOARD_GROUP: ShortcutGroup = "Storyboard";
 
-  { group: "Working view", combo: "G", does: "Grab the selection — move it with the mouse, click to place", probe: probe("g"), workingPane: true, hasSelection: true, action: "modalStart" },
-  { group: "Working view", combo: "R", does: "Rotate the selection (roll)", probe: probe("r"), workingPane: true, hasSelection: true, action: "modalStart" },
-  { group: "Working view", combo: "S", does: "Scale the selection", probe: probe("s"), workingPane: true, hasSelection: true, action: "modalStart" },
-  { group: "Working view", combo: "G / S", does: "Nothing selected: move / zoom the camera", probe: probe("g"), workingPane: true, action: "modalStart" },
-  { group: "Working view", combo: "X / Y / Z", does: "Constrain the transform to an axis (again clears; G+Z = depth)", probe: probe("x"), transformModal: true, action: "modalAxis" },
-  { group: "Working view", combo: "0-9", does: "Type an exact value: G X 200 Enter", probe: probe("2"), transformModal: true, action: "modalNumber" },
-  // `hasSelection` because R is the one that needs it: the CAMERA has no modal
-  // roll, so switching to rotate on a camera transform would arm one that could
-  // never emit.
-  { group: "Working view", combo: "G / R / S", does: "Switch transform without leaving the gesture", probe: probe("r"), transformModal: true, hasSelection: true, action: "modalStart" },
-  { group: "Working view", combo: "Enter", does: "Confirm the transform (or click)", probe: probe("Enter"), transformModal: true, action: "modalConfirm" },
-  { group: "Working view", combo: "Esc", does: "Cancel the transform (or right-click)", probe: probe("Escape"), transformModal: true, action: "modalCancel" },
-  { group: "Working view", combo: "Num1 / 3 / 7", does: "Front / right / top view (⌘ = the opposite)", probe: probe("1", { code: "Numpad1" }), action: "workingViewPreset" },
-  { group: "Working view", combo: "Num0", does: "Camera view, and back again", probe: probe("0", { code: "Numpad0" }), action: "stageLayout" },
-  { group: "Working view", combo: "Num.", does: "Frame the selection", probe: probe(".", { code: "NumpadDecimal" }), action: "fitSelection" },
-  { group: "Working view", combo: "Num2 / 4 / 6 / 8", does: "Orbit 15°; Num9 looks from the opposite side", probe: probe("4", { code: "Numpad4" }), action: "orbitStep" },
-  { group: "Working view", combo: "Num5", does: "Orthographic / perspective", probe: probe("5", { code: "Numpad5" }), action: "toggleWorkingOrtho" },
-  { group: "Working view", combo: "Num/", does: "Go inside the selection, and back out", probe: probe("/", { code: "NumpadDivide" }), action: "toggleIsolation" },
-  { group: "Working view", combo: "Num+ / Num−", does: "Zoom the active pane", probe: probe("+", { code: "NumpadAdd" }), action: "zoom" },
+/** The groups the main table prints, in the manual's own order: every one
+ *  `state/shortcuts.ts` declares, less the two that own a table and a section
+ *  of their own. Derived rather than re-listed, so a new group is one edit
+ *  there and not a second one here that nobody remembers to make. */
+const GROUPS = SHORTCUT_GROUPS.filter(
+  (group) => group !== MATERIAL_GROUP && group !== STORYBOARD_GROUP,
+);
 
-  { group: "Edit", combo: "Arrows", does: "Nudge selection 1 px (⇧ = 10)", probe: probe("ArrowRight"), hasSelection: true, action: "nudge" },
-  { group: "Edit", combo: "⌘Z", does: "Undo", probe: probe("z", { ctrl: true }), action: "undo" },
-  { group: "Edit", combo: "⌘⇧Z", does: "Redo", probe: probe("z", { ctrl: true, shift: true }), action: "redo" },
-  { group: "Edit", combo: "⌘S", does: "Save", probe: probe("s", { ctrl: true }), action: "save" },
-  { group: "Edit", combo: "⌘D", does: "Duplicate", probe: probe("d", { ctrl: true }), action: "duplicate" },
-  { group: "Edit", combo: "⌘A / A", does: "Select all, in the scope you are in", probe: probe("a", { ctrl: true }), action: "selectAll" },
-  { group: "Edit", combo: "⌥A", does: "Deselect all", probe: probe("a", { alt: true }), action: "deselect" },
-  { group: "Edit", combo: "B", does: "Box select with the next drag", probe: probe("b"), action: "boxSelect" },
-  { group: "Edit", combo: "⇧D", does: "Duplicate", probe: probe("d", { shift: true }), action: "duplicate" },
-  { group: "Edit", combo: "Esc", does: "Deselect", probe: probe("Escape"), action: "deselect" },
-  { group: "Edit", combo: "Del", does: "Delete selection", probe: probe("Delete"), action: "deleteSelection" },
-  { group: "Edit", combo: "⌘G", does: "Group", probe: probe("g", { ctrl: true }), action: "group" },
-  { group: "Edit", combo: "⌘⇧G", does: "Ungroup", probe: probe("g", { ctrl: true, shift: true }), action: "ungroup" },
-  { group: "Edit", combo: "⌥L", does: "Lock / unlock", probe: probe("l", { alt: true }), action: "toggleLock" },
-  { group: "Edit", combo: "H", does: "Hide the selection", probe: probe("h"), action: "setHidden" },
-  { group: "Edit", combo: "⇧H", does: "Hide everything else", probe: probe("h", { shift: true }), action: "setHidden" },
-  { group: "Edit", combo: "⌥H", does: "Show everything again", probe: probe("h", { alt: true }), action: "setHidden" },
-  { group: "Edit", combo: "⌥G / ⌥R", does: "Clear the position / the rotation", probe: probe("g", { alt: true }), action: "clearTransform" },
-  { group: "Edit", combo: "Enter", does: "Edit inside the selection", probe: probe("Enter"), hasSelection: true, action: "enterIsolation" },
-  { group: "Edit", combo: "Esc", does: "Come back out one level", probe: probe("Escape"), isolation: true, action: "exitIsolation" },
-  { group: "Edit", combo: "Enter", does: "Finish the path you are drawing", probe: probe("Enter"), penActive: true, action: "penCommit" },
-  { group: "Edit", combo: "Esc", does: "Throw away the path you are drawing", probe: probe("Escape"), penActive: true, action: "penAbandon" },
+/** The three layouts by name and key, out of the one table the toolbar chips,
+ *  the View menu and the refusal sentences all read. Renaming the third from
+ *  "Frame" to "Camera" (founder order, 2026-09-05) left this manual teaching
+ *  the withdrawn word for exactly as long as it took someone to read it,
+ *  because prose was the one surface with nothing tying it to the control. */
+const WORKING = layoutSpec("working");
+const SPLIT = layoutSpec("split");
+const CAMERA = layoutSpec("camera");
 
-  { group: "Animate & camera", combo: "⇧A", does: "Animate mode — edits become blocks", probe: probe("a", { shift: true }), action: "animateToggle" },
-  { group: "Animate & camera", combo: "M", does: "Drop a marker at the playhead", probe: probe("m"), action: "addMarker" },
-  { group: "Animate & camera", combo: "⌥C", does: "Point the camera at the working view", probe: probe("c", { alt: true }), action: "alignCameraToView" },
-  { group: "Animate & camera", combo: "⌘B", does: "Split layer at the playhead", probe: probe("b", { ctrl: true }), action: "splitAtPlayhead" },
-  { group: "Animate & camera", combo: "⌘E", does: "Export video", probe: probe("e", { ctrl: true }), action: "openExport" },
-];
+/** The two words the switch shows, from the same table the control and the
+ *  View menu read. The paragraph below taught "Video (4)" as a literal, which
+ *  is a rebind away from being wrong in the one place an author looks first. */
+const EDIT = VIEW_MODE_SPECS.edit;
+const VIDEO = VIEW_MODE_SPECS.video;
 
-const GROUPS = ["View", "Working view", "Edit", "Animate & camera"] as const;
-
-/** The sentences a first session needs, in the order a session meets them.
- *  Mouse gestures live HERE and not in the shortcut table below, because every
- *  row of that table is walked through the real keymap by its test — a row for
- *  a gesture no key produces would have to carry a fake event to pass. */
+/** The first-run guide: the few sentences a first session needs, in the order
+ *  it meets them. Everything else is in the key tables below. Mouse gestures
+ *  live HERE and not in those tables, because every row there is walked
+ *  through the real keymap by its test, and a gesture has no key to walk. */
 const BASICS: readonly string[] = [
-  "Camera view: scroll to pan, ctrl+scroll to zoom at the pointer, space-drag to pan.",
-  "Working view (1 / 2): drag empty space or middle-drag to orbit, scroll to dolly, space-drag or ⇧middle-drag to pan. Click a layer to select it, then G / R / S transform it Blender-style; the panels tuck away while you work.",
-  "Working view aids: a ground grid under the frame that coarsens as you pull back, three coloured world axes (X red, Y green, Z blue) through the canvas centre, and an axis ball top-right — click an end to look down that axis.",
-  "Right-click a layer, on the stage or in the outline, for duplicate, hide, lock, isolate, delete — and on a model, a material.",
-  "Models: the outline shows each one's triangle count, and tints it once the scene gets heavy enough to feel it. Give a model a surface with right-click → Apply material; a toon model also grows a sun handle you can drag to aim its key.",
-  "Double-click a layer to go INSIDE it: the working pane frames that subtree flat and head-on and everything else dims. Orbit, pan or dolly and the camera is yours; Home puts it back head-on. A blue bar over the pane says you are inside; Esc backs out one level, or click a crumb in the left panel.",
-  "Drag arms (red/green/blue) sit on the selection, or on the CAMERA when nothing is selected — the same subject G and S pick. Z moves a layer in depth; on the camera it dollies.",
-  "Header zoom, ⌘+ / ⌘− and ⇧C all act on the pane you last clicked. ⇧Z is the wireframe toggle.",
-  "Draw: arm a tool in the top bar, then drag on the stage. Text takes a click.",
-  "Animate: toggle ⇧A, then edit — the change becomes a block ending at the playhead.",
-  "Camera: use the timeline's + shot button for a move, or in the working view (1) drag the yellow frustum's edge to pan, its apex to zoom, or its arms for one axis at a time.",
-  "Audio: drop a file on the timeline's audio lane. Markers ride their clip.",
-  "Everything exports exactly as previewed — same engine, same frames.",
+  `${EDIT.label} is where you build. ${VIDEO.label} (${VIDEO.key}) is the finished picture. Space plays it, and a click on anything brings ${EDIT.label} back.`,
+  `${EDIT.label} has three views: ${CAMERA.title} (${CAMERA.key}) is the shot's picture, where you draw. ${WORKING.title} (${WORKING.key}) is free to look around: drag to orbit, scroll to dolly. ${SPLIT.title} (${SPLIT.key}) is both.`,
+  "Draw: pick a tool in the footer under the picture (on the Storyboard, the rail beside the frame), then drag on the stage. Text takes a click, then type.",
+  "Double-click a layer to go inside it. Esc backs out. Right-click a layer for more.",
+  "Animate: turn on ⇧A, then change something. Edits write keyframes at the playhead.",
 ];
 
-export function HelpSection() {
+/**
+ * The manual itself, CONTROLLED, and opened from ONE surface: the app menu's
+ * Help row (AppMenu owns the `open` bit).
+ *
+ * There used to be a second door, a "?" in the left column's foot. The Studio
+ * redesign dropped it: a 28px glyph over the foot's end was a second Help
+ * entry the founder questioned, and the foot itself is gone now. The menu row
+ * is reachable with no document open, which was the "?"'s whole reason to live
+ * in the column rather than in the Files panel.
+ *
+ * `Dialog` returns null while closed, so this copy of `McpSection` does not
+ * probe health until the author asks for Help. The top bar's Agent chip owns
+ * a separate Project-targeted copy.
+ */
+export function HelpDialog(props: { open: boolean; onClose(): void }) {
+  const close = props.onClose;
   return (
-    <details className="help-section" data-testid="help-section">
-      <summary className="file-section-label help-summary">Manual</summary>
-
-      <ul className="help-basics">
-        {BASICS.map((line) => (
-          <li key={line}>{line}</li>
-        ))}
-      </ul>
-
-      <div className="file-section-label">Tools</div>
-      <ul className="help-rows">
-        {SHOT_TOOLS.map((tool) => {
-          const spec = specOf(tool);
-          return (
-            <li key={tool} className="help-row">
-              <span>{spec.label}</span>
-              {spec.key !== null && (
-                <kbd>{`${spec.shift === true ? "⇧" : ""}${spec.key.toUpperCase()}`}</kbd>
-              )}
-            </li>
-          );
-        })}
-      </ul>
+    <Dialog
+      open={props.open}
+      title="Help"
+      // The shared dialog is a hard 320px, which is a confirm's width: the
+      // shortcut rows are a combo and a sentence on one line, and at 320
+      // every one of them wraps.
+      className="shot-help-dialog"
+      onClose={close}
+      actions={
+        <button type="button" className="btn" onClick={close}>
+          Close
+        </button>
+      }
+    >
+      <div className="help-manual" data-testid="help-manual">
+        <ul className="help-basics">
+          {/* In this machine's spelling, like every table row below: the
+              lines name keys in the house glyphs ("⇧1", "⇧A"). */}
+          {BASICS.map((line) => (
+            <li key={line}>{formatCombo(line)}</li>
+          ))}
+        </ul>
 
-      {GROUPS.map((group) => (
-        <div key={group}>
-          <div className="file-section-label">{group}</div>
-          <ul className="help-rows">
-            {SHORTCUTS.filter((row) => row.group === group).map((row) => (
-              // Keyed on the combo AND what it does: Esc and Enter each mean
-              // three things now, depending on what is open, and every one of
-              // them is a row.
-              <li key={`${row.combo}:${row.does}`} className="help-row">
-                <span>{row.does}</span>
-                <kbd>{row.combo}</kbd>
+        <div className="file-section-label">Tools</div>
+        <ul className="help-rows">
+          {SHOT_TOOLS.map((tool) => {
+            const spec = specOf(tool);
+            return (
+              <li key={tool} className="help-row">
+                <span>{spec.label}</span>
+                {spec.key !== null && <kbd>{toolKey(tool)}</kbd>}
               </li>
-            ))}
-          </ul>
+            );
+          })}
+        </ul>
+
+        <div className="help-groups">
+          {GROUPS.map((group) => (
+            <div key={group}>
+              <div className="file-section-label">{group}</div>
+              <ul className="help-rows">
+                {SHORTCUTS.filter((row) => row.group === group).map((row) => (
+                  // Keyed on the combo AND what it does: Esc and Enter each
+                  // mean three things now, depending on what is open, and
+                  // every one of them is a row.
+                  <li key={`${row.combo}:${row.does}`} className="help-row">
+                    <span>{row.does}</span>
+                    <kbd>{comboOf(row)}</kbd>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+          <div>
+            <div className="file-section-label">{MATERIAL_GROUP}</div>
+            <ul className="help-rows">
+              {MATERIAL_SHORTCUTS.map((row) => (
+                <li key={`${row.combo}:${row.does}`} className="help-row">
+                  <span>{row.does}</span>
+                  <kbd>{comboOf(row)}</kbd>
+                </li>
+              ))}
+            </ul>
+          </div>
+          <div>
+            <div className="file-section-label">{STORYBOARD_GROUP}</div>
+            <ul className="help-rows">
+              {STORYBOARD_SHORTCUTS.map((row) => (
+                <li key={`${row.combo}:${row.does}`} className="help-row">
+                  <span>{row.does}</span>
+                  <kbd>{comboOf(row)}</kbd>
+                </li>
+              ))}
+            </ul>
+          </div>
         </div>
-      ))}
-      <p className="help-note">⌘ is Ctrl on Windows and Linux.</p>
-    </details>
+        {/* The "⌘ is Ctrl on Windows and Linux" footnote used to live here and
+              is gone on purpose: every row above is printed through
+              `comboOf`, so on Windows and Linux the table already says Ctrl.
+              A footnote translating a glyph the reader is not being shown is
+              worse than no footnote. */}
+        <p className="help-note">
+          The Material nodes keys act only inside the node canvas, and the
+          Storyboard keys only while the Storyboard is open.
+        </p>
+
+        {/* The general doorway, repeated from the Agent chip so setup stays
+              findable from Help. */}
+        <McpSection />
+      </div>
+    </Dialog>
   );
 }