@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/storyboard/StillThumbs.tsx

@@ -0,0 +1,162 @@
+// THE BOARD'S STILL PICTURES, for the shot cards, the Comments panel's Frame
+// threads and every sketch picture (`useSketchThumbs`, which `MiniSketch`
+// shows once drawn): one `createStillThumbs` queue while it is active
+// (state/stillThumbs.ts), shared through context, so a still shown in two
+// places is drawn once.
+//
+// MOUNTED FOR THE WHOLE SESSION, ACTIVE ON THE BOARD AND FOR THE BRIEF. App
+// wraps the shell in it, because the strip and the inspector are different
+// shell children and the shell must never remount. `active`
+// (`stillThumbsActive`) makes the queue when the board opens, or when Studio's
+// right column shows the Brief, and disposes it when neither does. In Studio
+// the Brief's sketches are then the only pictures asked for: the one other
+// reader there, the Comments panel's Frame threads, shares the Brief's column.
+// So Studio pays for one draw per sketch of the entered Shot's plan, and
+// nothing while the Brief is closed.
+//
+// The provider owns the queue's life. It is made in an effect, not in render,
+// so StrictMode's second mount gets a live queue rather than a disposed one,
+// and it is disposed on unmount, which revokes every object URL it made.
+//
+// A CODE SAVE REDRAWS what it reaches. The store has no "saved" event, so the
+// provider watches each code file's status move from "saving" to "idle", the
+// one write `saveCodeFile` makes on success, and hands those paths to
+// `codeSaved`.
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { previewBindingOf } from "@dailies-studio/shot/doc";
+import { useStore } from "../../state/context.js";
+import { createStillThumbs } from "../../state/stillThumbs.js";
+import { boardRightPanel } from "../../state/workspace.js";
+import type { StillThumb, StillThumbs, StillThumbsDeps } from "../../state/stillThumbs.js";
+
+/** The queue, and a counter bumped on each change to what it answers. */
+const ThumbsContext = createContext<{ thumbs: StillThumbs; version: number } | null>(null);
+
+/** Whether the still queue runs (App's `active`): on the board, and off it
+ *  while the right column shows the Brief, whose sketches it draws. */
+export function stillThumbsActive(s: Parameters<typeof boardRightPanel>[0]): boolean {
+  return s.storyboardOpen || boardRightPanel(s) === "brief";
+}
+
+export function StillThumbsProvider({
+  children,
+  options,
+  active = true,
+}: {
+  children: ReactNode;
+  /** Whether the queue exists. False answers null to every reader. */
+  active?: boolean;
+  /** The queue's seams, for tests: a stub stage, timers, object URLs. Read
+   *  once, when the queue is made. */
+  options?: Omit<StillThumbsDeps, "store">;
+}) {
+  const store = useStore();
+  const [thumbs, setThumbs] = useState<StillThumbs | null>(null);
+  const [version, setVersion] = useState(0);
+  // `options` is read once by design: a queue is not rebuilt for a new object.
+  const [seams] = useState(options);
+
+  useEffect(() => {
+    if (!active) return;
+    const made = createStillThumbs({
+      // A sketch's code components bind by `contractBinding`'s rule
+      // (ComponentStage.tsx, which the shot board's Play uses), restated so
+      // this shell-wide provider does not load the stage preview.
+      sketchBinding: (id) => {
+        const state = store.getState();
+        const contract = state.contracts[id];
+        const availability = state.library.find((row) => row.id === id)?.contractAvailability ?? "inferred";
+        return contract === undefined ? undefined : previewBindingOf({ availability, contract });
+      },
+      loadContracts: async (ids) => {
+        if (!store.getState().libraryLoaded) await store.refreshLibrary();
+        await Promise.all(ids.map((id) => store.loadContract(id)));
+      },
+      ...seams,
+      store,
+    });
+    const unlisten = made.subscribe(() => setVersion((n) => n + 1));
+    let files = store.getState().codeFiles;
+    // Cold: a save is never a transport tick.
+    const unwatch = store.subscribeCold(() => {
+      const next = store.getState().codeFiles;
+      if (next === files) return;
+      const saved = Object.keys(next).filter((rel) => files[rel]?.status === "saving" && next[rel]!.status === "idle");
+      files = next;
+      if (saved.length > 0) made.codeSaved(saved);
+    });
+    setThumbs(made);
+    return () => {
+      unwatch();
+      unlisten();
+      made.dispose();
+      setThumbs(null);
+    };
+  }, [store, seams, active]);
+
+  const value = useMemo(() => (thumbs === null ? null : { thumbs, version }), [thumbs, version]);
+  return <ThumbsContext.Provider value={value}>{children}</ThumbsContext.Provider>;
+}
+
+/** The picture of `sceneId` at Shot-local `frame`, queueing its draw. Null
+ *  outside a provider, before its queue is made, or for a Shot that is gone. */
+export function useStillThumb(sceneId: string, frame: number): StillThumb | null {
+  const context = useContext(ThumbsContext);
+  const version = context?.version;
+  // `version` re-asks: the queue changed its answer. The body must READ it,
+  // because the React Compiler keys the memo on what the body reads, not on the
+  // listed deps, and the queue object itself never changes. Keyed on `thumbs`
+  // alone, the stills stayed pending forever (stillThumbsCompiled.test.ts).
+  return useMemo(
+    () => (version === undefined ? null : context!.thumbs.thumb(sceneId, frame)),
+    [context, version, sceneId, frame],
+  );
+}
+
+/** The stage-drawn pictures of `sketchIds` (all of one part), by sketch id,
+ *  queueing each one's draw. Each is null outside a provider, before its
+ *  queue is made, or for a sketch that is gone; `MiniSketch` keeps its DOM
+ *  drawing until one is ready. */
+export function useSketchThumbs(partId: string, sketchIds: readonly string[]): ReadonlyMap<string, StillThumb | null> {
+  const context = useContext(ThumbsContext);
+  // READ, for the React Compiler's reason above: the compiled cache re-asks
+  // the queue when `version` moves. No manual memo: asking is cheap, and the
+  // ids arrive as a fresh array each render.
+  const version = context?.version;
+  const pictures = new Map<string, StillThumb | null>();
+  for (const id of sketchIds) pictures.set(id, version === undefined || context === null ? null : context.thumbs.sketch(partId, id));
+  return pictures;
+}
+
+/**
+ * ONE STILL, drawn: the picture when there is one (an older one while its
+ * redraw waits), else a ground that says why. Sized by the caller: the
+ * strip's cards draw it at 92x52.
+ */
+export function StillPicture({
+  sceneId,
+  frame,
+  width,
+  height,
+  className,
+}: {
+  sceneId: string;
+  frame: number;
+  width: number;
+  height: number;
+  className: string;
+}) {
+  const thumb = useStillThumb(sceneId, frame);
+  const url = thumb?.url;
+  return (
+    <span
+      className={className}
+      style={{ width, height }}
+      data-status={thumb?.status ?? "pending"}
+      title={thumb?.status === "failed" ? `No picture: ${thumb.message}` : undefined}
+    >
+      {url !== undefined && <img src={url} alt="" width={width} height={height} draggable={false} />}
+    </span>
+  );
+}

package/src/panels/storyboard/StoryboardView.tsx

@@ -0,0 +1,79 @@
+// THE STORYBOARD MODE: the Project's planning board, in the docked frame.
+//
+// ONE CANVAS, FULL WIDTH (S1). The board fills the docked grid's centre cell
+// from edge to edge (BoardCanvas): no left rail, no panel bar, no strip and no
+// stage. The top bar stays, and the right column opens only while
+// `boardRightPanel` names an occupant (the component sheet, the inspector for
+// a card, comments, the agent).
+//
+// The drop dialog (BoardDropDialog) rides along: files dropped or pasted on
+// the board open it.
+//
+// A SHOT'S BOARD (`storyboardPlan`, `shotBoardOf`) takes the same cell in the
+// whole board's place: one shot's sketches (shotboard/ShotBoard.tsx).
+//
+// ONLY IN ITS OWN WORKSPACE. `workspaceOf` is the one precedence for which
+// mode is on screen, so the board portals (and binds its clipboard) only when
+// it is the answer: two modes can never fill one cell.
+import { useEffect, useState } from "react";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { shotBoardOf, workspaceOf } from "../../state/workspace.js";
+import { InCell } from "../stage/cellSlots.js";
+import { BoardCanvas } from "./BoardCanvas.js";
+import { BoardDropDialog } from "./BoardDropDialog.js";
+import { ShotBoard } from "./shotboard/ShotBoard.js";
+import { bindBoardClipboard } from "./boardClipboard.js";
+
+export function StoryboardView() {
+  const store = useStore();
+  const active = useShotEditor((s) => workspaceOf(s) === "storyboard");
+  const docId = useShotEditor((s) => s.doc?.id ?? null);
+  const plan = useShotEditor(shotBoardOf);
+  // STATE, NOT A REF: the view lands through a portal, and on a boot with
+  // `?storyboard=1` the cells register a commit after the board opens. The
+  // focus below has to run when the element arrives, not when `active` flips.
+  const [view, setView] = useState<HTMLElement | null>(null);
+
+  // ── FOCUS THE VIEW ON THE WAY IN ────────────────────────────────────────
+  //
+  // Opening a mode should not leave the keyboard on whatever control the
+  // author last pressed in the chrome around it.
+  useEffect(() => {
+    if (active) view?.focus({ preventScroll: true });
+  }, [active, view]);
+
+  // ── THE CLIPBOARD, ON THE DOCUMENT ──────────────────────────────────────
+  //
+  // DOM handlers rather than keybindings, because `clipboardData.files`
+  // exists only on a real `paste` event; binding ⌘V through `handleKey` would
+  // `preventDefault` the keydown and take away pasting a screenshot onto the
+  // board. `storyboardClipboard`'s arm returns false for exactly that reason;
+  // see keymap.ts.
+  //
+  // ON THE DOCUMENT AND NOT ON THE VIEW. A clipboard event targets
+  // `document.activeElement`, and the right column sits beside the board
+  // rather than inside it, so the moment an author touched a control over
+  // there the board's copy, cut and paste would go dead with nothing saying
+  // why. The stage iframe's document binds the same handlers
+  // (`bindBoardClipboard`, StagePanel).
+  //
+  // DECLARED ABOVE THE EARLY RETURN, because hooks must be. It closes over
+  // `store`, which is stable.
+  useEffect(() => {
+    if (!active) return;
+    const aborter = new AbortController();
+    bindBoardClipboard(document, store, aborter.signal);
+    return () => aborter.abort();
+  }, [active, store]);
+
+  if (!active || docId === null) return null;
+
+  return (
+    <>
+      <InCell name="centre">
+        {plan === null ? <BoardCanvas rootRef={setView} /> : <ShotBoard key={plan} partId={plan} rootRef={setView} />}
+      </InCell>
+      <BoardDropDialog />
+    </>
+  );
+}