@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/layout.ts

@@ -0,0 +1,295 @@
+// WHICH SECTIONS A SUBJECT GETS, AND IN WHAT ORDER. DECLARED, NOT DERIVED.
+//
+// ── THE PANEL MOUNTED EVERYTHING AND LET EACH SECTION REFUSE ────────────
+//
+// `InspectorPanel` used to render every design section for every selection and
+// each one gated itself: `layers.some((l) => l.kind === "cloner")` in one file,
+// `every(isMedia)` in a second, `layers.length === 1` in three more. So the
+// answer to "what does a text layer's inspector look like" was the ORDER OF THE
+// JSX plus a kind predicate buried inside whichever of the sections happened to
+// carry one, a file each. Nothing asserted it, two sections could disagree about
+// the same selection, and a new layer kind got whatever happened to fall out.
+//
+// This file IS that answer, and `test/inspectorLayout.test.tsx` pins it per
+// kind. `LAYER_LAYOUT` is a `Record` over the schema's own union — the rule
+// `KIND_WORDS` (layerWords.ts) already follows — so a sixteenth layer kind
+// is a COMPILE ERROR here rather than a rail that silently offers it nothing
+// but Transform.
+//
+// ── KIND GATES MOVED HERE; THE REST STAYED, AND MOST OF THAT IS A CHOICE ─
+//
+// "Is this layer a cloner" is a question about the kind, and the table answers
+// it once. The gates that stayed behind split in two, and only one half is
+// out of reach.
+//
+// "Does this mesh wear a node graph", "is this instance's definition still
+// there" are questions about the DOCUMENT. Nothing handed to this module can
+// answer them, so they could not move even in principle.
+//
+// "Is exactly one layer selected", "is every one of them media", "which layer
+// leads" could: `sectionsFor` is given `layers.map((l) => l.kind)`, the kinds
+// IN SELECTION ORDER, so the count, the leader and the whole multiset are
+// already in its argument. They stay in their sections anyway, because
+// re-deriving them here would be a SECOND SPELLING of each section's own rule
+// and two spellings are what drift — the sections keep the one copy and this
+// table stays the ceiling. Every one of them is named on `sectionsFor` below,
+// because a gate nobody wrote down is the gate the next author debugs twice.
+import type { Layer3DKind } from "@dailies-studio/shot/doc";
+
+/**
+ * Every design section, in the order a MIXED selection renders them.
+ *
+ * The order is the order the picture is described in: where the layer is
+ * (transform, appearance), WHEN it is (time), what it IS (the per-kind block,
+ * a mesh's geometry, a device's slab, a component's definition, a cloner's
+ * arrangement, a media layer's source), what is PAINTED onto it, what its
+ * content is (type, markup), and last what it DOES over time.
+ *
+ * "Time" is the layer's LIFETIME and, for a video, the footage under it: the
+ * window, the source edges, the speed and what happens past the recording's
+ * end. It sits with transform and appearance because it is a fact about the
+ * layer, and every kind has one.
+ *
+ * "Mask" leads (gap 7, Paper page 25): a mask paints nothing of its own, so
+ * what it does to the layers in front of it is the first fact about it.
+ *
+ * "Template field" (schema v50) follows the content: whether a person who
+ * starts from this Project swaps the layer for their own is a fact about what
+ * the layer shows, so it sits after the sections that say what that is.
+ */
+export const SECTION_ORDER = [
+  "mask",
+  "transform",
+  "appearance",
+  "time",
+  "presets",
+  "mesh",
+  "material",
+  "device",
+  "instance",
+  "component",
+  "cloner",
+  "media",
+  "plateStyle",
+  "textFill",
+  "fill",
+  "stroke",
+  "corner",
+  "shadow",
+  "typography",
+  "html",
+  "templateField",
+  "splineFollow",
+] as const;
+
+export type SectionId = (typeof SECTION_ORDER)[number];
+
+/** Where the layer is, how it reads, when it exists and how it comes and goes.
+ *  Every kind has all of them: a lifetime is not optional, so neither is the
+ *  section that edits it, and every kind has an opacity a Fade can stamp
+ *  ("presets", the Motion section: a preset writes ordinary keys).
+ *  Any kind can be a mask too, so every kind lists "mask"; the section itself
+ *  is a document gate (see `sectionsFor`). */
+const BASE = ["mask", "transform", "appearance", "time", "presets"] as const satisfies readonly SectionId[];
+
+/**
+ * The four sections that write `paint`. A kind lists only the ones its draw
+ * reads (F30): ellipse and path have no corner, line and arrow have no fill or
+ * corner, and media has no fill (see `LAYER_LAYOUT`).
+ *
+ * The six kinds that do NOT list these are refused for two overlapping reasons.
+ * `mesh`, `device` and `instance` DRAW but never take a rasterizer call — a
+ * mesh's look is its material, a device's slab colour comes from its preset
+ * (device.tsx reads `deviceSlab`, never `paint`), and an instance paints
+ * itself. `group`, `cloner` and `component` do not draw at all; they are
+ * transform, derivation and definition parents. For every one of the six a
+ * fill, a stroke, a corner radius and a shadow are document fields that move no
+ * pixel: the author edits one, sees nothing, and concludes the renderer is
+ * broken.
+ */
+const PAINT = ["fill", "stroke", "corner", "shadow"] as const satisfies readonly SectionId[];
+
+/** What the layer does over time beyond its keyframes. The keyframes are the
+ *  timeline dock's channel rows and the inspector's diamonds, not a section. */
+const MOTION = ["splineFollow"] as const satisfies readonly SectionId[];
+
+/**
+ * The predefined control panel for each layer kind.
+ *
+ * MEDIA HAS NO `fill`, which is the one entry that is not simply "what the kind
+ * carries": `drawLayer` paints `paint.fill` only in the arm that is neither
+ * "mask" nor "plate" (raster.ts) and `MediaPlane` asks for exactly those two, so
+ * a photo's fill swatch writes a field and moves nothing. Stroke, corner and
+ * shadow ride the plate and the mask, so those three stay.
+ *
+ * TEXT'S "Fill" IS THE GLYPH COLOUR (`textFill`, F20), the Figma meaning. Its
+ * `paint.fill` is the plate behind the words, so that section reads
+ * "Background" over text (FillSection).
+ *
+ * ONLY TEXT, IMAGE AND VIDEO LIST `templateField`: they are `SWAP_KINDS`, the
+ * kinds `setLayerSwap` lets a template field sit on.
+ */
+export const LAYER_LAYOUT: Record<Layer3DKind, readonly SectionId[]> = {
+  text: [...BASE, "textFill", ...PAINT, "typography", "templateField", ...MOTION],
+  image: [...BASE, "media", "plateStyle", "stroke", "corner", "shadow", "templateField", ...MOTION],
+  video: [...BASE, "media", "plateStyle", "stroke", "corner", "shadow", "templateField", ...MOTION],
+  rect: [...BASE, ...PAINT, ...MOTION],
+  ellipse: [...BASE, "fill", "stroke", "shadow", ...MOTION],
+  line: [...BASE, "stroke", "shadow", ...MOTION],
+  arrow: [...BASE, "stroke", "shadow", ...MOTION],
+  path: [...BASE, "fill", "stroke", "shadow", ...MOTION],
+  html: [...BASE, ...PAINT, "html", ...MOTION],
+  group: [...BASE, ...MOTION],
+  device: [...BASE, "device", ...MOTION],
+  mesh: [...BASE, "mesh", "material", ...MOTION],
+  cloner: [...BASE, "cloner", ...MOTION],
+  instance: [...BASE, "instance", ...MOTION],
+  component: [...BASE, "component", ...MOTION],
+};
+
+/**
+ * The sections a selection of these kinds renders, in `SECTION_ORDER`.
+ *
+ * THE UNION, NEVER THE INTERSECTION. A rect selected with a mesh keeps the
+ * paint block, because the rect in it still paints and `useSelectionWrite`
+ * already skips the layers a write cannot reach — a false cut hides a real
+ * control, which is strictly worse than a control that only reaches half the
+ * selection. That is also what the old self-gating stack produced (every kind
+ * gate in it was `some`, never `every`), and `inspectorPanel.test.tsx` pins it.
+ *
+ * DECLARED IS THE CEILING, NOT THE MOUNT. Nothing outside this list mounts.
+ * Something inside it can still withhold itself, on a question about the SHAPE
+ * OF THE SELECTION or about the DOCUMENT. The document ones are outside this
+ * module's reach. The shape ones are NOT — the argument is the kinds in
+ * selection order — and they are left in their sections deliberately, so each
+ * rule has exactly one spelling. Every withholding, and its exact condition:
+ *
+ *   `component`              ONE layer only. Each panel's rows are one
+ *   `instance`, `material`   definition's or one graph's own key list, so a
+ *                            fan-out would write keys the other subject has
+ *                            never heard of.
+ *   `templateField`          ONE layer only. A field's name says what THAT
+ *                            layer asks for ("Screenshot", "Headline"), so two
+ *                            layers under one name would be one question
+ *                            asked twice.
+ *   `time`                   ONE layer only, and on its own reason rather than
+ *                            theirs: nothing about it is a key list. A lifetime
+ *                            belongs to one layer and every clip op takes one
+ *                            `layerId`, so fanning the edges out would need
+ *                            `moveLayers`' all-or-nothing posture, and "source
+ *                            in" has no fan-out meaning at all because the next
+ *                            layer's footage starts somewhere else entirely.
+ *                            `TimeSection`'s own header states this rule and
+ *                            names this list as the company it keeps, so the
+ *                            two are written to be read together.
+ *   `plateStyle`             `every(isMedia)`. A plate chip writes stroke,
+ *                            radius and shadows over the WHOLE selection, so a
+ *                            rect in it would be restyled from a shelf that
+ *                            never named it.
+ *   `cloner`, `html`         the FIRST selected layer's. A selection led in
+ *                            document order by anything else has no arrangement
+ *                            and no markup to show. (They arrive there by
+ *                            different routes: `html` reads through
+ *                            `useSelectionValue`, while `ClonerSection` takes
+ *                            the lead layer directly and asks about mixedness
+ *                            per field — an object read through that hook makes
+ *                            every multi-selection "Mixed" by identity.)
+ *   `material`               and, ON TOP of the one-layer rule, the document
+ *                            has to hold what it describes: a mesh with no
+ *                            node graph renders nothing at all.
+ *   `mask`                   a document gate: it renders only when a selected
+ *                            layer is a mask or a group that holds one
+ *                            (`maskTargetOf`).
+ *   `splineFollow`           a document gate too: it renders only when the
+ *                            layer already follows a spline, the home holds a
+ *                            spline it could follow, or a cloner's spline
+ *                            distribution owns the path.
+ *
+ * The material gate is why "a single layer renders exactly its row of the
+ * table" is true of fourteen of the fifteen kinds and not of `mesh`: its
+ * material needs a graph behind it, which is why the fixture in
+ * `inspectorLayout.test.tsx` mints one before asserting the row.
+ * Every withholding above is pinned in that file too, so this list is asserted
+ * rather than merely written down.
+ */
+export function sectionsFor(kinds: Iterable<Layer3DKind>): readonly SectionId[] {
+  const wanted = new Set<SectionId>();
+  for (const kind of kinds) for (const id of LAYER_LAYOUT[kind]) wanted.add(id);
+  return SECTION_ORDER.filter((id) => wanted.has(id));
+}
+
+/** What the rail is looking at when NOTHING is selected. The three are decided
+ *  by the context bits alone: an open definition, then the entered shot, then
+ *  the project the panel is a view of. */
+export type ContainerSubject = "project" | "shot" | "definition" | "storyboard";
+
+/**
+ * Every container section, by id.
+ *
+ * `shotTransition` is the PROJECT context's shot: the shot's own rows and the
+ * seam after it, under one head. `shot` is the same shot rows alone, for the
+ * inside of a shot, where the seam is off screen. `blur` and `postprocessing`
+ * are the two halves of one `Scene3D.effects` stack, split by what the pass
+ * does to the picture (see `EffectsSection`).
+ */
+export type ContainerSectionId =
+  | "project"
+  | "makeItYours"
+  | "shot"
+  | "shotTransition"
+  | "camera"
+  | "blur"
+  | "postprocessing"
+  | "definition"
+  | "storyboardReference"
+  | "storyboardCut";
+
+/**
+ * The predefined control panel for each container subject.
+ *
+ * EACH CONTEXT LEADS WITH ITSELF (Paper 27, "8 · Empty inspector"). With
+ * nothing selected the first read is the context the author is in: the
+ * Project's name, size and rate above the shots, the Shot's background and
+ * duration inside one. The camera follows in both, because it is what the
+ * stage IS (the presented shot camera above, the framed picture inside), and
+ * the other context's section after it. Blur and Postprocessing close the
+ * list, blur first because a defocus is a lens decision and a grade is not;
+ * each opens collapsed to one "None" line while it holds no pass
+ * (EffectsSection).
+ *
+ * This replaced one shared order (Camera, Project, Shot, ...) for both
+ * contexts. That order put the camera's numbers first in a panel whose
+ * subject was the Project or the Shot, so the empty inspector never said
+ * where the author was.
+ *
+ * Camera, Blur and Postprocessing used to sit out the project context on the
+ * claim that nobody could judge them there. That stopped being true: the stage
+ * there is the presented shot camera, `writeCamera` and `writeScene` both
+ * resolve the shot from the playhead, and a camera drag on the stage was
+ * already allowed. So the rail now offers what the stage already did.
+ *
+ * WHERE THE TWO DIFFER IS THE SEAM. PROJECT holds `shotTransition`, because a
+ * transition is a property of the join between two shots and that join is
+ * drawn there: the shot row puts a diamond on every cut. SHOT holds plain
+ * `shot`, because inside one shot the strip is gone and the shot after it is
+ * off screen, so the one thing an author cannot see is the join a transition
+ * describes. DEFINITION is the open component's own panel; the scene sections
+ * there would describe a scene the stage is not rendering.
+ *
+ * MAKE IT YOURS comes second in both Studio contexts, right after the context
+ * itself: in a Project started from a template, swapping its fields for one's
+ * own is the first work there is. It is a DATA gate, in the spirit of the
+ * layer withholdings: it renders only while `swapFieldsOf` lists a field.
+ */
+export const CONTAINER_LAYOUT: Record<ContainerSubject, readonly ContainerSectionId[]> = {
+  project: ["project", "makeItYours", "shotTransition", "camera", "blur", "postprocessing"],
+  shot: ["shot", "makeItYours", "camera", "project", "blur", "postprocessing"],
+  definition: ["definition"],
+  // STORYBOARD is the board's own panel. Each section gates on WHAT the
+  // board's selection points at (one card, one cut), a data question
+  // in the spirit of the layer withholdings above, so exactly one of them
+  // renders at a time. With nothing of that kind selected the right column
+  // holds no inspector (`boardRightPanel`), so there is no Doc or Part section
+  // any more.
+  storyboard: ["storyboardReference", "storyboardCut"],
+};

package/src/panels/inspector/propValue.ts

@@ -0,0 +1,199 @@
+// THE ONE CONVERSION between what a prop row's control hands back and what the
+// document may hold, for every ControlSpec row in the chrome: a placed code
+// component's props, a Studio-made component's overrides and published props,
+// a code component's defaults, and one use of either.
+//
+// ── WHY THE CONTRACT'S `coerceValue` AND NOT A CHECK OF ITS OWN ─────────
+//
+// Each surface used to run its own `asValue`, which took any string, any
+// boolean and any short number list and refused every object. So the curve and
+// gradient editors, which hand back the decoded VALUE OBJECT, ended every edit
+// in an error and their props could not be changed at all, while a colour box
+// stored "banana" and an enum stored an option the contract no longer has.
+// `coerceValue` is the contract's own answer: it encodes a composite to its
+// canonical JSON, checks enum membership and tuple shapes, and ends at the
+// engine's value-shape gate (finite numbers, `#rrggbb[aa]` colours, unit
+// quaternions), the gate the save itself runs.
+//
+// ── NULL IS "NO ASSET", NOT "NOT A VALUE" ───────────────────────────────
+//
+// An asset control's "None" (and an emptied id field) hands back null, which no
+// document field can hold: an asset prop with no asset is a prop that stores
+// nothing and falls back to its default. So "None" CLEARS the row when that
+// fallback is itself no asset, and is refused with the reason when the default
+// names one, rather than storing a value that would read back as the default's
+// asset and look like the press had been ignored.
+import { clampedStoredValue, coerceStoredValue, controlLabel, rangeWordsOf } from "@dailies-studio/contract";
+import type { Contract, ControlSpec } from "@dailies-studio/contract";
+import type { Value } from "@dailies-studio/engine";
+import { exposedSpecOf, toTrackHex } from "@dailies-studio/shot/doc";
+import { mimeForPath } from "@dailies-studio/shot/mime";
+import type { ComponentDef3D, Doc3D, ExposedProp3D, ShotAssetKind } from "@dailies-studio/shot/doc";
+import type { PropControlAsset } from "@dailies-studio/ui";
+import { fileNameOf } from "../files/resourceParts.js";
+
+/** The engine Value a control's value is stored as, or null when it cannot be
+ *  one (the document would refuse it). */
+export function coercePropValue(spec: ControlSpec, raw: unknown): Value | null {
+  const out = coerceStoredValue(spec, raw);
+  return out.ok ? out.value : null;
+}
+
+/** What a prop row does with a value its control handed back. */
+export type PropEdit =
+  | { kind: "set"; value: Value }
+  /** Store nothing: the row falls back to its default (an asset's "None"
+   *  over a default that names no asset). */
+  | { kind: "clear" }
+  | { kind: "refused"; reason: string };
+
+/** No asset: what an asset control's "None" and an emptied id field commit. */
+function isNoAsset(value: unknown): boolean {
+  return value === null || value === undefined || value === "";
+}
+
+/** The row's words for a refusal, read defensively: a hand-built spec may
+ *  carry no key at all. */
+function wordsOf(spec: ControlSpec): string {
+  const key = typeof spec.key === "string" ? spec.key : "";
+  return controlLabel(typeof spec.label === "string" ? { key, label: spec.label } : { key }) || "This prop";
+}
+
+/**
+ * The edit a row makes for `raw`. `fallback` is what the row shows when it
+ * stores nothing (the contract default, the master's value), which decides
+ * whether an asset's "None" can be kept by clearing.
+ */
+export function propEditOf(spec: ControlSpec, raw: unknown, fallback: unknown): PropEdit {
+  const label = wordsOf(spec);
+  if (spec.kind === "asset" && isNoAsset(raw)) {
+    return isNoAsset(fallback)
+      ? { kind: "clear" }
+      : { kind: "refused", reason: `${label} cannot be set to no asset here: its default names one. Pick another asset instead.` };
+  }
+  const out = coerceStoredValue(spec, raw);
+  return out.ok ? { kind: "set", value: out.value } : { kind: "refused", reason: `${label} cannot hold that value (${out.error}).` };
+}
+
+/**
+ * A stored number or vector outside its spec's range, which its field cannot
+ * show truthfully (the slider sits at the end, the box shows a number the
+ * field would never commit): a component narrowed the range after the value
+ * was set, or a hand edit put it there. The row's warning, and the nearest
+ * value inside (`clampedStoredValue`) its "Bring inside" stores. Null when
+ * the value is inside, or the spec has no range.
+ */
+export function outsideRangeOf(
+  spec: ControlSpec,
+  value: Value | undefined,
+): { words: string; title: string; inside: Value } | null {
+  if (value === undefined || (spec.kind !== "number" && spec.kind !== "vec2" && spec.kind !== "vec3")) return null;
+  const inside = clampedStoredValue(spec, value);
+  const range = rangeWordsOf(spec);
+  if (inside === value || range === null) return null;
+  const shown = (v: Value): string => (Array.isArray(v) ? v.join(", ") : String(v));
+  const label = wordsOf(spec);
+  return {
+    words: `${label} is ${shown(value)}, outside its range of ${range}.`,
+    title: `Set ${label} to ${shown(inside)}, the nearest value inside its range`,
+    inside,
+  };
+}
+
+/**
+ * The value as the row's control should be handed it. A colour is read in any
+ * spelling a layer holds (a paint's `rgba(30,215,96,0.18)`, a short `#fff`) and
+ * shown as the hex the colour field reads and writes, the respelling the
+ * keyframe seam makes (`toTrackHex`); one it cannot read is shown as it is.
+ */
+export function shownPropValue(spec: ControlSpec, value: unknown): unknown {
+  if (spec.kind === "color" && typeof value === "string") return toTrackHex(value) ?? value;
+  return value;
+}
+
+/**
+ * What a prop row shows while it follows its master (it stores and tries
+ * nothing of its own): the MASTER'S VALUE, what an un-overridden placement
+ * draws (`masterValueOf`, `exposedMasterValue`), whenever the row's control
+ * can hold it. Else the spec's default, a valid typed value: a published
+ * prop's master falls back to its stored `default` where the definition draws
+ * nothing, and that can be the blank an old `expose_prop` minted.
+ *
+ * Not the spec's default first: `exposedSpecOf` takes the published `default`
+ * as its own, and that one drifts from the layer once the published field is
+ * edited anywhere but the props panel, so every row showed a value nothing on
+ * screen had.
+ */
+export function masterRowValue(spec: ControlSpec, master: unknown): unknown {
+  const typed = "default" in spec ? spec.default : undefined;
+  if (master === undefined) return typed;
+  return coercePropValue(spec, shownPropValue(spec, master)) !== null ? master : (typed ?? master);
+}
+
+/** A spec PropControl draws as one box per part (a vec2, a vec3, a
+ *  quaternion's Euler X, Y and Z), whatever value it holds. A verb on the
+ *  whole track (the expose pin) sits once in such a row's label column, where
+ *  a box's accessory would repeat in every part and crowd the first. */
+export function isVectorSpec(spec: ControlSpec): boolean {
+  return spec.kind === "vec2" || spec.kind === "vec3" || spec.kind === "quaternion";
+}
+
+/** An exposed prop's row: its control, and whether anything in reach could
+ *  describe one. */
+export interface ExposedRow {
+  spec: ControlSpec;
+  /** The target takes `#rrggbb` only, so the colour field offers no alpha. */
+  opaqueColor: boolean;
+  /** Nothing describes the control (a kind this editor does not know, an enum
+   *  or an asset the record cannot carry the options or kind of): the row is
+   *  read-only, its control saying what it can ("Unknown kind: …", "No
+   *  options"), where it used to be a bare badge. */
+  undescribed: boolean;
+}
+
+/**
+ * The row for one exposed prop of a definition, from what the prop drives
+ * (`exposedSpecOf`: its target's table row, contract spec or graph parameter),
+ * so the definition's own panel, an instance's override rows and one use's
+ * panel draw the same bounded, typed control for it.
+ */
+export function exposedRowOf(
+  prop: ExposedProp3D,
+  def: ComponentDef3D,
+  materials: Doc3D["materials"] | undefined,
+  contracts: Readonly<Record<string, Contract>>,
+): ExposedRow {
+  const control = exposedSpecOf(prop, def, { materials, contracts });
+  if (control !== null) return { spec: control.spec, opaqueColor: control.opaqueColor, undescribed: false };
+  const spec = { key: prop.key, propName: prop.key, label: prop.label, kind: prop.kind, animatable: false };
+  return { spec: spec as unknown as ControlSpec, opaqueColor: false, undescribed: true };
+}
+
+/** A Project asset's kind in the contract's words (`AssetSpec.assetKind`). A
+ *  model is a "glb" there; a video has no asset kind a contract can ask for. */
+function contractAssetKind(kind: ShotAssetKind): string {
+  return kind === "model" ? "glb" : kind;
+}
+
+/**
+ * The Project's assets as an asset prop's picker offers them: by id, named by
+ * their file, in the contract's kinds, each with its file `name` and its MIME
+ * type, which the picker reads against the spec's `accept` list
+ * (`assetAccepted`): an extension entry (".png") against the name, a MIME
+ * entry ("image/svg+xml", "image/*") against the type.
+ *
+ * A Project asset records no MIME type (`ShotAsset`: a path, a hash, a kind
+ * and a probe), so the type is the one the studio serves its stored file as,
+ * from the one extension-to-MIME table (`mimeForPath`,
+ * `@dailies-studio/shot/mime`). A file whose extension the table does not know
+ * carries no type, and the picker offers it rather than hide it.
+ */
+export function projectAssetsOf(assets: Doc3D["assets"] | undefined): PropControlAsset[] {
+  return Object.values(assets ?? {})
+    .map((asset) => {
+      const name = fileNameOf(asset);
+      const mime = mimeForPath(asset.path);
+      return { id: asset.id, label: name, kind: contractAssetKind(asset.kind), name, ...(mime === undefined ? {} : { mime }) };
+    })
+    .sort((a, b) => a.label.localeCompare(b.label));
+}