@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/studio/componentParts.tsx

@@ -0,0 +1,341 @@
+// The parts both Components tabs share (C1, C2, C7): the way back and the
+// breadcrumb in the canvas bar (whose "used in N places" opens Every use), the
+// Preview tab's transport, and the hooks the right panel and Every use read.
+import { useEffect, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { SegmentedControl } from "@dailies-studio/ui";
+import { framesToSeconds, secondsToFrame } from "@dailies-studio/engine";
+import type { Rational } from "@dailies-studio/engine";
+import { componentUsesOf } from "@dailies-studio/shot/doc";
+import * as api from "../../api.js";
+import type { ShotComponentBackground } from "../../bridgeTypes.js";
+import { CHEVRON_LEFT_ICON } from "../../icons.js";
+import { useShotEditor, useShotEditorHot, useStore } from "../../state/context.js";
+import { defClockFrames } from "../../state/types.js";
+import type { ComponentsOrigin, ComponentsSelection } from "../../state/types.js";
+import {
+  componentsSubject,
+  newPropKeys,
+  sameComponent,
+  shotLabel,
+  useByKey,
+  usesViewOf,
+  workspaceRowOf,
+} from "../../state/workspace.js";
+import { clock, formatDuration } from "../timeline/model.js";
+import { PlayButton } from "../timeline/PlayButton.js";
+
+const FALLBACK_FPS: Rational = { num: 30, den: 1 };
+
+/** The open component's workspace row, when the store has one for it. */
+export function useSubjectRow(): api.WorkspaceComponent | undefined {
+  const list = useShotEditor((s) => s.workspaceComponents);
+  const projectId = useShotEditor((s) => s.doc?.id);
+  const codeComponent = useShotEditor((s) => s.codeComponent);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  return useMemo(
+    () => workspaceRowOf(list, projectId, componentsSubject({ codeComponent, editingDef })),
+    [list, projectId, codeComponent, editingDef],
+  );
+}
+
+/** The subject's recorded versions, newest first, loaded again whenever its
+ *  workspace row moves to a new version. */
+export function useSubjectVersions(): readonly api.WorkspaceComponentVersionInfo[] | undefined {
+  const store = useStore();
+  const row = useSubjectRow();
+  const id = row?.id ?? null;
+  const version = row?.version ?? 0;
+  const versions = useShotEditor((s) => (id === null ? undefined : s.componentVersions[id]));
+  useEffect(() => {
+    if (id !== null) void store.loadComponentVersions(id);
+  }, [store, id, version]);
+  return versions;
+}
+
+/** The keys that were not in the previous version: the "New" badge's rows. */
+export function useNewPropKeys(keys: readonly string[]): string[] {
+  const versions = useSubjectVersions();
+  // Keyed on the names, not the array a caller may build per render.
+  const joined = keys.join(" ");
+  return useMemo(() => newPropKeys(joined === "" ? [] : joined.split(" "), versions), [joined, versions]);
+}
+
+/** The usage index's rows for the open component, across every Project the
+ *  caller may see, or null until it answers (or when the store does not
+ *  know the component yet). Read again when the component records a new
+ *  version, since a save is what rewrites the index. */
+export function useIndexedUses(): readonly api.IndexedComponentUse[] | null {
+  const row = useSubjectRow();
+  const [indexed, setIndexed] = useState<{ id: string; uses: api.IndexedComponentUse[] } | null>(null);
+  const id = row?.id ?? null;
+  const version = row?.version ?? 0;
+  useEffect(() => {
+    if (id === null) return;
+    let live = true;
+    api.workspaceComponentUses(id).then(
+      (uses) => {
+        if (live) setIndexed({ id, uses });
+      },
+      () => {
+        // No other Projects listed; this document's own uses stand.
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [id, version]);
+  return indexed !== null && indexed.id === id ? indexed.uses : null;
+}
+
+/** The index's uses in OTHER Projects. This document's own come from the
+ *  live document instead, which the index only sees at its last save. */
+export function useOtherProjectUses(): readonly api.IndexedComponentUse[] {
+  const indexed = useIndexedUses();
+  const projectId = useShotEditor((s) => s.doc?.id);
+  return useMemo(() => (indexed ?? []).filter((u) => u.projectId !== projectId), [indexed, projectId]);
+}
+
+/** How many places use the component: this document's own uses, live, plus
+ *  the usage index's uses in every other Project. */
+export function useUsedIn(sel: ComponentsSelection | null): number {
+  const doc = useShotEditor((s) => s.doc);
+  // Keyed on the id, not the selection object a caller may build per render.
+  const kind = sel?.kind ?? null;
+  const target = sel === null ? null : sel.kind === "studio" ? sel.def : sel.module;
+  const local = useMemo(() => {
+    if (doc === null || target === null) return 0;
+    return componentUsesOf(doc).filter((u) => (kind === "studio" ? u.def === target : u.component === target)).length;
+  }, [doc, kind, target]);
+  return local + useOtherProjectUses().length;
+}
+
+/** The Shot door this component came through (C7), while it is on screen:
+ *  null once the author picks another component. */
+export function useOriginOf(sel: ComponentsSelection | null): ComponentsOrigin | null {
+  return useShotEditor((s) =>
+    s.componentsOrigin !== null && sameComponent(s.componentsOrigin.sel, sel) ? s.componentsOrigin : null,
+  );
+}
+
+/**
+ * THE WAY BACK, first in every Components bar.
+ *
+ *   came from a Shot   "Back to Shot" (C7): that Shot, its frame and its
+ *                      selection, as the author left them (`backToShot`).
+ *                      Kept while they browse other components.
+ *   a component open   the chevron to All components (`openComponents`).
+ *   the home           the chevron out of Components (`leaveComponents`).
+ *
+ * `guard` asks before a code component's unsaved buffers go.
+ */
+export function ComponentsBack(props: { testId: string; guard: (then: () => void) => void }) {
+  const store = useStore();
+  const fromShot = useShotEditor((s) => s.componentsOrigin !== null);
+  const home = useShotEditor((s) => componentsSubject(s) === null);
+  if (fromShot) {
+    return (
+      <button
+        type="button"
+        className="btn components-back-to-shot"
+        data-testid="components-back-to-shot"
+        title="Back to the Shot, at the frame you left (Esc)"
+        onClick={() => props.guard(() => void store.backToShot())}
+      >
+        <span className="tool-icon" aria-hidden="true">
+          {CHEVRON_LEFT_ICON}
+        </span>
+        Back to Shot
+      </button>
+    );
+  }
+  const label = home ? "Leave Components" : "All components";
+  return (
+    <button
+      type="button"
+      className="back-chip component-studio-back"
+      data-testid={props.testId}
+      title={home ? "Leave Components (Esc)" : "All components"}
+      aria-label={label}
+      onClick={() => props.guard(() => (home ? store.leaveComponents() : void store.openComponents()))}
+    >
+      <span className="tool-icon" aria-hidden="true">
+        {CHEVRON_LEFT_ICON}
+      </span>
+    </button>
+  );
+}
+
+/** "All components / <name> · used in N places", the canvas bar's lead, or,
+ *  for the use a Shot door opened (C7), "03 Phone reveal / <name> · this use
+ *  · frame 00:01.08". `name` is a slot so the Studio's Edit tab can make it
+ *  the rename button. The Edit tabs drop the "All components /" root: the
+ *  chevron before it and the left column's back row already say where up
+ *  is, so the bar reads the chevron and the name. */
+export function ComponentCrumb(props: { sel: ComponentsSelection; name: ReactNode }) {
+  const origin = useOriginOf(props.sel);
+  if (origin !== null) return <OriginCrumb origin={origin} name={props.name} />;
+  return <SubjectCrumb sel={props.sel} name={props.name} />;
+}
+
+function OriginCrumb(props: { origin: ComponentsOrigin; name: ReactNode }) {
+  const doc = useShotEditor((s) => s.doc);
+  const fps = doc?.fps ?? FALLBACK_FPS;
+  const use = useMemo(() => (doc === null ? null : useByKey(doc, props.origin.useKey)), [doc, props.origin.useKey]);
+  const shot = doc !== null && use?.sceneId != null ? shotLabel(doc, use.sceneId) : "Shot";
+  return (
+    <div className="components-crumb" data-testid="components-crumb">
+      <span className="components-crumb-root" data-testid="components-crumb-shot">
+        {shot} /
+      </span>
+      {props.name}
+      <span className="components-crumb-use" data-testid="components-crumb-use">
+        this use · frame {clock(props.origin.shotFrame, fps)}
+      </span>
+    </div>
+  );
+}
+
+function SubjectCrumb(props: { sel: ComponentsSelection; name: ReactNode }) {
+  const store = useStore();
+  const used = useUsedIn(props.sel);
+  const open = useShotEditor((s) => usesViewOf(s) !== null);
+  const preview = useShotEditor((s) => s.componentsTab === "preview");
+  // A door to Every use (C4), which takes the preview's place; pressed again
+  // it closes.
+  return (
+    <div className="components-crumb" data-testid="components-crumb">
+      {preview ? <span className="components-crumb-root">All components /</span> : null}
+      {props.name}
+      <button
+        type="button"
+        className="components-crumb-uses"
+        data-testid="components-used-in"
+        aria-pressed={open}
+        title={open ? "Back to the preview" : "Every place that uses this component"}
+        onClick={() => store.openComponentUses(!open)}
+      >
+        used in {used} {used === 1 ? "place" : "places"}
+      </button>
+    </div>
+  );
+}
+
+/** The loop lengths the transport offers, in seconds, after the component's own. */
+const LOOP_SECONDS = [1, 2, 3, 4, 6, 8];
+
+const BACKDROPS: { value: ShotComponentBackground; label: string }[] = [
+  { value: "dark", label: "Dark" },
+  { value: "light", label: "Light" },
+  { value: "brand", label: "Brand" },
+];
+
+/** The loop's length on screen, and the component's own length (no loop set). */
+export function useLoopLength(): { frames: number; own: number; fps: Rational } {
+  const frames = useShotEditor((s) => defClockFrames(s) ?? 0);
+  const own = useShotEditor((s) => defClockFrames({ ...s, componentPreview: { ...s.componentPreview, loopFrames: null } }) ?? 0);
+  const fps = useShotEditor((s) => s.doc?.fps ?? FALLBACK_FPS);
+  return { frames, own, fps };
+}
+
+/**
+ * The Preview tab's 48 transport, under the stage in the canvas cell: pause,
+ * the loop length, the progress (a scrub), and the backdrop. The header's
+ * playback loop already plays the component clock (`defClockFrames`), so this
+ * is the dock's play button in another place (`PlayButton`, the same
+ * component), not a second playback path.
+ */
+export function PreviewTransport() {
+  const store = useStore();
+  const frame = useShotEditorHot((s) => s.defFrame);
+  const loopFrames = useShotEditor((s) => s.componentPreview.loopFrames);
+  const background = useShotEditor((s) => s.componentPreview.background);
+  const { frames, own, fps } = useLoopLength();
+  const label = (n: number): string => `Loop · ${formatDuration(framesToSeconds(n, fps))}`;
+  const choices = LOOP_SECONDS.map((sec) => secondsToFrame(sec, fps)).filter((n) => n !== own);
+  const last = Math.max(0, frames - 1);
+  return (
+    <div className="components-transport" data-testid="components-transport">
+      <PlayButton className="components-play" testId="components-play" />
+      <select
+        className="select components-loop"
+        data-testid="components-loop"
+        aria-label="Loop length"
+        value={loopFrames === null ? "" : String(loopFrames)}
+        onChange={(e) => {
+          const v = e.currentTarget.value;
+          store.setComponentPreview({ loopFrames: v === "" ? null : Number(v) });
+        }}
+      >
+        <option value="">{label(own)}</option>
+        {choices.map((n) => (
+          <option key={n} value={String(n)}>
+            {label(n)}
+          </option>
+        ))}
+        {loopFrames !== null && !choices.includes(loopFrames) && loopFrames !== own ? (
+          <option value={String(loopFrames)}>{label(loopFrames)}</option>
+        ) : null}
+      </select>
+      <input
+        className="transport-scrub components-progress"
+        type="range"
+        min={0}
+        max={last}
+        step={1}
+        value={Math.min(frame, last)}
+        aria-label="Loop position"
+        data-testid="components-progress"
+        onChange={(e) => {
+          store.pauseForScrub();
+          store.seekDef(Number(e.currentTarget.value));
+        }}
+      />
+      {/* The state's own value, with no default of its own: the look starts
+          on Dark (`INITIAL_STATE`), so what is lit is what the stage draws. */}
+      <SegmentedControl
+        ariaLabel="Backdrop"
+        className="components-backdrop"
+        value={background ?? ""}
+        options={BACKDROPS.map((b) => ({ value: b.value, label: b.label, testId: `components-backdrop-${b.value}` }))}
+        onChange={(next) => store.setComponentPreview({ background: next as ShotComponentBackground })}
+      />
+    </div>
+  );
+}
+
+/**
+ * The props panel's "Apply to all instances" checkbox, shared by the code
+ * and the definition panels (Framer's component panel: values are tried
+ * first, saved on purpose).
+ *
+ * Off: every edit is TRIED (`componentPlay`), drawn in the preview and saved
+ * nowhere. On: edits save to the component, which every instance without its
+ * own value follows; ticking it also saves whatever was being tried.
+ */
+export function ApplyAllToggle({ disabled, disabledReason }: { disabled: boolean; disabledReason?: string }) {
+  const store = useStore();
+  const on = useShotEditor((s) => s.componentApplyAll);
+  const tried = useShotEditor((s) => Object.keys(s.componentPlay).length);
+  return (
+    <div className="props-apply" data-testid="props-apply-all">
+      <label className="props-apply-row" title={disabled ? disabledReason : undefined}>
+        <input
+          type="checkbox"
+          className="checkbox"
+          checked={on && !disabled}
+          disabled={disabled}
+          onChange={(e) => store.setComponentApplyAll(e.currentTarget.checked)}
+        />
+        <span>Apply to all instances</span>
+      </label>
+      <p className="insp-note props-apply-note" data-testid="props-apply-note">
+        {on && !disabled
+          ? "Changes save to the component. Every instance without its own value follows."
+          : tried === 0
+            ? "Try values in the preview. Nothing is saved."
+            : `Trying ${tried === 1 ? "1 change" : `${tried} changes`} in the preview. Tick to save to every instance.`}
+      </p>
+    </div>
+  );
+}

package/src/panels/studio/components.ts

@@ -0,0 +1,6 @@
+// THE COMPONENTS WORKSPACE'S CHUNK: All components, a component's Preview tab
+// and a Studio-made component's Edit tab. Loaded on demand through
+// app/lazySurfaces.tsx. Code Studio is a chunk of its own, because it carries
+// the CodeMirror editor.
+export { ComponentStudio } from "./ComponentStudio.js";
+export { ComponentsPreview } from "./ComponentsPreview.js";

package/src/panels/studio/newCodeComponent.ts

@@ -0,0 +1,66 @@
+// What Components' New › Code writes: the "component-three" template and the
+// export-name rule, RESTATED from packages/store/src/componentTemplates.ts
+// (the chrome cannot import the store package). Keep the two in step:
+// test/newCodeComponent.test.ts holds them equal.
+
+/** PascalCase identifier from whatever the author typed. A component's NAME
+ *  is its export name, so an invalid identifier is a syntax error. */
+export function componentNameOf(input: string): string {
+  const base = input.slice(input.lastIndexOf("/") + 1).replace(/\..*$/, "");
+  const words = base.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const name = words.map((w) => w[0]!.toUpperCase() + w.slice(1)).join("");
+  return /^[A-Za-z]/.test(name) ? name : `C${name}`;
+}
+
+// The starter's r3f specifier, held apart from its `from` so sourceHygiene's
+// three-free scan reads the template as the text it is, not an import.
+const FIBER = "@react-three/fiber";
+
+/** The react-three-fiber starter: typed optional props with defaults, so the
+ *  extractor infers a usable contract with no controls file. It keeps the
+ *  shot lane's three rules, so it shows the moment it is made: it draws in
+ *  design px (the lane's world unit), its material needs no light (the lane
+ *  has none), and its time is the studio clock, read in render. Its empty r3f
+ *  type import is what declares its JSX: a new workspace has no other file
+ *  that loads r3f's types. */
+export function threeComponentSource(name: string): string {
+  return `// r3f's JSX types, so <mesh> and the other three elements type-check even
+// when no other file in the Project imports r3f. It loads no code.
+import type {} from "${FIBER}";
+import { useStudioClock } from "@dailies-studio/runtime";
+
+export interface ${name}Props {
+  /**
+   * How fast it turns. The angle comes from the studio clock and is never
+   * added up per frame, so a scrub or an export lands on the same pose.
+   * @min 0
+   * @max 5
+   */
+  speed?: number;
+  color?: string;
+  /**
+   * Across, in design px. One world unit on the stage is one design pixel.
+   * @min 1
+   * @max 2000
+   * @unit px
+   */
+  size?: number;
+}
+
+// torusKnotGeometry(0.7, 0.24) reaches 1.29 units from its centre, so at any
+// angle it stays inside a circle 2.58 units across.
+const SPAN = 2.58;
+
+export function ${name}({ speed = 1, color = "#4f8cff", size = 360 }: ${name}Props) {
+  const t = (useStudioClock()?.timeSeconds ?? 0) * speed;
+  // The stage has no lights, so the material must need none: a matcap shades
+  // the form from the view alone and still reads as 3D.
+  return (
+    <mesh rotation={[t * 0.7, t, 0]} scale={size / SPAN}>
+      <torusKnotGeometry args={[0.7, 0.24, 160, 32]} />
+      <meshMatcapMaterial color={color} />
+    </mesh>
+  );
+}
+`;
+}