@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/rail.json

@@ -0,0 +1,255 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioRail",
+  "$description": "The Navigator rail: a rendering of the panel registry. The adapter hands in `groups`, every rail-able panel grouped by level with its selected state and badge, and `settingsVisible`/`settingsOpen` for the foot's gear. Nothing here is a list of panels.",
+  "tagName": "div",
+  "attributes": {
+    "part": "rail"
+  },
+  "style": {
+    "display": "flex",
+    "flexDirection": "column",
+    "height": "100%",
+    "& > [part=\"groups\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "padding": "var(--jx-space-2) 0"
+    },
+    "& [role=\"group\"]": {
+      "display": "flex",
+      "flexDirection": "column"
+    },
+    "& jx-divider": {
+      "$description": "The element draws the hairline and announces it; what the rail owns is where it sits. The rule outranks `jx-divider`'s own margin by one element in the selector, which is the sanctioned way a host retunes a kit element (ui.md §3.2) and the reason the divider's spacing is on its HOST rather than on the rule inside it.",
+      "margin": "var(--jx-space-3) var(--jx-space-4)"
+    },
+    "& > [part=\"foot\"]": {
+      "marginTop": "auto",
+      "display": "flex",
+      "flexDirection": "column",
+      "padding": "var(--jx-space-3) 0"
+    },
+    "& jx-action-button": {
+      "width": "100%"
+    },
+    "& jx-action-button > [part=\"control\"]": {
+      "borderLeft": "2px solid transparent",
+      "opacity": "0.75",
+      ":hover": {
+        "opacity": "1"
+      }
+    },
+    "& jx-action-button[data-selected] > [part=\"control\"]": {
+      "borderLeftColor": "var(--jx-accent)",
+      "background": "transparent",
+      "color": "var(--jx-fg)",
+      "opacity": "1"
+    },
+    "& jx-action-button[data-expanded] > [part=\"control\"]": {
+      "background": "var(--jx-hover-bg)",
+      "color": "var(--jx-fg)",
+      "opacity": "1"
+    }
+  },
+  "children": [
+    {
+      "tagName": "nav",
+      "attributes": {
+        "part": "groups",
+        "aria-label": "Navigator panels"
+      },
+      "children": [
+        {
+          "$prototype": "Array",
+          "items": {
+            "$ref": "#/state/groups"
+          },
+          "key": {
+            "$ref": "$map/item/level"
+          },
+          "map": {
+            "tagName": "div",
+            "attributes": {
+              "role": "none"
+            },
+            "children": [
+              {
+                "tagName": "div",
+                "attributes": {
+                  "role": "none"
+                },
+                "$switch": {
+                  "$ref": "$map/item/dividerAbove"
+                },
+                "cases": {
+                  "true": {
+                    "tagName": "jx-divider"
+                  }
+                }
+              },
+              {
+                "tagName": "div",
+                "attributes": {
+                  "role": "group",
+                  "aria-label": "${$map.item.label}"
+                },
+                "children": [
+                  {
+                    "$prototype": "Array",
+                    "items": {
+                      "$ref": "$map/item/panels"
+                    },
+                    "key": {
+                      "$ref": "$map/item/id"
+                    },
+                    "map": {
+                      "tagName": "jx-action-button",
+                      "$props": {
+                        "label": {
+                          "$ref": "$map/item/title"
+                        },
+                        "hint": {
+                          "$ref": "$map/item/title"
+                        },
+                        "icon": {
+                          "$ref": "$map/item/icon"
+                        },
+                        "stacked": true,
+                        "toggles": true,
+                        "selected": {
+                          "$ref": "$map/item/selected"
+                        },
+                        "badge": {
+                          "$ref": "$map/item/badge"
+                        }
+                      },
+                      "attributes": {
+                        "data-panel": "${$map.item.id}"
+                      },
+                      "onchange": {
+                        "$prototype": "Function",
+                        "body": [
+                          {
+                            "operator": "call",
+                            "target": {
+                              "$ref": "#/state/toggle"
+                            },
+                            "value": [
+                              {
+                                "$ref": "$map/item/id"
+                              }
+                            ]
+                          }
+                        ]
+                      },
+                      "children": [
+                        {
+                          "tagName": "span",
+                          "textContent": "${$map.item.title}"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "foot"
+      },
+      "$switch": {
+        "$ref": "#/state/settingsVisible"
+      },
+      "cases": {
+        "true": {
+          "tagName": "jx-action-button",
+          "$props": {
+            "label": "Settings",
+            "hint": "Settings",
+            "icon": "gear",
+            "stacked": true,
+            "haspopup": "menu",
+            "expanded": {
+              "$ref": "#/state/settingsOpen"
+            }
+          },
+          "attributes": {
+            "data-rail-menu": "settings",
+            "data-expanded": "${state.settingsOpen ? '' : null}"
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/openSettings"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/currentTarget"
+                  }
+                ]
+              }
+            ]
+          },
+          "onkeydown": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "$switch": {
+                  "$ref": "event#/key"
+                },
+                "cases": {
+                  "ArrowUp": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/openSettings"
+                      },
+                      "value": [
+                        {
+                          "$ref": "event#/currentTarget"
+                        }
+                      ]
+                    },
+                    {
+                      "preventDefault": true
+                    }
+                  ],
+                  "ArrowDown": [
+                    {
+                      "operator": "call",
+                      "target": {
+                        "$ref": "#/state/openSettings"
+                      },
+                      "value": [
+                        {
+                          "$ref": "event#/currentTarget"
+                        }
+                      ]
+                    },
+                    {
+                      "preventDefault": true
+                    }
+                  ]
+                }
+              }
+            ]
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "Settings"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/src/surfaces/rail.ts

@@ -0,0 +1,206 @@
+/**
+ * The Navigator rail — the `rail` surface, rendered FROM the panel registry.
+ *
+ * There is no list of panels here. `railGroups()` returns every rail-able record grouped by level
+ * and filtered by its own `when`, and the surface draws whatever that says: two groups with a
+ * divider between them, PROJECT above and DOCUMENT below. Adding a panel is a `registerPanel()`
+ * call in the module that owns it, and it appears here; there is nothing to update in step.
+ *
+ * **Every rail button opens the Navigator, and the grouping is by LEVEL.** Every button is a
+ * `jx-action-button` in its stacked form, so it carries an 11px text label under its icon — an icon
+ * whose only name is a hover tooltip is the accessibility failure §2 principle 6 names — and
+ * `aria-pressed` states the toggle-focus semantics honestly: re-picking the open panel collapses
+ * its dock, which is a two-state control, not a one-way selection.
+ *
+ * The foot is the ⚙ **Settings** menu, a menu button rendered from the `settings/menu` placement: a
+ * record joins the gear by declaring the placement and there is nothing here to update in step.
+ * With no registry, or one that declares nothing for it, there is no foot.
+ *
+ * What this adapter owns is the projection and the two decisions: which panel a button toggles, and
+ * where the gear's menu opens. The scope is reactive, so the surface follows `shell` through one
+ * effect that recomputes the projection; nothing repaints.
+ *
+ * @docs studio/interface
+ */
+import { activityBar } from "../store";
+import { effect, effectScope, reactive } from "../reactivity";
+import { requireNavigatorPanelId, shell, toggleActivityTab } from "../shell";
+import { refreshGitStatus } from "../panels/git-panel";
+import { panelContext, railGroups } from "../panels/panel-registry";
+import { registerNavigatorPanels } from "../panels/navigator-panels";
+import { activeRegistry } from "../commands/active-registry";
+import {
+  dismissSettingsMenu,
+  isSettingsMenuOpen,
+  openSettingsMenu,
+  SETTINGS_MENU_PLACEMENT,
+} from "../panels/settings-menu";
+import { mountSurface, registerSurface } from "../ui/surface";
+import railDoc from "./rail.json";
+
+import type { EffectScope } from "@vue/reactivity";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { PanelRecord } from "../panels/panel-registry";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("rail", railDoc as unknown as JxDocument);
+
+/** One rail button, as the surface reads it. */
+interface RailButton {
+  id: string;
+  title: string;
+  icon: string;
+  selected: boolean;
+  /** The badge text; empty for none. */
+  badge: string;
+}
+
+interface RailGroupProjection {
+  level: string;
+  label: string;
+  dividerAbove: boolean;
+  panels: RailButton[];
+}
+
+interface RailScope extends Record<string, unknown> {
+  groups: RailGroupProjection[];
+  settingsVisible: boolean;
+  settingsOpen: boolean;
+  toggle: (id: string) => void;
+  openSettings: (anchor: unknown) => void;
+}
+
+let _scope: EffectScope | null = null;
+let _state: RailScope | null = null;
+let _mount: Promise<SurfaceHandle> | null = null;
+let _handle: SurfaceHandle | null = null;
+
+/**
+ * Whether a rail button is showing what it names — its dock open, on its tab.
+ *
+ * @param {PanelRecord} panel
+ */
+export function isRailPanelShowing(panel: PanelRecord): boolean {
+  return !shell.docks.left.collapsed && shell.leftTab === panel.id;
+}
+
+/**
+ * Reveal (or collapse) what a rail button names.
+ *
+ * There is no per-dock branch, because every rail button opens the Navigator. `PanelRecord.id` is a
+ * `string` because the same registry hosts the Bottom dock's panels; the rail only ever draws
+ * Navigator ones, and `requireNavigatorPanelId` is the shared lock that says so out loud rather
+ * than letting an undeclared id reach `shell.leftTab`.
+ *
+ * @param {PanelRecord} panel
+ */
+export function toggleRailPanel(panel: PanelRecord): void {
+  toggleActivityTab(requireNavigatorPanelId(panel.id, "the Navigator rail"));
+}
+
+/** The rail, as the surface reads it, from the registry and the shell as they stand now. */
+function project(): { groups: RailGroupProjection[]; settingsVisible: boolean } {
+  const ctx = panelContext();
+  const groups = railGroups(ctx).map((group, index) => ({
+    dividerAbove: index > 0,
+    label: group.label,
+    level: group.level,
+    panels: group.panels.map((panel) => ({
+      badge: String(panel.badge?.(ctx) ?? ""),
+      icon: panel.icon,
+      id: panel.id,
+      selected: isRailPanelShowing(panel),
+      title: panel.title,
+    })),
+  }));
+  const registry = activeRegistry();
+  const settingsVisible =
+    registry !== null && registry.forPlacement(SETTINGS_MENU_PLACEMENT).length > 0;
+  return { groups, settingsVisible };
+}
+
+/** The reactive scope the surface reads, made once. */
+function state(): RailScope {
+  _state ??= reactive({
+    groups: [],
+    openSettings: (anchor: unknown) => {
+      if (!(anchor instanceof HTMLElement)) {
+        return;
+      }
+      openSettingsMenu(anchor, {
+        rerender: () => {
+          if (_state) {
+            _state.settingsOpen = isSettingsMenuOpen();
+          }
+        },
+      });
+    },
+    settingsOpen: false,
+    settingsVisible: false,
+    toggle: (id: string) => {
+      const panel = railGroups(panelContext())
+        .flatMap((group) => group.panels)
+        .find((candidate) => candidate.id === id);
+      if (panel) {
+        toggleRailPanel(panel);
+      }
+    },
+  }) as RailScope;
+  return _state;
+}
+
+/** Recompute the projection from the registry and the shell; the surface follows. */
+export function renderActivityBar(): void {
+  const scope = state();
+  const next = project();
+  scope.groups = next.groups;
+  scope.settingsVisible = next.settingsVisible;
+  scope.settingsOpen = isSettingsMenuOpen();
+  ensureMounted();
+}
+
+/** Mount the surface into the rail host, once. */
+function ensureMounted(): void {
+  if (_mount || !activityBar) {
+    return;
+  }
+  _mount = mountSurface("rail", state(), activityBar);
+  void _mount.then((handle) => {
+    _handle = handle;
+  });
+}
+
+export function mount(): void {
+  // The rail is a rendering of the registry, so the registry has to exist before the first paint.
+  // Idempotent, and the Navigator dock calls it too — whichever mounts first wins.
+  registerNavigatorPanels();
+  _scope = effectScope();
+  _scope.run(() => {
+    effect(() => {
+      // Source control is PROJECT state, so the badge is fetched and drawn without reference to
+      // Any tab. The badge needs a status once. A refresh that already failed must not re-arm this:
+      // The effect re-runs on the very state the failure writes, so retrying here spins.
+      const { error, loading, status } = shell.git;
+      if (!status && !loading && !error) {
+        void refreshGitStatus();
+      }
+      renderActivityBar();
+    });
+  });
+}
+
+export function unmount(): void {
+  dismissSettingsMenu();
+  _scope?.stop();
+  _scope = null;
+  const pending = _mount;
+  _mount = null;
+  if (_handle) {
+    _handle.dispose();
+    _handle = null;
+  } else if (pending) {
+    // Mounting still in flight: dispose it the moment it lands.
+    void pending.then((handle) => handle.dispose());
+  }
+  _state = null;
+}

package/src/surfaces/reference-field.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioReferenceField",
+  "$description": "The `reference` form control — site-architecture.md §6.1's `{ \"$ref\": \"#/content/x\" }` and §7.4's entry picker. Registered once and dispatched to by `ui/schema-form.ts` for any property whose `$ref` names a collection, so the settings forms, the entry editor and an array-of-objects cell all draw the same control without any of them knowing it exists. `ui/form-controls.ts` decides which of the three states the field is in and what each gesture commits; nothing here reads a schema or lists a directory. The three states are drawn as three different controls on purpose: a picker while the entries are known, a TEXT field while they are not — a failed read leaves the value editable with the reason beside it, because swapping it for an empty dropdown would present \"no entries\" and \"could not find out\" as the same screen — and a disabled picker saying so while the read is in flight.",
+  "tagName": "div",
+  "attributes": {
+    "part": "reference",
+    "role": "none"
+  },
+  "style": {
+    "$description": "The five `.reference-*` rules from `styles/inspector.css`, keyed on `part` and re-pointed at the studio token layer. Two values could not come with them. The note read `var(--spectrum-font-size-50, 11px)`, which resolves only inside `<sp-theme>` — this document is mounted in a settings pane, an entry editor or a frontmatter card, all outside that element, so it would silently have taken its hard-coded fallback every time. And `.reference-missing` coloured ONE row of the dropdown red; the kit's select offers a row a face, a swatch and a border style but no tone, so the dangling entry says what it is in words (\"— not found\") and the colour is not replaced by a second channel. The 6px gap comes onto the kit's spacing scale.",
+    "display": "flex",
+    "flex": "1",
+    "minWidth": "0",
+    "alignItems": "center",
+    "gap": "var(--jx-space-2)",
+    "& [part=\"picker\"], & [part=\"text\"]": {
+      "flex": "1",
+      "minWidth": "0"
+    },
+    "& [part=\"note\"]": {
+      "margin": "0",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)",
+      "lineHeight": "1.4"
+    },
+    "& [part=\"note\"][data-tone=\"danger\"]": {
+      "$description": "A listing that failed is a FAULT rather than a fact about the project, and the two notes this control draws are otherwise the same sentence in the same place.",
+      "color": "var(--danger)"
+    },
+    "& [part=\"retry\"]": {
+      "flex": "none"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "control-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/kind"
+      },
+      "cases": {
+        "picker": {
+          "$description": "The collection's entries. The empty row is `\"\"` rather than a sentinel, because the kit's select treats the empty string as a legal value a reader can arrow to; a dangling reference is kept in the list and marked, since blanking the field would delete the evidence and the value in one repaint. While the read is in flight the same control is disabled and offers one row saying so.",
+          "tagName": "jx-select",
+          "attributes": {
+            "part": "picker"
+          },
+          "$props": {
+            "size": "sm",
+            "label": {
+              "$ref": "#/state/label"
+            },
+            "options": {
+              "$ref": "#/state/options"
+            },
+            "value": {
+              "$ref": "#/state/value"
+            },
+            "disabled": {
+              "$ref": "#/state/disabled"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/choose"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        "text": {
+          "$description": "The id as the string it is: what a reader gets when the choices could not be listed, and when the control was named by a `ui.control` override on a property that references nothing. Refusing to draw anything would lose the value that is already there.",
+          "tagName": "jx-textfield",
+          "attributes": {
+            "part": "text"
+          },
+          "$props": {
+            "size": "sm",
+            "label": {
+              "$ref": "#/state/label"
+            },
+            "value": {
+              "$ref": "#/state/value"
+            }
+          },
+          "onchange": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/edit"
+                },
+                "value": [
+                  {
+                    "$ref": "event#/target/value"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "note-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/hasNote"
+      },
+      "cases": {
+        "true": {
+          "tagName": "p",
+          "attributes": {
+            "part": "note",
+            "data-tone": "${state.noteTone}",
+            "role": "status"
+          },
+          "textContent": "${state.note}"
+        }
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "retry-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/canRetry"
+      },
+      "cases": {
+        "true": {
+          "$description": "Offered only where there is something to try again — a listing that failed. It used to be offered only where the HOST passed a repaint hook, because a template control cannot draw a second frame of its own and a button that cannot do the thing it is named after is worse than its absence. A mounted control redraws itself, so the condition is now the failure rather than the host.",
+          "tagName": "jx-action-button",
+          "attributes": {
+            "part": "retry"
+          },
+          "$props": {
+            "size": "sm",
+            "quiet": true,
+            "label": "Retry listing entries"
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/retry"
+                },
+                "value": []
+              }
+            ]
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "Retry"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}