@odori/cli 0.0.3 → 0.0.4

package/studio/src/studio.css

@@ -153,6 +153,18 @@ body.render-mode {
   background-clip: content-box;
 }
 
+/* Anything you click says so, once, rather than per control. */
+button:not(:disabled),
+[role="button"]:not([aria-disabled="true"]),
+summary {
+  cursor: pointer;
+}
+
+button:disabled,
+[role="button"][aria-disabled="true"] {
+  cursor: not-allowed;
+}
+
 /* ---------- primitives ---------- */
 
 .button {
@@ -485,19 +497,93 @@ select.input {
 
 .main {
   display: grid;
-  /* A detail is the stage and the inspector; galleries and pages are one
-     column. The inspector's column is a root variable so its drag handle can
-     resize it without React re-laying anything out. */
-  grid-template-columns: minmax(0, 1fr) clamp(240px, var(--inspector-width, 320px), 50vw);
+  /* A detail is a list, a stage, and an inspector; galleries and pages are one
+     column. The side columns size to their contents, so a panel that puts
+     itself away takes its column with it and the stage grows into the gap
+     without a rule per combination of what is open. The inspector's width is
+     a root variable so its drag handle can resize it without React re-laying
+     anything out. */
+  grid-template-columns: auto minmax(0, 1fr) auto;
   overflow: hidden;
 }
 .main[data-single="true"] {
   grid-template-columns: 1fr;
 }
 
+/* ---------- navigator ---------- */
+
+.navigator {
+  background: var(--panel);
+  border-right: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  width: 232px;
+}
+.navigator-head {
+  align-items: center;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  gap: 6px;
+  padding: 10px;
+}
+.navigator-search {
+  height: 28px;
+  font-size: 12px;
+  min-width: 0;
+}
+.navigator-scroll {
+  overflow-y: auto;
+  padding: 10px;
+  scrollbar-gutter: stable;
+}
+.navigator-group {
+  color: var(--subtle);
+  font-size: 11px;
+  font-weight: 500;
+  letter-spacing: 0.04em;
+  margin: 10px 0 4px 2px;
+  text-transform: uppercase;
+}
+.navigator-scroll > div:first-child .navigator-group {
+  margin-top: 0;
+}
+.navigator-empty {
+  padding: 4px 2px;
+}
+.navigator-toggle,
+.navigator-reopen {
+  align-items: center;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--radius-sm);
+  color: var(--muted);
+  cursor: pointer;
+  display: inline-flex;
+  flex: none;
+  height: 28px;
+  justify-content: center;
+  width: 28px;
+}
+.navigator-toggle:hover,
+.navigator-reopen:hover {
+  background: var(--hover);
+  color: var(--foreground);
+}
+/* Away, the way back floats where the list was. */
+.navigator-reopen {
+  background: var(--panel);
+  border-color: var(--border);
+  left: 10px;
+  position: fixed;
+  top: 58px;
+  z-index: 5;
+}
+
 .inspector {
   background: var(--panel);
   border-left: 1px solid var(--border);
+  width: clamp(240px, var(--inspector-width, 320px), 50vw);
   container-type: inline-size;
   display: flex;
   overflow: hidden;
@@ -507,6 +593,11 @@ select.input {
   flex: 1;
   overflow-y: auto;
   padding: 16px;
+  /* The gutter is reserved whether or not it is used. Code is taller than the
+     facts it replaces, so switching to it summoned a scrollbar, and the ten
+     pixels that took came out of the content: the header's controls jumped
+     sideways every time you changed face. */
+  scrollbar-gutter: stable;
 }
 
 
@@ -526,6 +617,127 @@ select.input {
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+/* Two views of one selection, not two modes: the segmented control sits in
+   the pane's own header rather than above the whole app. */
+.inspector-views {
+  background: var(--hover);
+  border-radius: var(--radius-sm);
+  display: flex;
+  flex: none;
+  gap: 2px;
+  margin-left: auto;
+  padding: 2px;
+}
+.inspector-views button {
+  background: transparent;
+  border: 0;
+  border-radius: calc(var(--radius-sm) - 1px);
+  color: var(--muted);
+  cursor: pointer;
+  font: inherit;
+  font-size: 11px;
+  padding: 3px 9px;
+}
+.inspector-views button:hover {
+  color: var(--foreground);
+}
+/* A lift off the track it sits in, and nothing else. The weight and the
+   border this used to add both changed the button's size, so selecting one
+   nudged the other sideways: emphasis has to come from colour alone, or the
+   control moves while you read it. */
+.inspector-views button[data-active="true"] {
+  background: color-mix(in srgb, var(--foreground) 10%, var(--hover));
+  color: var(--foreground);
+}
+
+/* Which of a component's files is being read. */
+.source-files {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-bottom: 10px;
+}
+.source-files button {
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--muted);
+  font-family: var(--font-mono);
+  font-size: 11px;
+  padding: 3px 10px;
+}
+.source-files button:hover {
+  color: var(--foreground);
+}
+.source-files button[data-active="true"] {
+  background: var(--hover);
+  border-color: var(--border-strong);
+  color: var(--foreground);
+}
+
+/*
+ * Token colours, taken from the same GitHub themes the docs site highlights
+ * with, so a component's source reads the same in both places.
+ */
+:root {
+  --token-comment: #6e7781;
+  --token-string: #0a3069;
+  --token-keyword: #cf222e;
+  --token-number: #0550ae;
+  --token-tag: #116329;
+  --token-attr: #953800;
+  --token-fn: #8250df;
+}
+:root[data-theme="dark"] {
+  --token-comment: #8b949e;
+  --token-string: #a5d6ff;
+  --token-keyword: #ff7b72;
+  --token-number: #79c0ff;
+  --token-tag: #7ee787;
+  --token-attr: #ffa657;
+  --token-fn: #d2a8ff;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --token-comment: #8b949e;
+    --token-string: #a5d6ff;
+    --token-keyword: #ff7b72;
+    --token-number: #79c0ff;
+    --token-tag: #7ee787;
+    --token-attr: #ffa657;
+    --token-fn: #d2a8ff;
+  }
+}
+
+.source [data-token="comment"] { color: var(--token-comment); font-style: italic; }
+.source [data-token="string"] { color: var(--token-string); }
+.source [data-token="keyword"] { color: var(--token-keyword); }
+.source [data-token="number"] { color: var(--token-number); }
+.source [data-token="tag"] { color: var(--token-tag); }
+.source [data-token="attr"] { color: var(--token-attr); }
+.source [data-token="fn"] { color: var(--token-fn); }
+.source [data-token="punct"] { color: var(--muted); }
+
+/*
+ * Code scrolls the full width of the pane. The inspector pads its content by
+ * sixteen, which is right for prose and wrong for a scrolling region: it left
+ * a gutter the code could not reach, so a long line appeared to stop short of
+ * an edge it had not reached. The negative margin gives the scroller the whole
+ * pane and the padding puts the text back where it was.
+ */
+.source {
+  color: var(--foreground);
+  font-family: var(--font-mono);
+  font-size: 11px;
+  line-height: 1.65;
+  margin: 0 -16px;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  padding: 0 16px;
+  tab-size: 2;
+  white-space: pre;
+}
+
 .inspector-toggle,
 .inspector-reopen {
   align-items: center;
@@ -556,9 +768,7 @@ select.input {
 }
 
 /* A collapsed inspector hands its column to the stage. */
-html[data-inspector="collapsed"] .main:not([data-single="true"]) {
-  grid-template-columns: minmax(0, 1fr);
-}
+/* Panels carry their own width now, so collapsing one needs no grid rule. */
 .inspector-resize {
   cursor: col-resize;
   /* Fully inside the pane: the inspector clips overflow, and a handle hung
@@ -630,6 +840,33 @@ html[data-inspector="collapsed"] .main:not([data-single="true"]) {
   }
 }
 
+/* Filter the catalog by the video a component is actually used in. */
+.catalog-filter {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 16px 20px 0;
+}
+.catalog-filter button {
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--muted);
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  padding: 4px 12px;
+}
+.catalog-filter button:hover {
+  border-color: var(--border-strong);
+  color: var(--foreground);
+}
+.catalog-filter button[data-active="true"] {
+  background: var(--hover);
+  border-color: var(--border-strong);
+  color: var(--foreground);
+}
+
 /* A gallery page or an explainer page: one scrolling column with a readable
    lead-in. */
 .page {
@@ -1263,6 +1500,16 @@ html[data-inspector="collapsed"] .main:not([data-single="true"]) {
   color: var(--foreground);
 }
 
+/* A drawer inside a family. Quieter than the family it sits under, and
+   indented enough that the nesting reads without a rule to draw it. */
+.group-title {
+  color: var(--muted);
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: -0.01em;
+  margin: 2px 0 8px;
+}
+
 /* ---------- home ---------- */
 
 .home {

package/studio/src/views/BrandsView.tsx

@@ -13,6 +13,7 @@ import {CanvasStage} from "../components/CanvasStage";
 import {Transport} from "../components/Transport";
 import {Empty, Fact, SectionTitle, Separator} from "../components/ui";
 import {Inspector} from "../components/Inspector";
+import {Navigator} from "../components/Navigator";
 import {useShortcuts} from "../shortcuts";
 
 /** Brands come from videos/**\/brands modules and from every resolved layout. */
@@ -101,9 +102,21 @@ export const BrandsView = ({
   }
 
   const layout = defineVideoLayout({extends: base, brand});
+  const brandFile = project.files.brands.find((item) => item.id === brand.name)?.file;
 
   return (
     <>
+      <Navigator
+        label="Brands"
+        selected={brand.name}
+        onSelect={onSelect}
+        items={brands.map((item) => ({
+          id: item.name,
+          title: item.name,
+          detail: `${Object.keys(item.audio.cues).length} cues · ${item.audio.targetLufs} LUFS`,
+        }))}
+      />
+
       <section className="stage">
         <CanvasStage width={layout.format.width} height={layout.format.height}>
           <OdoriRuntime
@@ -125,7 +138,11 @@ export const BrandsView = ({
         />
       </section>
 
-      <Inspector title={brand.name} hint={project.files.brands.find((item) => item.id === brand.name)?.file}>
+      <Inspector
+        title={brand.name}
+        hint={brandFile}
+        source={brandFile}
+      >
         <SectionTitle>Preview with</SectionTitle>
         <ul className="list">
           {videos.map((video) => (

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>
             );