@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/InspectorFooter.tsx

@@ -0,0 +1,91 @@
+// THE INSPECTOR'S STATUS FOOTER, pinned under the scroller: the container the
+// panel is inside, as two facts. Its place on the left ("Shot 03",
+// "Component", "4 shots"), its length and rate on the right ("540 frames ·
+// 30 fps").
+//
+// ── THE CONTAINER, NEVER THE SELECTION ─────────────────────────────────────
+//
+// The head above names the subject, and the subject changes with every click.
+// The footer names what the subject lives IN, which is the one thing that is
+// true for every selection the panel can hold: a rect inside shot 3 is still in
+// shot 3, a layer picked inside a definition is still on the definition's
+// clock. So the ladder is the context bits alone, in `InspectorPanel`'s order
+// for containers: an open definition, then the entered shot, then the project.
+// The Storyboard falls through to the project, because the board plans the
+// whole film and the project's length and rate are its facts too.
+//
+// ── NO FOOTER IS BETTER THAN A WRONG ONE ───────────────────────────────────
+//
+// In Components the subject is a component, not the document, so no document
+// fact describes it: the footer there is the component's own
+// (`ComponentFooter`, "Made by you · private · vN"). With no document open
+// there is nothing to state, and it renders nothing rather than a placeholder.
+//
+// The rate is `fpsLabel`, the Tool footer's own wording, and the length is in
+// frames because frames are what the Project section and the Shot section
+// type into.
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { defDurationFrames, docDurationFramesCached } from "@dailies-studio/shot/doc";
+import { useShotEditor } from "../../state/context.js";
+import { shotNumberOf } from "../../state/storyboardModel.js";
+import { workspaceOf } from "../../state/workspace.js";
+import { fpsLabel } from "../toolbar/ToolFooter.js";
+import { ComponentFooter } from "../studio/ComponentSidePanel.js";
+
+const frames = (n: number): string => `${n} ${n === 1 ? "frame" : "frames"}`;
+
+/**
+ * The footer's two lines for one context, or null where no fact is true.
+ * Pure, so the ladder is tested without a store.
+ */
+export function inspectorFooterFacts(
+  doc: Doc3D | null,
+  enteredScene: string | null,
+  editingDef: string | null,
+  board = false,
+): { subject: string; meta: string } | null {
+  if (doc === null) return null;
+  const rate = `${fpsLabel(doc.fps)} fps`;
+  if (editingDef !== null) {
+    const def = doc.components?.[editingDef];
+    if (def === undefined) return null;
+    return { subject: "Component", meta: `${frames(defDurationFrames(def))} · ${rate}` };
+  }
+  if (enteredScene !== null) {
+    const scene = doc.scenesById[enteredScene];
+    const index = doc.scenes.indexOf(enteredScene);
+    if (scene === undefined || index === -1) return null;
+    // On the board a Shot is numbered as its strip card is (`shotNumberOf`,
+    // planned shots included), so the footer and the card agree.
+    const number = (board ? shotNumberOf(doc, enteredScene) : null) ?? String(index + 1).padStart(2, "0");
+    return {
+      subject: `Shot ${number}`,
+      meta: `${frames(scene.durationFrames)} · ${rate}`,
+    };
+  }
+  const count = doc.scenes.length;
+  return {
+    subject: `${count} ${count === 1 ? "shot" : "shots"}`,
+    meta: `${frames(docDurationFramesCached(doc))} · ${rate}`,
+  };
+}
+
+export function InspectorFooter() {
+  // Stable references and primitives only. The facts are derived in render,
+  // which runs on a document edit or a context change and never on a frame.
+  const doc = useShotEditor((s) => s.doc);
+  const enteredScene = useShotEditor((s) => s.enteredScene);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  const board = useShotEditor((s) => s.storyboardOpen);
+  const code = useShotEditor((s) => workspaceOf(s) === "components");
+  // Components states whose component it is and which version is live.
+  if (code) return <ComponentFooter />;
+  const facts = inspectorFooterFacts(doc, enteredScene, editingDef, board);
+  if (facts === null) return null;
+  return (
+    <footer className="inspector-footer" data-testid="inspector-footer">
+      <span className="inspector-footer-subject">{facts.subject}</span>
+      <span className="inspector-footer-meta">{facts.meta}</span>
+    </footer>
+  );
+}

package/src/panels/inspector/InspectorHead.tsx

@@ -0,0 +1,425 @@
+// WHAT THIS PANEL IS DESCRIBING, said once at the top.
+//
+// ── THE PANEL KNEW ITS SUBJECT AND NEVER NAMED IT ───────────────────────
+//
+// The rail resolves a subject on every render (`InspectorPanel`'s ladder) and
+// then mounts a stack of sections whose TITLES are the only thing on screen.
+// So the author read "Shot / Camera / Effects" in one context and "Transform /
+// Appearance" in another, with nothing saying that the first set belongs to a
+// shot and the second to the rectangle they clicked. Two subjects looked like
+// two unrelated panels, and the one case where it actually matters (a layer
+// selected INSIDE a component definition, where the sections are identical to
+// the scene's) had no tell at all.
+//
+// ── THE LADDER IS `InspectorPanel`'s, NOT A SECOND OPINION ──────────────
+//
+// Every branch below answers the same question the panel's own fork answers,
+// in the same order, so the head can never name something the sections are not
+// describing. In particular the SELECTION WINS OVER `editingDef`: with a layer
+// picked inside a definition the panel mounts the layer's design sections, so
+// the head says "Text", not "Component". The definition is the subject only
+// when nothing inside it is selected, which is exactly when
+// `DefinitionSection` is what renders.
+//
+// ── THE NAME IS THE RENAME ──────────────────────────────────────────────
+//
+// For the subjects that own a rename verb (a single layer, the open shot and
+// the Project) the name IS the field. That is what let the Shot section drop its Name
+// row: a heading and a "Name" row two lines below it, both holding the same
+// string, is the panel restating itself. The other subjects render a span,
+// because a title that looks editable and is not is worse than a plain one.
+import { useRef, useState } from "react";
+import type { KeyboardEvent, ReactElement } from "react";
+import { homeOf, maskTargetOf, visibleStills } from "@dailies-studio/shot/doc";
+import {
+  CAMERA_ICON,
+  COMPONENT_ICON,
+  DOCK_TOOL_ICONS,
+  MASK_ICON,
+  MOTION_NOTE_ICON,
+  RECORD_ICON,
+  REFERENCE_ICONS,
+  SCENE_ICON,
+  STORYBOARD_ICON,
+  TRANSITION_ICON,
+  iconFor,
+  isComponentGlyph,
+} from "../../icons.js";
+import { wordFor } from "../../layerWords.js";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { boardSubjectOf, cardKindOf, isReferenceId, shotNameOf, stillNameOf } from "../../state/storyboardModel.js";
+import { useSelectedLayers } from "./useDocWrite.js";
+import { componentEditOpen, workspaceOf } from "../../state/workspace.js";
+import { framesToSeconds } from "@dailies-studio/engine";
+import { formatDuration, timecode } from "../timeline/model.js";
+
+/** The Studio face's selection: none (see `studioFace`). */
+const NO_LAYERS: ReturnType<typeof useSelectedLayers> = [];
+
+interface Rename {
+  ariaLabel: string;
+  /** The subject's identity, and the field's remount key. See `RenameField`. */
+  id: string;
+  commit(next: string): void;
+}
+
+interface Subject {
+  /** The stable half, shown above the name: which set of sections is about to
+   *  be read. Not drawn on the shot's head, whose `meta` line says it. */
+  kind: string;
+  /** THE SHOT'S HEAD ONLY: a fact line under the name ("Shot 03 · 0:18"), and
+   *  the glyph on a tile instead of bare. The open shot is the container the
+   *  author works inside, so its head reads as a place with a size rather than
+   *  as one more object kind. Null on every other subject. */
+  meta: string | null;
+  /** Null for a subject with no name of its own. A marker is a frame, a label
+   *  and a colour, and the label is a field in the section below. */
+  name: string | null;
+  /** NULL FOR A SUBJECT NO GLYPH DESCRIBES. Every other one here is a thing on
+   *  the stage or on the timeline and has a glyph the outliner already uses for
+   *  it; the Project is the panel's own frame and had to borrow one. See the
+   *  Project branch. */
+  icon: ReactElement | null;
+  /** Paints the glyph in the accent, the outliner's rule for the component
+   *  family. */
+  component: boolean;
+  /** Null where no store verb renames this subject. */
+  rename: Rename | null;
+}
+
+/**
+ * The name, in place, committing on blur and on Enter.
+ *
+ * NOT `TextField`, which solves exactly this and is used for every other text
+ * value in the rail. It hard-codes `text-input` onto its input, and that class
+ * is a control pill: a `--control-h` box, a filled ground and a focus ring.
+ * The head's name is a TITLE that happens to be editable, which is why
+ * `.insp-head-rename` is transparent until it is pointed at, and the two rule
+ * sets would fight over height and focus paint. One bare input is cheaper than
+ * a second styling escape hatch on a shared widget.
+ *
+ * The two traps `TextField` documents are real and are handled the same way:
+ * Enter BLURS and does not also commit (the blur handler is the same closure,
+ * so committing here as well pushes two history entries for one keystroke and
+ * the first Ctrl-Z appears to do nothing), and Escape sets a ref the blur
+ * commit reads, because `setDraft(null)` has only been queued by the time the
+ * synchronous blur runs.
+ */
+function RenameField(props: { value: string; ariaLabel: string; onCommit: (next: string) => void }) {
+  const [draft, setDraft] = useState<string | null>(null);
+  const ref = useRef<HTMLInputElement | null>(null);
+  const cancelling = useRef(false);
+
+  const commit = (): void => {
+    if (cancelling.current) {
+      cancelling.current = false;
+      setDraft(null);
+      return;
+    }
+    if (draft === null) return;
+    setDraft(null);
+    if (draft !== props.value) props.onCommit(draft);
+  };
+
+  const onKeyDown = (e: KeyboardEvent<HTMLInputElement>): void => {
+    if (e.key === "Enter") ref.current?.blur();
+    else if (e.key === "Escape") {
+      cancelling.current = true;
+      ref.current?.blur();
+    }
+  };
+
+  return (
+    <input
+      ref={ref}
+      className="insp-head-rename"
+      type="text"
+      value={draft ?? props.value}
+      aria-label={props.ariaLabel}
+      onChange={(e) => setDraft(e.target.value)}
+      onBlur={commit}
+      onKeyDown={onKeyDown}
+    />
+  );
+}
+
+export function InspectorHead() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  /** Inside a shot. NOT `sceneId !== null`, which is never null with a document
+   *  open: this is the context bit, written only by enter/leave. */
+  const inShot = useShotEditor((s) => s.enteredScene !== null);
+  const selectedMarker = useShotEditor((s) => s.selectedMarker);
+  const focused = useShotEditor((s) => s.selectedMove);
+  const storyboardOpen = useShotEditor((s) => s.storyboardOpen);
+  const storyboardSelection = useShotEditor((s) => s.storyboardSelection);
+  // Components' Preview tab names the definition whatever is selected inside
+  // it: `InspectorPanel`'s rule, so the head and the stack agree.
+  const studioFace = useShotEditor(
+    (s) => workspaceOf(s) === "components" && s.codeComponent === null && !componentEditOpen(s),
+  );
+  const selectedLayers = useSelectedLayers();
+  const layers = studioFace ? NO_LAYERS : selectedLayers;
+  if (doc === null) return null;
+
+  // RESOLVED, not merely selected, for both focused objects, the same rule
+  // `InspectorPanel` applies to each. A selection pointing at a marker or a
+  // camera move that an undo removed would otherwise name a subject with
+  // nothing behind it, while the panel below had already fallen through to the
+  // next branch.
+  const marker =
+    selectedMarker !== null && (doc.markers ?? []).some((m) => m.id === selectedMarker);
+  const cameraShot =
+    focused !== null && focused.sceneId === sceneId
+      ? (doc.scenesById[focused.sceneId]?.shots.find((s) => s.id === focused.shotId) ?? null)
+      : null;
+  const scene = sceneId === null ? undefined : doc.scenesById[sceneId];
+  const one = layers.length === 1 ? layers[0] : undefined;
+
+  const subject = ((): Subject => {
+    // THE BOARD FIRST, `InspectorPanel`'s ladder: while it is open nothing on
+    // screen is a layer, a marker or a camera move.
+    if (storyboardOpen) {
+      const only = storyboardSelection.length === 1 ? storyboardSelection[0]! : null;
+      if (only !== null && isReferenceId(only)) {
+        const item = doc.resources?.references?.find((r) => r.id === only);
+        if (item !== undefined) {
+          return {
+            kind: "Reference",
+            name: item.label,
+            icon: REFERENCE_ICONS[cardKindOf(item, doc.assets)],
+            component: item.type === "component",
+            meta: null,
+            rename: {
+              ariaLabel: "Reference name",
+              id: `sb|${item.id}`,
+              commit: (label) => {
+                const trimmed = label.trim();
+                if (trimmed.length > 0) store.updateReference(item.id, { label: trimmed });
+              },
+            },
+          };
+        }
+      }
+      // NO PLANNED-SHOT BRANCH. One planned shot picked is the Plan panel's
+      // (`boardRightPanel`), whose head names and renames it (`PartName`), so
+      // this panel never shows one alone.
+      const board = boardSubjectOf(doc, storyboardSelection);
+      if (board !== null && board.kind === "cut") {
+        // Named by the two Shots either side, and saved on the first:
+        // `StoryboardCutSection` edits the outgoing Shot's transition.
+        const a = shotNameOf(doc, board.sceneId);
+        return {
+          kind: "Transition",
+          name: `Between ${a} and ${shotNameOf(doc, board.cut.incoming)}`,
+          icon: TRANSITION_ICON,
+          component: false,
+          meta: `Transition · saved on ${a}`,
+          rename: null,
+        };
+      }
+      if (board !== null && board.kind === "gap") {
+        // The move between two stills, named by them and placed by their
+        // times.
+        const stills = visibleStills(doc.scenesById[board.sceneId]!);
+        return {
+          kind: "Move",
+          name: `${stillNameOf(stills, board.gap.from)} → ${stillNameOf(stills, board.gap.to)}`,
+          icon: MOTION_NOTE_ICON,
+          component: false,
+          meta: `Move · ${shotNameOf(doc, board.sceneId)} · ${timecode(board.gap.from, doc.fps)} to ${timecode(board.gap.to, doc.fps)}`,
+          rename: null,
+        };
+      }
+      if (storyboardSelection.length > 1) {
+        return {
+          kind: "Selection",
+          name: `${storyboardSelection.length} items`,
+          icon: DOCK_TOOL_ICONS.select,
+          component: false,
+          meta: null,
+          rename: null,
+        };
+      }
+      return {
+        kind: "Storyboard",
+        name: doc.title ?? doc.name,
+        icon: STORYBOARD_ICON,
+        component: false,
+        meta: null,
+        rename: null,
+      };
+    }
+    if (marker && !storyboardOpen) {
+      // A dot in a ring is the transport grammar for a mark, and it is the one
+      // glyph in the set that reads as a point on a timeline rather than as a
+      // thing on the stage. A marker owns no icon of its own because it is not
+      // a layer kind.
+      return { kind: "Marker", name: null, icon: RECORD_ICON, component: false, meta: null, rename: null };
+    }
+    // BELOW THE SELECTION, for the same reason `editingDef` is. A camera move
+    // is only ever the panel's FOCUSED-OBJECT SLOT (`ShotSection` sits above
+    // the design stack, it does not replace it), and clicking a camera bar
+    // leaves the layer selection alone: the camera row never calls `select`,
+    // and `selectMove` clears only the marker, the keyframes and the audio.
+    // So with a rect selected and a camera bar focused, the head said "Camera
+    // move" over nine sections describing the rect. The marker branch above
+    // stays first because that one DOES replace the panel.
+    if (cameraShot !== null && layers.length === 0) {
+      return {
+        kind: "Camera move",
+        name: cameraShot.label,
+        icon: CAMERA_ICON,
+        component: false,
+        meta: null,
+        rename: null,
+      };
+    }
+    if (one !== undefined) {
+      // A MASK SAYS SO (gap 7, Paper page 25): "Ellipse · mask" on the mask,
+      // "Group · masked by Circle" on the group that holds one.
+      const home = homeOf(doc, editingDef ?? sceneId ?? "");
+      const maskId = home === null ? null : maskTargetOf(home, one.id);
+      const maskWord =
+        maskId === null ? "" : maskId === one.id ? " · mask" : ` · masked by ${home!.layersById[maskId]!.label}`;
+      const kind = wordFor(one) + maskWord;
+      return {
+        kind,
+        name: one.label,
+        icon: maskId === null ? iconFor(one) : MASK_ICON,
+        component: maskId === null && isComponentGlyph(one),
+        meta: null,
+        rename: {
+          ariaLabel: "Layer name",
+          // The CONTAINER is in the key as well as the layer id: layer ids are
+          // scene-local, so the same id names a different layer after the
+          // playhead crosses a cut or the author enters a definition. Without
+          // it a draft typed here would commit into whatever layer inherited
+          // the id. Same reasoning as the panel's `subjectKey`.
+          id: `${editingDef ?? sceneId ?? "-"}|${one.id}`,
+          commit: (label) => store.renameLayer(one.id, label),
+        },
+      };
+    }
+    if (layers.length > 1) {
+      // The pointer, which is what "a selection" means everywhere else in this
+      // chrome. The layers do not agree on a kind, so no kind glyph can stand
+      // for them.
+      return {
+        kind: "Selection",
+        name: `${layers.length} layers`,
+        icon: DOCK_TOOL_ICONS.select,
+        component: false,
+        meta: null,
+        rename: null,
+      };
+    }
+    if (editingDef !== null) {
+      const def = doc.components?.[editingDef];
+      // No rename here even though `renameComponent` exists: a definition's
+      // name is the name codegen emits, so it is edited where its other
+      // published facts are, in the section below.
+      return {
+        kind: "Component",
+        name: def?.name ?? editingDef,
+        icon: COMPONENT_ICON,
+        component: true,
+        meta: null,
+        rename: null,
+      };
+    }
+    if (inShot && scene !== undefined && sceneId !== null) {
+      // The number is the shot's place in `doc.scenes` and the length is
+      // `formatDuration`, the same two strings the Tool footer and the left column's
+      // shot rows print, so one shot is never numbered or timed two ways.
+      const number = String(doc.scenes.indexOf(sceneId) + 1).padStart(2, "0");
+      return {
+        kind: "Shot",
+        name: scene.name,
+        icon: SCENE_ICON,
+        component: false,
+        meta: `Shot ${number} · ${formatDuration(framesToSeconds(scene.durationFrames, doc.fps))}`,
+        rename: {
+          ariaLabel: "Shot name",
+          id: sceneId,
+          commit: (name) => store.renameScene(sceneId, name),
+        },
+      };
+    }
+    // The scene context. `title` is optional through v13, so the generated
+    // component name is the fallback every other surface already falls back to.
+    //
+    // ── AND NO GLYPH, BECAUSE THE BORROWED ONE READ AS A BUTTON ─────────
+    //
+    // This was `kindIcon("group")` on the argument that a Project is the one
+    // thing here made OF the others. The glyph for that is two offset
+    // rectangles, which is also the universal glyph for DUPLICATE — sitting at
+    // 16px immediately left of the project's name, at the top of a panel whose
+    // every other small square is a control, it was read as a copy button and
+    // reported as one.
+    //
+    // No other icon is right either: the clapperboard is a single shot's and
+    // reusing it names the wrong altitude, and inventing a glyph for the one
+    // subject that is not on the stage teaches a symbol that appears nowhere
+    // else. The word PROJECT is already on the line, above the name, saying the same
+    // thing without the ambiguity — so the head runs without one here.
+    return {
+      kind: "Project",
+      name: doc.title ?? doc.name,
+      icon: null,
+      component: false,
+      meta: null,
+      // The title only: `doc.name` is the generated component's name, and
+      // SceneDocSection's Component row is its one writer.
+      rename: {
+        ariaLabel: "Project title",
+        id: "project",
+        commit: (title) => store.setProjectTitle(title),
+      },
+    };
+  })();
+
+  const name =
+    subject.name === null ? null : subject.rename === null ? (
+      // The title carries the full string, because the name is the one thing
+      // here that ellipsises and a truncated title with no way to read it is
+      // the defect this head exists to stop repeating.
+      <span className="insp-head-name" title={subject.name}>
+        {subject.name}
+      </span>
+    ) : (
+      // KEYED ON THE SUBJECT so the draft dies with it. The head itself sits
+      // outside the panel's subject-keyed sections on purpose (InspectorPanel
+      // keys each section `${subjectKey}:${id}`; the head must not replay its
+      // entrance on every selection change), so this is where the
+      // "a draft must never commit into the next subject" rule is kept:
+      // crossing a cut mid-rename remounts the field and drops the text
+      // instead of writing shot A's name into shot B.
+      <RenameField
+        key={subject.rename.id}
+        value={subject.name}
+        ariaLabel={subject.rename.ariaLabel}
+        onCommit={subject.rename.commit}
+      />
+    );
+  const shotHead = subject.meta !== null;
+
+  return (
+    <div className={`insp-head${shotHead ? " is-shot" : ""}`} data-testid="insp-head">
+      {subject.icon === null ? null : (
+        <span
+          className={`insp-head-icon${shotHead ? " is-tile" : ""}${subject.component ? " is-component" : ""}`}
+        >
+          {subject.icon}
+        </span>
+      )}
+      <div className="insp-head-text">
+        {shotHead ? null : <span className="insp-head-kind">{subject.kind}</span>}
+        {name}
+        {shotHead ? <span className="insp-head-meta">{subject.meta}</span> : null}
+      </div>
+    </div>
+  );
+}