@odori/cli 0.0.3 → 0.0.5

package/studio/src/views/ComponentsView.tsx

@@ -10,14 +10,15 @@ import {
   type Brand,
   type VideoEntry,
 } from "odori";
-import {PreviewBoundary} from "odori/preview";
+import {PreviewBoundary, categoryFromPath, categoryPath, familyOf, groupOf} from "odori/preview";
 import {componentPreviews, project, videos} from "virtual:odori-project";
 import {CanvasStage} from "../components/CanvasStage";
 import {Transport} from "../components/Transport";
 import {Thumbnail} from "../components/Thumbnail";
 import {InputControls} from "../components/InputControls";
-import {Badge, Button, Empty, Fact, SectionTitle, Separator} from "../components/ui";
+import {Button, Empty, Fact, SectionTitle, Separator} from "../components/ui";
 import {Inspector} from "../components/Inspector";
+import {Navigator} from "../components/Navigator";
 import {useShortcuts} from "../shortcuts";
 
 type PreviewEntry = (typeof componentPreviews)[number];
@@ -32,11 +33,93 @@ const projectBrands = (): Brand[] => {
   return [...seen.values()];
 };
 
-const FAMILY_ORDER = ["Typography", "Developer proof", "Product UI", "Narrative", "Brand", "Media", "Audio"];
+// The reading order of the catalog: what you author, then what you show, then
+// what carries it. A family missing here sorts last, alphabetically.
+/**
+ * The reading order of the catalog. A category nests, so this lists families
+ * and the groups inside them sort alphabetically underneath: the order that
+ * matters is which family you meet first, not which of its drawers.
+ */
+const FAMILY_ORDER = [
+  "Typography",
+  "Developer proof",
+  "Interface",
+  "Agents",
+  "Products",
+  "Narrative",
+  "Data",
+  "Media",
+  "Motion",
+  "Brand",
+  "Foundation",
+  "Sound",
+];
+
+/**
+ * Where a family sorts.
+ *
+ * The listed ones are the registry's, in reading order. A project's own
+ * families are not in that list and must not all collapse to the same rank:
+ * they sort alphabetically after, so somebody who writes their own categories
+ * gets a stable order rather than whatever the file walk happened to produce.
+ */
+/**
+ * Where a component belongs.
+ *
+ * The fixture wins when it says, because a registry component is copied into
+ * somebody's tree, lands flat, and has to keep the family it was written for.
+ * Otherwise the directory answers, which is how a project organises its own
+ * work: move the folder and it moves in Studio, with nothing to keep in sync
+ * and no group that exists only because somebody mistyped one. A directory
+ * names itself in a `category.json` beside its components, which is the one
+ * thing a filesystem cannot say.
+ */
+/** What a directory calls itself, from its own `category.json`. */
+const declared = new Map(project.categories.map((entry) => [entry.path, entry]));
+
+export const categoryOf = (entry: PreviewEntry): string => {
+  if (entry.preview.category) return entry.preview.category;
+  const file = project.files.previews.find((item) => item.id === entry.id)?.file;
+  const derived = file
+    ? categoryFromPath(file, project.componentsDir.split("/").pop(), (path) => declared.get(path)?.name)
+    : "";
+  return derived || "Uncategorised";
+};
+
+/**
+ * Where a family sorts, when a project has said so.
+ *
+ * `category.json` carries an order, which is the only way a project can put
+ * its own families in a sensible sequence: the list above is ours, and a
+ * hardcoded list of somebody else's families is no use to them.
+ */
+const declaredOrder = (family: string): number | undefined => {
+  for (const entry of project.categories) {
+    if (entry.order === undefined || entry.path.includes("/")) continue;
+    const label = entry.name ?? entry.path.replace(/-/g, " ").replace(/^./, (letter) => letter.toUpperCase());
+    if (label === family) return entry.order;
+  }
+  return undefined;
+};
+
+const familyRank = (family: string): number => {
+  // A project's own order leads, then ours, then whatever is left, which
+  // sorts alphabetically. Declared orders go negative so they rank ahead.
+  const own = declaredOrder(family);
+  if (own !== undefined) return own - 1000;
+  const known = FAMILY_ORDER.indexOf(family);
+  return known === -1 ? FAMILY_ORDER.length : known;
+};
 
 const byFamily = (left: PreviewEntry, right: PreviewEntry) => {
-  const delta = FAMILY_ORDER.indexOf(left.preview.category) - FAMILY_ORDER.indexOf(right.preview.category);
-  return delta !== 0 ? delta : left.preview.title.localeCompare(right.preview.title);
+  const leftFamily = familyOf(categoryOf(left));
+  const rightFamily = familyOf(categoryOf(right));
+  const delta = familyRank(leftFamily) - familyRank(rightFamily);
+  if (delta !== 0) return delta;
+  const family = leftFamily.localeCompare(rightFamily);
+  if (family !== 0) return family;
+  const group = groupOf(categoryOf(left)).localeCompare(groupOf(categoryOf(right)));
+  return group !== 0 ? group : left.preview.title.localeCompare(right.preview.title);
 };
 
 const FORMATS = [
@@ -76,7 +159,26 @@ export const ComponentsView = ({
 }) => {
   // Finding one by name is ⌘K; the gallery is for browsing them all. A route
   // with no selection is the gallery; a selection is that component's player.
-  const filtered = useMemo(() => [...componentPreviews].sort(byFamily), []);
+  const [usedIn, setUsedIn] = useState<string | null>(null);
+
+  /**
+   * Which video a component appears in, derived from the imports rather than
+   * declared, so it cannot disagree with the composition. A project of a
+   * hundred components is otherwise a wall with no way in.
+   */
+  const usage = useMemo(
+    () => Object.fromEntries(project.files.previews.map((entry) => [entry.id, entry.usedBy])),
+    [],
+  );
+  const videosUsing = useMemo(
+    () => [...new Set(Object.values(usage).flat())].sort(),
+    [usage],
+  );
+
+  const filtered = useMemo(() => {
+    const all = [...componentPreviews].sort(byFamily);
+    return usedIn ? all.filter((item) => (usage[item.id] ?? []).includes(usedIn)) : all;
+  }, [usedIn, usage]);
   const selected = selection ? (filtered.find((entry) => entry.id === selection) ?? null) : null;
   const brands = projectBrands();
   const [brandName, setBrandName] = useState(brands[0]?.name ?? defaultBrand.name);
@@ -119,17 +221,62 @@ export const ComponentsView = ({
   }
 
   if (!selected) {
-    const grouped = filtered.reduce<Record<string, PreviewEntry[]>>((groups, item) => {
-      groups[item.preview.category] = [...(groups[item.preview.category] ?? []), item];
-      return groups;
-    }, {});
+    /*
+     * Two levels, because a category is a path. Rendering one section per
+     * full path printed the family again for every drawer inside it -
+     * Interface, Interface, Interface - which is a list pretending to be an
+     * outline. `filtered` is already sorted by family, then group, then
+     * title, so walking it in order is enough to build the tree.
+     */
+    const families: Array<{name: string; groups: Array<{name: string; entries: PreviewEntry[]}>}> = [];
+    for (const item of filtered) {
+      const familyName = familyOf(categoryOf(item));
+      const groupName = groupOf(categoryOf(item));
+      let family = families.at(-1);
+      if (!family || family.name !== familyName) {
+        family = {name: familyName, groups: []};
+        families.push(family);
+      }
+      let group = family.groups.at(-1);
+      if (!group || group.name !== groupName) {
+        group = {name: groupName, entries: []};
+        family.groups.push(group);
+      }
+      group.entries.push(item);
+    }
     return (
       <div style={{overflowY: "auto", width: "100%"}}>
-        {Object.entries(grouped).map(([category, entries]) => (
-          <section key={category} style={{padding: "16px 20px 0"}}>
-            <SectionTitle>{category}</SectionTitle>
-            <div className="gallery" style={{padding: "0 0 8px"}}>
-              {entries.map((item) => (
+        {videosUsing.length > 0 ? (
+          <div className="catalog-filter">
+            <button type="button" data-active={usedIn === null ? "true" : undefined} onClick={() => setUsedIn(null)}>
+              All
+            </button>
+            {videosUsing.map((video) => (
+              <button
+                key={video}
+                type="button"
+                data-active={usedIn === video ? "true" : undefined}
+                onClick={() => setUsedIn(video)}
+              >
+                {video}
+              </button>
+            ))}
+          </div>
+        ) : null}
+        {families.map((family) => (
+          <section key={family.name} style={{padding: "16px 20px 0"}}>
+            <SectionTitle>{family.name}</SectionTitle>
+            {family.groups.map((group) => (
+              <div key={group.name || "."}>
+                {/* A family whose components sit at its top level has one
+                    unnamed group, and no heading to draw for it. */}
+                {/* Any depth renders: the family is the heading, and whatever
+                    a project nests below it reads as one path. Two levels is
+                    our own editorial rule for our registry, not a limit the
+                    framework puts on anybody else's. */}
+                {group.name ? <h3 className="group-title">{group.name.split("/").join(" · ")}</h3> : null}
+                <div className="gallery" style={{padding: "0 0 8px"}}>
+                  {group.entries.map((item) => (
                 <button key={item.id} type="button" className="card" onClick={() => onSelect(item.id)}>
                   <Thumbnail
                     entry={entryFor(
@@ -151,8 +298,10 @@ export const ComponentsView = ({
                     <span>{item.id}</span>
                   </div>
                 </button>
-              ))}
-            </div>
+                  ))}
+                </div>
+              </div>
+            ))}
           </section>
         ))}
       </div>
@@ -167,8 +316,30 @@ export const ComponentsView = ({
   const props = {...controlDefaults, ...(example?.props ?? {}), ...overrides};
   const entry = entryFor(selected, props, brand, format);
 
+  const previewFile =
+    project.files.previews.find((entry) => entry.id === selected.id)?.file ??
+    `videos/components/${selected.id}/${selected.id}.preview.tsx`;
+  // What it draws comes before the fixture that plays it: the fixture is the
+  // harness, and reading only the harness answers the wrong question.
+  const componentFile = previewFile.replace(/\.preview\.tsx$/, ".tsx");
+  const sources = componentFile === previewFile ? [previewFile] : [componentFile, previewFile];
+
   return (
     <>
+      {/* `filtered` is already sorted family, group, title, so the list reads
+          in the same order the gallery does. */}
+      <Navigator
+        label="Components"
+        selected={selected.id}
+        onSelect={onSelect}
+        items={filtered.map((item) => ({
+          id: item.id,
+          title: item.preview.title,
+          detail: item.id,
+          group: categoryPath(categoryOf(item)).join(" · "),
+        }))}
+      />
+
       <section className="stage">
         <CanvasStage width={format.width} height={format.height}>
           <PreviewBoundary resetKey={`${selected.id}-${format.label}-${brand.name}`} label="This component threw">
@@ -190,13 +361,7 @@ export const ComponentsView = ({
         />
       </section>
 
-      <Inspector
-        title={preview.title}
-        hint={
-          project.files.previews.find((entry) => entry.id === selected.id)?.file ??
-          `videos/components/${selected.id}/${selected.id}.preview.tsx`
-        }
-      >
+      <Inspector title={preview.title} hint={componentFile} source={sources}>
         <SectionTitle>Examples</SectionTitle>
         <ul className="list">
           {preview.examples.map((item) => (
@@ -219,7 +384,7 @@ export const ComponentsView = ({
 
         <SectionTitle>Component</SectionTitle>
         <dl className="facts">
-          <Fact label="category">{preview.category}</Fact>
+          <Fact label="category">{categoryPath(categoryOf(selected)).join(" · ")}</Fact>
           <Fact label="canvas">
             {preview.canvas.width}x{preview.canvas.height} · {String(preview.canvas.duration)}
           </Fact>
@@ -255,7 +420,7 @@ export const ComponentsView = ({
               {item.name}
             </Button>
           ))}
-          <Badge>{Object.keys(preview.controls ?? {}).length} controls</Badge>
+
         </div>
 
         <Separator />

package/studio/src/views/HomeView.tsx

@@ -4,7 +4,8 @@ import {Thumbnail} from "../components/Thumbnail";
 import {AudioClip} from "../components/AudioClip";
 import {SectionTitle} from "../components/ui";
 import {collectBrands} from "./BrandsView";
-import {entryFor} from "./ComponentsView";
+import {categoryOf, entryFor} from "./ComponentsView";
+import {familyOf} from "odori/preview";
 import type {StudioView} from "../Studio";
 
 /**
@@ -28,7 +29,7 @@ export const HomeView = ({onOpen}: {onOpen: (view: StudioView, selection?: strin
           <SectionTitle>Videos</SectionTitle>
           {videos.length > SHOWN ? (
             <button type="button" className="view-all" onClick={() => onOpen("videos")}>
-              View all {videos.length} →
+              View all →
             </button>
           ) : null}
         </div>
@@ -58,7 +59,7 @@ export const HomeView = ({onOpen}: {onOpen: (view: StudioView, selection?: strin
           <SectionTitle>Components</SectionTitle>
           {componentPreviews.length > SHOWN ? (
             <button type="button" className="view-all" onClick={() => onOpen("components")}>
-              View all {componentPreviews.length} →
+              View all →
             </button>
           ) : null}
         </div>
@@ -82,7 +83,9 @@ export const HomeView = ({onOpen}: {onOpen: (view: StudioView, selection?: strin
                 />
                 <div className="card-meta">
                   <strong>{item.preview.title}</strong>
-                  <span>{item.preview.category.toLowerCase()}</span>
+                  {/* The home card names the family, not the whole path: it
+                      is a glance, not a filing cabinet. */}
+                  <span>{familyOf(categoryOf(item)).toLowerCase() || "component"}</span>
                 </div>
               </button>
             );

package/studio/src/views/VideosView.tsx

@@ -20,8 +20,10 @@ import {InputControls} from "../components/InputControls";
 import {ExportPanel} from "../components/ExportPanel";
 import {Diagnostics} from "../components/Diagnostics";
 import {Inspector} from "../components/Inspector";
+import {Navigator} from "../components/Navigator";
 import {Badge, Empty, Fact, SectionTitle, Separator} from "../components/ui";
 import {measureTrack} from "../lib/mix-loudness";
+import {readStartSound} from "../settings";
 import {useShortcuts} from "../shortcuts";
 
 /**
@@ -50,9 +52,15 @@ export const VideosView = ({
   const [timeline, setTimeline] = useState<CompiledTimeline | null>(null);
   const [track, setTrack] = useState<AudioTrack | null>(null);
   const [loop, setLoop] = useState(true);
-  const [muted, setMuted] = useState(false);
+  /* Read once per mount rather than watched: flipping the default while a
+     video is open would mute the thing being listened to, and a default is a
+     statement about what happens next. */
+  const [muted, setMuted] = useState(() => readStartSound() === "off");
   const [soloCue, setSoloCue] = useState<string | null>(null);
-  const [scrubbing, setScrubbing] = useState(false);
+  /* The frame the cursor is over, which the stage shows instead of the
+     playhead frame. Preview never moves the playhead and never sounds: it
+     answers "what is here" and nothing else. */
+  const [preview, setPreview] = useState<number | null>(null);
   const [rate, setRate] = useState(1);
   const [loudness, setLoudness] = useState<number | null>(null);
   const [audioBlocked, setAudioBlocked] = useState(false);
@@ -107,7 +115,7 @@ export const VideosView = ({
     playing: playback.playing,
     muted,
     soloCue,
-    scrubbing,
+    scrubbing: preview !== null,
     rate,
     onBlocked: setAudioBlocked,
     onFailed: setAudioFailed,
@@ -205,6 +213,25 @@ export const VideosView = ({
 
   return (
     <>
+      {/* A video id is a path under videos/, so the folder is the grouping a
+          project already chose: social/announcement sits under social. */}
+      <Navigator
+        label="Videos"
+        selected={selected.metadata.id}
+        onSelect={onSelect}
+        items={[...filtered]
+          .sort((left, right) => left.metadata.id.localeCompare(right.metadata.id))
+          .map((video) => {
+            const parts = video.metadata.id.split("/");
+            return {
+              id: video.metadata.id,
+              title: video.metadata.title,
+              detail: String(video.metadata.duration ?? "auto"),
+              group: parts.length > 1 ? parts.slice(0, -1).join(" · ") : undefined,
+            };
+          })}
+      />
+
       <section className="stage">
         <CanvasStage
           width={layout.format.width}
@@ -218,7 +245,7 @@ export const VideosView = ({
           <PreviewBoundary resetKey={selected.metadata.id}>
             <OdoriRuntime
               entry={selected}
-              frame={playback.frame}
+              frame={preview ?? playback.frame}
               input={input}
               assets={project.assets}
               onTimeline={handleTimeline}
@@ -238,7 +265,7 @@ export const VideosView = ({
           audioBlocked={audioBlocked}
           onEnableAudio={() => setMuted(false)}
           onSoloCue={setSoloCue}
-          onScrubbing={setScrubbing}
+          onPreview={setPreview}
           rate={rate}
           onRate={setRate}
           onToggleLoop={() => setLoop((value) => !value)}
@@ -246,7 +273,7 @@ export const VideosView = ({
         />
       </section>
 
-      <Inspector title={selected.metadata.title} hint={file}>
+      <Inspector title={selected.metadata.title} hint={file} source={file}>
         {/* Export sits first: it is the pane's one action, and the header
             names what is being worked on right above it. */}
         <ExportPanel

package/studio/src/virtual.d.ts

@@ -10,6 +10,9 @@ declare module "virtual:odori-project" {
   export const project: {
     root: string;
     videosDir: string;
+    componentsDir: string;
+    /** Directories that named themselves, from `category.json`. */
+    categories: Array<{path: string; name?: string; order?: number}>;
     docsUrl: string;
     exportDir: string;
     audioDir: string;
@@ -18,7 +21,7 @@ declare module "virtual:odori-project" {
     assets: Array<{reference: string; url: string}>;
     files: {
       videos: Array<{id: string; file: string}>;
-      previews: Array<{id: string; file: string}>;
+      previews: Array<{id: string; file: string; usedBy: string[]}>;
       brands: Array<{id: string; file: string}>;
     };
   };