@dailies-studio/shot-editor 0.1.0

package/src/tools.ts

@@ -0,0 +1,181 @@
+// THE TOOL TABLE. One literal, and every list, union and lookup below is
+// DERIVED from it — so adding a tool without answering every question the table
+// asks is a compile error rather than an empty button or a dead key.
+//
+// It lives beside the bridge contract rather than in either half, because both
+// halves read it: the chrome renders the dock from it, and the stage keys its
+// cursor and its gesture routing off the same rows.
+//
+// ── `animate` IS DELIBERATELY NOT A TOOL ────────────────────────────────
+//
+// In Raylight you can be in Animate mode WHILE holding Select: it changes what
+// an edit MEANS, not what a drag DOES. As a member of this union every arm of
+// every switch would have to answer "and what does select do while animate is
+// armed?", which has no answer. It is `animateMode: boolean`, toggled by ⇧A,
+// and it is the one bit that decides whether a gesture writes base or authors a
+// block.
+//
+// ── THE `shift` FIELD, WHICH THE 2D LANE'S TABLE DOES NOT HAVE ──────────
+//
+// Raylight binds `L` to line and `⇧L` to arrow. So the key lane cannot be "a
+// bare letter arms a tool" — it has to be "a letter PLUS whether shift was
+// held", and the shift bit belongs in the table with the letter rather than in
+// a special case beside it.
+
+/** Every tool that changes what a canvas press does. */
+export type ShotTool =
+  | "select"
+  | "move"
+  | "text"
+  | "image"
+  | "rect"
+  | "ellipse"
+  | "line"
+  | "arrow"
+  | "path";
+
+export interface ToolSpec {
+  label: string;
+  /**
+   * The letter that arms it, lower case, or null for a tool with no binding.
+   *
+   * ONE PLACE. `toolForKey` is the only reader, and the keymap consults nothing
+   * else for a bare letter — so a tool cannot be bound here and to something
+   * else somewhere in a switch.
+   */
+  key: string | null;
+  /** Does the binding require SHIFT? `L` is line and `⇧L` is arrow. */
+  shift?: true;
+  /** "dock" is the toolbar's own row; "flyout" is reached through the shape
+   *  button. Six buttons in a row is a row; ten is a different object. */
+  surface: "dock" | "flyout";
+  /** Does a press-drag-release with this tool INSERT a layer? False for select
+   *  (which picks) and move (which drags). */
+  draws: boolean;
+  /** The CSS cursor while this tool is armed. A row here rather than a default
+   *  in the stage means a new tool has to answer "what does the pointer look
+   *  like" in the same place it answers "what letter arms it". */
+  cursor: string;
+}
+
+/**
+ * The tools, in DOCK ORDER. `Object.keys` on an object literal is insertion
+ * order for string keys, and every list below derives its order from this one.
+ * The flyout rows sit beside the button they fly out of.
+ */
+export const TOOL_SPECS = {
+  select: { label: "Select", key: "v", surface: "dock", draws: false, cursor: "default" },
+  // The flat-plane move. It is a TOOL and not a modifier because the plane it
+  // unprojects onto is the whole difference between it and select — see
+  // stage/interactions/move.ts.
+  move: { label: "Move", key: "g", surface: "dock", draws: false, cursor: "move" },
+  // `draws: true` and a text cursor are not in tension: the box IS drawn, and
+  // what the author gets for it is somewhere to type.
+  text: { label: "Text", key: "t", surface: "dock", draws: true, cursor: "text" },
+  // "Frame" and not "Image": the box the author draws takes an image OR a
+  // video, and the server's sniff of the file they pick decides which layer
+  // kind it becomes. The tool ID stays `image` because it is a persisted
+  // vocabulary — the bridge, the keymap and the insert map all key on it — and
+  // renaming a wire word to fix a button's caption is a schema break for a
+  // string nobody sees.
+  image: { label: "Frame", key: "i", surface: "dock", draws: true, cursor: "crosshair" },
+  rect: { label: "Rect", key: "r", surface: "dock", draws: true, cursor: "crosshair" },
+  ellipse: { label: "Ellipse", key: "o", surface: "flyout", draws: true, cursor: "crosshair" },
+  line: { label: "Line", key: "l", surface: "flyout", draws: true, cursor: "crosshair" },
+  arrow: { label: "Arrow", key: "l", shift: true, surface: "flyout", draws: true, cursor: "crosshair" },
+  // The pen takes no drag at all and still shows the crosshair: what the cursor
+  // announces is "a press here authors geometry", which is true of every press
+  // it takes, not "a drag is about to start".
+  path: { label: "Pen", key: "p", surface: "dock", draws: false, cursor: "crosshair" },
+  // NO `cut` ROW. It armed a crosshair and did nothing at all: the stage's
+  // pointer lane has no branch for it, and ⌘B is the real split-at-playhead.
+  // Deleting it is compile-checked by the `satisfies` below, and it frees `C`.
+} as const satisfies Record<ShotTool, ToolSpec>;
+
+/** Every tool, in dock order. The cast is the one place this file asserts what
+ *  `satisfies` has already proved: the literal above is the only writer of the
+ *  object and its key set IS `ShotTool`, which `Object.keys` cannot say because
+ *  its return type is `string[]` for every object in TypeScript. */
+export const SHOT_TOOLS = Object.keys(TOOL_SPECS) as readonly ShotTool[];
+
+/**
+ * One row, seen as a `ToolSpec` rather than as its own literal type.
+ *
+ * `as const satisfies` narrows every row to exactly the keys it wrote, so
+ * `TOOL_SPECS.select.shift` is a type ERROR rather than `undefined` — which is
+ * excellent for the table and useless for anything iterating it. This is the
+ * one widening, and it is in one place.
+ */
+export function specOf(tool: ShotTool): ToolSpec {
+  return TOOL_SPECS[tool];
+}
+
+/** The tools that insert on drag-release, DERIVED so the union and the flag can
+ *  never disagree. Adding a `draws: true` row widens this union, which is what
+ *  makes the draw lane's insert map fail to compile until the new tool has an
+ *  answer there. That is the whole point of the table. */
+export type DrawTool = {
+  [K in ShotTool]: (typeof TOOL_SPECS)[K]["draws"] extends true ? K : never;
+}[ShotTool];
+
+/**
+ * Every tool that ends up CREATING A LAYER, which is the draw tools plus the
+ * pen.
+ *
+ * The pen is not `draws: true` and must not become it: that flag answers "does
+ * a press-drag-release insert a layer", the stage's pointer lane forks on it,
+ * and the pen's answer is no — it commits across N presses on Enter or a
+ * double-click. What the two DO share is the far end of the wire, where an
+ * insert map has to answer for each of them, so that map is keyed on this and a
+ * new creating tool fails to compile until it has an entry.
+ */
+export type InsertTool = DrawTool | "path";
+
+/** The tools with a button in the dock's own row. The dock's icon map is keyed
+ *  on it, so a new dock tool without a glyph is a compile error. */
+export type DockTool = {
+  [K in ShotTool]: (typeof TOOL_SPECS)[K]["surface"] extends "dock" ? K : never;
+}[ShotTool];
+
+/** The other surface. Derived so the two partition the union by construction. */
+export type FlyoutTool = {
+  [K in ShotTool]: (typeof TOOL_SPECS)[K]["surface"] extends "flyout" ? K : never;
+}[ShotTool];
+
+/** A type predicate rather than a set-membership test: a `ReadonlySet<string>`
+ *  narrows nothing, so the draw lane would have to cast its tool back on the
+ *  far side of a check that could not see it. */
+export function isDrawTool(tool: ShotTool): tool is DrawTool {
+  return TOOL_SPECS[tool].draws;
+}
+
+const isDockTool = (tool: ShotTool): tool is DockTool => TOOL_SPECS[tool].surface === "dock";
+const isFlyoutTool = (tool: ShotTool): tool is FlyoutTool => TOOL_SPECS[tool].surface === "flyout";
+
+export const DOCK_TOOLS: readonly DockTool[] = SHOT_TOOLS.filter(isDockTool);
+export const FLYOUT_TOOLS: readonly FlyoutTool[] = SHOT_TOOLS.filter(isFlyoutTool);
+
+/** Keyed on `${letter}${shift ? "+" : ""}` so `l` and `l+` are different
+ *  entries rather than one entry with a branch beside it. */
+const TOOL_BY_KEY: ReadonlyMap<string, ShotTool> = new Map(
+  SHOT_TOOLS.flatMap((tool): Array<[string, ShotTool]> => {
+    const spec = specOf(tool);
+    return spec.key === null ? [] : [[bindingOf(spec.key, spec.shift === true), tool]];
+  }),
+);
+
+function bindingOf(key: string, shift: boolean): string {
+  return `${key.toLowerCase()}${shift ? "+" : ""}`;
+}
+
+/**
+ * THE KEYMAP'S WHOLE TOOL LANE: the tool this letter arms, or null when no tool
+ * claims it (which is how the transport and zoom keys keep theirs).
+ *
+ * Case and the shift bit are folded HERE as well as at the call site, so a
+ * caller that forgot cannot get a different answer from the one the table
+ * gives.
+ */
+export function toolForKey(key: string, shift = false): ShotTool | null {
+  return TOOL_BY_KEY.get(bindingOf(key, shift)) ?? null;
+}