@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/library/LibraryPreviewPanel.tsx

@@ -0,0 +1,349 @@
+// The Library's right column (the selected item, larger, its action and Pin) and
+// the centre column's EXPANDED PREVIEW, which replaces the catalog while it is
+// open. A sound pack's column is `LibrarySoundPanel`: a pack is a list of
+// files to audition one at a time, not one thing to look at.
+//
+// THE PROPS ARE THE CONTRACT. The browser owns selection, the expanded flag
+// and the one-add-at-a-time rule (a double click on a card adds too, so the
+// guard and the add's error cannot live here); this panel renders the
+// selected row and asks.
+//
+// PREVIEWING NEVER INSTALLS. A shipped component draws live only once it is
+// in this Project's registry (`installedAs` names a row of `s.library`): the
+// stage and the harness can only load a registry id, and installing as a side
+// effect of LOOKING would write files into the author's source tree. Before
+// the Add, the expanded preview is the item's thumb and a sentence that says
+// so. The live picture is the inspector's: a second shot stage
+// (`ComponentStage`, framed as a Shot frames it). Components are React Three
+// Fiber, so a dom host shows its thumb and says it is not supported.
+//
+// A SHOT'S ACTION IS ITS OWN PROJECT. A shot has no layer to place, so its
+// primary is "Use as new Project" (`claimLibraryShot`, the pinned card's Claim
+// as Project): the shot copied into a Project of its own and opened. Pin to
+// board stays the second action, as it is a component's.
+//
+// PLAY AND STOP, NOT A SCRUBBER. `ComponentStage` loops on its own rAF clock
+// and exposes no seek and no position, so the transport is the one control it
+// can honour: play loops, stop holds the first frame (a card with
+// `frame: 0`). A scrubber would claim a position nothing reports.
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { ReactNode } from "react";
+import type { Value } from "@dailies-studio/engine";
+import type { ReferenceItem3D } from "@dailies-studio/shot/doc";
+import type { LibraryItem } from "../../api.js";
+import { ADD_ICON, CHEVRON_DOWN_ICON, CHEVRON_LEFT_ICON, COLLAPSE_ICON, FIT_ICON, LIBRARY_CATEGORY_ICONS, PLAY_ICON, STOP_ICON } from "../../icons.js";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { placeInShotRefusal } from "../../state/store.js";
+import { instanceHostRefusal } from "../../state/storyboardModel.js";
+import { ComponentStage } from "../storyboard/ComponentStage.js";
+import { formatDuration } from "../timeline/model.js";
+import { DOM_NOT_SUPPORTED } from "../../state/workspace.js";
+import { displayNameOf, kindOf } from "./libraryModel.js";
+import { LibrarySoundPanel } from "./LibrarySoundPanel.js";
+
+type ComponentCard = Extract<ReferenceItem3D, { type: "component" }>;
+
+const NO_PROPS: Record<string, Value> = {};
+
+/** One item of a kind, for the metadata row and "About this …". */
+const KIND_NOUN: Record<ReturnType<typeof kindOf>, string> = {
+  component: "Component",
+  blueprint: "Blueprint",
+  material: "Material",
+  shot: "Shot",
+  images: "Image pack",
+  sounds: "Sound pack",
+};
+
+/** Only a component has motion to open larger: every other kind is a still. */
+export const canExpand = (item: LibraryItem): boolean => kindOf(item) === "component";
+
+export interface LibraryPreviewPanelProps {
+  /** The selected catalog row, or null before the author picks one. */
+  item: LibraryItem | null;
+  /** Where a PIN lands, as printed: "Project storyboard", the whole film. */
+  destination: string;
+  /** Cards on this Project's board that cite `item` (0 when none, or no item). */
+  onBoard: number;
+  /** False with no Project open: the catalog still browses, nothing adds. */
+  canAdd: boolean;
+  /** An add is in flight somewhere on the surface; every Add waits for it. */
+  adding: boolean;
+  /** ADD (D2): place a component in the open Shot, selected. It installs
+   *  first. Only a component has the button. */
+  onAdd: () => void;
+  /** USE AS NEW PROJECT: copy a shot into a new Project and open it. Only a
+   *  shot has the button. */
+  onClaim: () => void;
+  /** PIN TO INSPIRATION: the item as a board card for the agent. The one
+   *  action of a material, an image pack or a blueprint, and the second of a
+   *  component and a shot. Not for a sound pack, which pins one sound at a
+   *  time. */
+  onPin: () => void;
+  /** Why the last add of THIS item failed, printed under its button. The
+   *  shell's error strip is under the dialog, so without this a refused add
+   *  would only re-enable the button. */
+  error: string | null;
+  /** The centre column is showing this item's expanded preview. */
+  expanded: boolean;
+  onExpand: (open: boolean) => void;
+}
+
+export function LibraryPreviewPanel(props: LibraryPreviewPanelProps) {
+  const { item, destination, onBoard, canAdd, adding, onAdd, onClaim, onPin, error, expanded, onExpand } = props;
+  const [more, setMore] = useState(false);
+  // Why Add would refuse (no Shot open, a definition open), and the Shot it
+  // lands in: strings, so these selectors allocate nothing.
+  const shotRefusal = useShotEditor((s) => placeInShotRefusal(s));
+  // The board enters no Shot: one the Studio left open behind it is not where
+  // an Add lands (Add is refused there, `placeInShotRefusal`).
+  const shotName = useShotEditor((s) =>
+    s.storyboardOpen || s.enteredScene === null ? null : (s.doc?.scenesById[s.enteredScene]?.name ?? null),
+  );
+  const boardOpen = useShotEditor((s) => s.storyboardOpen);
+  // FOCUS COMES BACK HERE ON COLLAPSE. The expanded view's two closes unmount
+  // with it, so focus falls to <body>; put it on the button that opens the
+  // view again. Only when it fell: a rail pick also collapses, and the rail
+  // row keeps its focus.
+  const expandRef = useRef<HTMLButtonElement>(null);
+  const wasExpanded = useRef(expanded);
+  useEffect(() => {
+    const collapsed = wasExpanded.current && !expanded;
+    wasExpanded.current = expanded;
+    if (collapsed && (document.activeElement === null || document.activeElement === document.body)) expandRef.current?.focus();
+  }, [expanded]);
+  if (item === null) {
+    return (
+      <aside className="library-preview" aria-label="Preview">
+        <p className="library-preview-empty">Click an item to preview it.</p>
+      </aside>
+    );
+  }
+  const kind = kindOf(item);
+  const name = displayNameOf(item);
+  // Only a three host can be a layer, so a dom component's Add says why up front.
+  const placeRefusal = item.host === "three" ? shotRefusal : instanceHostRefusal(item.host);
+  if (kind === "sounds") {
+    return (
+      <LibrarySoundPanel
+        key={item.id}
+        item={item}
+        canAdd={canAdd}
+        adding={adding}
+      />
+    );
+  }
+  const opens = canExpand(item);
+  // The kinds whose primary is their own button, so Pin is the outlined second.
+  const primary = kind === "component" || kind === "shot";
+  const where = kind === "component" ? (shotName ?? "no Shot open") : kind === "shot" ? "a new Project" : destination;
+  return (
+    <aside className="library-preview" aria-label={`Preview: ${name}`} data-testid="library-preview">
+      <header className="library-preview-head">
+        <h2>{expanded ? `About this ${KIND_NOUN[kind].toLowerCase()}` : "Preview"}</h2>
+        {opens && !expanded ? (
+          <button ref={expandRef} type="button" className="btn is-ghost is-icon" aria-label="Open a larger preview" title="Open a larger preview" onClick={() => onExpand(true)}>
+            {FIT_ICON}
+          </button>
+        ) : null}
+      </header>
+      {expanded ? null : (
+        <div className="library-preview-thumb">
+          <LibraryArt item={item} />
+          {opens ? (
+            <button type="button" className="library-preview-play" aria-label={`Play ${name}`} title="Play it larger" onClick={() => onExpand(true)}>
+              {PLAY_ICON}
+            </button>
+          ) : null}
+        </div>
+      )}
+      <div className="library-preview-purpose">
+        <h3 className="library-preview-name">{name}</h3>
+        {item.description === undefined ? null : <p className="library-preview-note">{item.description}</p>}
+      </div>
+      <div className="library-preview-add">
+        <p className="library-preview-destination">
+          <span data-testid="library-destination">Destination: {where}</span>
+          {onBoard > 0 ? <span data-testid="library-preview-on-board">On the board ×{onBoard}</span> : null}
+        </p>
+        {kind === "component" ? (
+          <button
+            type="button"
+            className="btn is-primary is-lg"
+            data-testid="library-add"
+            disabled={!canAdd || adding}
+            aria-disabled={placeRefusal !== null || undefined}
+            title={
+              !canAdd
+                ? "Open a Project to add library items."
+                : (placeRefusal ?? `Install into this Project and place it in ${shotName ?? "the open Shot"}. Undo removes the layer; the installed files stay.`)
+            }
+            onClick={() => {
+              if (placeRefusal === null) onAdd();
+            }}
+          >
+            {ADD_ICON}
+            {adding ? "Adding…" : "Add to shot"}
+          </button>
+        ) : null}
+        {kind === "shot" ? (
+          <button
+            type="button"
+            className="btn is-primary is-lg"
+            data-testid="library-claim"
+            disabled={!canAdd || adding}
+            title={canAdd ? "Copy this shot into a new Project of its own and open it. This Project stays as it is." : "Open a Project to add library items."}
+            onClick={onClaim}
+          >
+            {ADD_ICON}
+            Use as new Project
+          </button>
+        ) : null}
+        <button
+          type="button"
+          className={primary ? "btn is-outline is-lg" : "btn is-primary is-lg"}
+          data-testid="library-pin"
+          disabled={!canAdd || adding}
+          title={canAdd ? `Pin a card to ${destination}. The agent reads it when it builds.${boardOpen ? "" : " Opens the storyboard."}` : "Open a Project to add library items."}
+          onClick={onPin}
+        >
+          {primary ? null : ADD_ICON}
+          Pin to board
+        </button>
+        {error === null ? null : (
+          <p className="library-preview-error" role="alert" data-testid="library-add-error">
+            {error}
+          </p>
+        )}
+        <p className="library-preview-hint">
+          {kind === "component"
+            ? "Add places it in the open Shot. Pin saves it for later."
+            : kind === "shot"
+              ? "Use as new Project copies it into a Project of its own and opens it. Pin saves it on this board for the agent."
+              : "This has no layer of its own. Pin it so the agent can use it."}
+        </p>
+      </div>
+      {item.useFor === undefined ? null : (
+        <section className="library-preview-usage" aria-label="Good for">
+          <h3>Good for</h3>
+          <p>{item.useFor}</p>
+        </section>
+      )}
+      {item.avoidFor === undefined ? null : (
+        <div className="library-preview-more">
+          <button type="button" aria-expanded={more} onClick={() => setMore((v) => !v)}>
+            More usage guidance
+            {CHEVRON_DOWN_ICON}
+          </button>
+          {more ? <p>Not for: {item.avoidFor}</p> : null}
+        </div>
+      )}
+      <footer className="library-preview-meta">
+        <span>
+          {KIND_NOUN[kind]}
+          {kind === "component" ? ` · ${item.host === "three" ? "3D" : "2D"}` : ""}
+        </span>
+        {item.version === undefined ? null : <span>v{item.version}</span>}
+      </footer>
+    </aside>
+  );
+}
+
+/** The item's thumb, or its category glyph on the well when it ships none. */
+function LibraryArt({ item }: { item: LibraryItem }) {
+  return item.thumb === undefined ? (
+    <span className="library-preview-placeholder" aria-hidden="true">
+      {LIBRARY_CATEGORY_ICONS[kindOf(item)]}
+    </span>
+  ) : (
+    <img className="library-preview-art" src={item.thumb} alt="" />
+  );
+}
+
+/**
+ * The centre column's larger preview of one component: the way back, the
+ * live picture (or the thumb and why), and play / stop. The browser mounts it
+ * in place of the catalog, so the rail and the right column stay put.
+ */
+// ponytail: Escape closes the whole Library, not just this view (the Dialog
+// owns the key); give the browser a keydown guard if authors expect a step back.
+export function LibraryExpandedPreview({ item, backTo, onClose }: { item: LibraryItem; backTo: string; onClose: () => void }) {
+  const store = useStore();
+  const name = displayNameOf(item);
+  const doc = useShotEditor((s) => s.doc);
+  const registryId = item.installedAs ?? null;
+  const row = useShotEditor((s) => (registryId === null ? undefined : s.library.find((r) => r.id === registryId)));
+  const contract = useShotEditor((s) => (registryId === null ? undefined : s.contracts[registryId]));
+  const [playing, setPlaying] = useState(true);
+  // The button that opened this view unmounted with the right column's thumb
+  // and head, so focus starts on the way back, not on <body>.
+  const backRef = useRef<HTMLButtonElement>(null);
+  useEffect(() => backRef.current?.focus(), []);
+  useEffect(() => {
+    if (registryId !== null && row?.host === "three") void store.loadContract(registryId);
+  }, [registryId, row?.host, store]);
+  // A STABLE CARD per play state: `ComponentStage` reloads its document when
+  // the card object changes, so a fresh literal per render would reload the
+  // stage on every store write.
+  const card = useMemo<ComponentCard | null>(
+    () =>
+      registryId === null
+        ? null
+        : { id: "ref_library_preview", type: "component", component: registryId, label: name, props: NO_PROPS, ...(playing ? {} : { frame: 0 }) },
+    [registryId, name, playing],
+  );
+  const live = doc !== null && card !== null && row?.host === "three";
+
+  let picture: ReactNode;
+  if (live && row !== undefined) {
+    picture = <ComponentStage doc={doc} item={card} contract={contract} availability={row.contractAvailability} lengthFrames={item.lengthFrames} />;
+  } else {
+    picture = (
+      <div className="library-expanded-still">
+        <LibraryArt item={item} />
+        <p>
+          {doc === null
+            ? "Open a Project to play this live."
+            : row?.host === "dom"
+              ? DOM_NOT_SUPPORTED
+              : "Add or pin it to play it live here. Previewing never installs it."}
+        </p>
+      </div>
+    );
+  }
+  const fps = doc === null ? 0 : doc.fps.num / doc.fps.den;
+
+  return (
+    <section className="library-expanded" aria-label={`Preview: ${name}`} data-testid="library-expanded">
+      <header className="library-expanded-head">
+        <div>
+          <button ref={backRef} type="button" className="library-expanded-back" onClick={onClose}>
+            {CHEVRON_LEFT_ICON}
+            Back to {backTo}
+          </button>
+          <h2>{name}</h2>
+        </div>
+        <button type="button" className="btn is-outline is-icon is-lg" aria-label="Close the larger preview" title="Close the larger preview" onClick={onClose}>
+          {COLLAPSE_ICON}
+        </button>
+      </header>
+      <div className="library-expanded-stage">{picture}</div>
+      {live ? (
+        <div className="library-expanded-transport">
+          <button
+            type="button"
+            className="library-preview-play"
+            aria-label={playing ? `Stop ${name}` : `Play ${name}`}
+            onClick={() => setPlaying((v) => !v)}
+          >
+            {playing ? STOP_ICON : PLAY_ICON}
+          </button>
+          {item.lengthFrames === undefined || !(fps > 0) ? null : (
+            <span className="library-expanded-length">Loops every {formatDuration(item.lengthFrames / fps)}</span>
+          )}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+

package/src/panels/library/LibraryRail.tsx

@@ -0,0 +1,84 @@
+// The Library's left column: the way back, the categories, and the Project an
+// Add lands in.
+//
+// THE BACK ROW IS THE CLOSE. The library has no Done button any more: the
+// author came from somewhere, and the row names it ("Back to <Shot>", or the
+// board, or the Project) so leaving says where it lands. Escape does the same
+// through `Dialog`.
+//
+// EACH ROW IS A BUTTON WITH `aria-pressed`, not a tab: the rows filter one
+// catalog column and own no panel of their own, so a tablist would promise a
+// tabpanel per row that does not exist.
+import type { ReactNode } from "react";
+import { CHEVRON_LEFT_ICON, LIBRARY_CATEGORY_ICONS } from "../../icons.js";
+import { CATEGORY_LABEL, LIBRARY_CATEGORIES, plural } from "./libraryModel.js";
+import type { LibraryCategory } from "./libraryModel.js";
+
+export function LibraryRail({
+  category,
+  counts,
+  onCategory,
+  backLabel,
+  onBack,
+  project,
+  onBoard,
+}: {
+  category: LibraryCategory;
+  counts: ReadonlyMap<LibraryCategory, number>;
+  onCategory: (category: LibraryCategory) => void;
+  /** "Back to Fold reel", "Back to storyboard", "Back to <Project>". */
+  backLabel: string;
+  onBack: () => void;
+  /** The open Project's display name, or null with none open. */
+  project: string | null;
+  /** Shipped items with at least one card on this Project's board. */
+  onBoard: number;
+}) {
+  let foot: ReactNode;
+  if (project === null) {
+    foot = (
+      <>
+        <span className="library-rail-project">No Project open</span>
+        <span>Open a Project to add library items.</span>
+      </>
+    );
+  } else {
+    foot = (
+      <>
+        <span className="library-rail-project">Project · {project}</span>
+        <span data-testid="library-on-board">{plural(onBoard, "library item")} on the storyboard</span>
+      </>
+    );
+  }
+  return (
+    <nav className="library-rail" aria-label="Library categories">
+      <button type="button" className="library-back" data-testid="library-back" onClick={onBack}>
+        {CHEVRON_LEFT_ICON}
+        <span>{backLabel}</span>
+      </button>
+      {/* The dialog's own title carries the accessible name "Library"; this
+          is its visible face, so the repeat is hidden from a reader. */}
+      <div className="library-rail-title">
+        <span aria-hidden="true">Library</span>
+        <span className="library-rail-sub">Pieces for your next shot</span>
+      </div>
+      <div className="library-rail-rows">
+        {LIBRARY_CATEGORIES.map((c) => (
+          <button
+            key={c}
+            type="button"
+            className="library-rail-row"
+            data-category={c}
+            aria-pressed={c === category}
+            onClick={() => onCategory(c)}
+          >
+            {LIBRARY_CATEGORY_ICONS[c]}
+            <span className="library-rail-label">{CATEGORY_LABEL[c]}</span>
+            {counts.has(c) ? <span className="library-rail-count">{counts.get(c)}</span> : null}
+          </button>
+        ))}
+      </div>
+      <div className="library-rail-foot">{foot}</div>
+    </nav>
+  );
+}