@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/style-panel.ts

@@ -0,0 +1,338 @@
+/// <reference lib="dom" />
+/**
+ * The Inspector's Style tab, as a Jx document over the kit.
+ *
+ * This is the adapter. `panels/style-panel.ts` keeps every decision — which compound coordinate the
+ * tab is editing, what css-meta says a property is, where a value came from, what a commit writes
+ * and into how many elements — and hands this module one projection whose every field is already a
+ * string, a boolean or a list of them. The document draws it and decides nothing.
+ *
+ * **One seam, and it is announced rather than queried** (specs/studio-ui-guidelines.md §9.4). The
+ * Target Line is its own document and cannot share a container with this one, so the tab draws an
+ * empty `[part="target-host"]` and the runtime reports it through `onNodeCreated` as it is made.
+ * There was a second: a colour row drew an empty `[part="control-host"]` a lit island filled,
+ * because the kit's colour elements were `ui.md` §5.6 and §5.6 was Pending. It landed, the row is a
+ * `jx-color-field` in the document beside every other control, and the sink that carried it is gone
+ * with it.
+ *
+ * **The mount is only ever ASSIGNED to.** A repaint that rebuilt it would take the field a reader
+ * is typing into out from under them, which is the whole reason the lit panel needed
+ * `panels/panel-scheduler.ts`'s focus guard and the reason this one is not allowed near it.
+ *
+ * @docs studio/design/style-inspector
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import stylePanelDoc from "./style-panel.json";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("style-panel", stylePanelDoc as unknown as JxDocument);
+
+// ─── The projection ──────────────────────────────────────────────────────────
+
+/** Which control a row draws. The flow picks it; the document switches on it. */
+export type StyleWidgetKind =
+  | "text"
+  | "number"
+  | "keywords"
+  | "group"
+  | "buttons"
+  | "color"
+  | "shorthand"
+  | "kv"
+  | "kvadd"
+  | "nested"
+  | "nestedadd";
+
+/** What a row IS, independently of what it draws — the identity a screenshot region reads. */
+export type StyleRowKind =
+  | "field"
+  | "shorthand"
+  | "custom"
+  | "custom-add"
+  | "nested"
+  | "nested-add";
+
+/** How the provenance chip is drawn: not at all, as a control, or as a statement. */
+export type StyleChipControl = "none" | "button" | "text";
+
+/**
+ * One colour the project has named, as the row's palette draws it.
+ *
+ * `value` is the reference and `color` is the literal behind it, and they are two fields because
+ * they are two things: choosing a swatch commits `var(--color-accent)`, while the chip is only how
+ * that reads on screen. `label` is what a reader hears — a swatch is never named by its hex.
+ */
+export interface StyleTokenView extends Record<string, unknown> {
+  value: string;
+  color: string;
+  label: string;
+}
+
+/**
+ * One keyword a `keywords` row lists under its field.
+ *
+ * `value` is what the row commits and `label` is how it reads — `Inline block` over `inline-block`
+ * — and the two stay separate because the field holds the value: a combobox row's label is a
+ * courtesy, never a second spelling the reader could end up with.
+ */
+export interface StyleOptionView extends Record<string, unknown> {
+  value: string;
+  label: string;
+  /** A muted note at the end of the row — a font token's own name beside its display name. */
+  description?: string;
+  /**
+   * The `jx-option` drawing channels (ui.md §5.3), for a row that is its own preview: the font
+   * family the words are set in, and the typographic axis the row's value would move. A weight row
+   * carries `weight: "700"` and the element's own `face`, so its `700` reads as 700 in that face.
+   */
+  face?: string;
+  weight?: string;
+  slant?: string;
+  variant?: string;
+  transform?: string;
+  decoration?: string;
+}
+
+/** One value of a button-group row. */
+export interface StyleButtonView extends Record<string, unknown> {
+  /** The owning row's key — a nested `$map` shadows `$map.item`, so the row carries it here. */
+  row: string;
+  /** The CSS value this button commits, and the button's identity in the repeater. */
+  value: string;
+  /** The accessible name and tooltip. */
+  title: string;
+  /** A kit glyph name, or the empty string where the kit has none for this value. */
+  icon: string;
+  /** The abbreviation drawn when there is no glyph. Empty when there is one. */
+  text: string;
+  selected: boolean;
+}
+
+/**
+ * One row of the tab, as the document reads it.
+ *
+ * Every field is present on every row whatever its `widget`, because a binding renders a value and
+ * a `$switch` chooses on one: a row that omitted `buttons` would leave that case reading an absent
+ * path. `key` is the identity — the repeater's key and the argument every action is given — and
+ * `prop` is the name a reader, the region grammar and the inspector see. The two are different on
+ * purpose: one coordinate's `color` and another's are two rows with one name.
+ */
+export interface StyleRowView extends Record<string, unknown> {
+  key: string;
+  prop: string;
+  label: string;
+  kind: StyleRowKind;
+  widget: StyleWidgetKind;
+  /** A longhand under an expanded shorthand — indented, and it carries no Value Source chip. */
+  child: boolean;
+  /** A value whose `$show` condition no longer passes: it is set, and it cannot apply. */
+  warning: boolean;
+  /** Span both columns of a grid section. */
+  span: boolean;
+  /** Whether the row draws a label line at all — the add-a-property field does not. */
+  hasLabel: boolean;
+  chip: StyleChipControl;
+  chipState: string;
+  chipText: string;
+  chipTitle: string;
+  /** The Value Source chip (§6.3). Absent on a child, a custom pair and a nested rule. */
+  hasSource: boolean;
+  sourceState: string;
+  sourceLabel: string;
+  sourceHint: string;
+  /** The control's value, always as a string. */
+  value: string;
+  /**
+   * A colour row whose value is a token reference: the literal behind it, so the field's chip can
+   * draw a colour this page cannot resolve. Empty on every other row and for a literal value.
+   */
+  resolved: string;
+  placeholder: string;
+  mono: boolean;
+  min: string;
+  max: string;
+  step: string;
+  /**
+   * The keywords a `keywords` row suggests. The field is free text over them: an enum is the values
+   * worth offering, not a whitelist, so the list never refuses what the reader typed.
+   */
+  options: StyleOptionView[];
+  /** Whether the row offers a list beside its field — units, fonts, or a button overflow. */
+  hasChoices: boolean;
+  /** The chooser's own label: the current unit, a chevron, or the overflow glyph's name. */
+  choicesLabel: string;
+  choicesHint: string;
+  buttons: StyleButtonView[];
+  /** The palette a colour row offers inside its picker, and whether it has one to offer. */
+  tokens: StyleTokenView[];
+  hasTokens: boolean;
+  overflowSelected: boolean;
+  expanded: boolean;
+  expandIcon: string;
+  expandLabel: string;
+  /** A custom pair's key cell, or a nested rule's selector. */
+  name: string;
+  removeLabel: string;
+  openTitle: string;
+}
+
+/** One accordion section. */
+export interface StyleSectionView extends Record<string, unknown> {
+  key: string;
+  label: string;
+  open: boolean;
+  /** `grid` lays the rows in two columns — the Size section, and nothing else. */
+  layout: string;
+  /** The inert half of the heading tally: one mark per informative state present. */
+  marks: { state: string }[];
+  /** Whether {@link StyleSectionView.marks} has anything in it — an empty tally draws nothing. */
+  hasMarks: boolean;
+  /** "3 set here · 2 inherited" — the sentence the retired Active toggle used to answer by hiding. */
+  tally: string;
+  /** Whether anything in the section can be cleared, which is what makes the accent dot a control. */
+  canClear: boolean;
+  clearTitle: string;
+  rows: StyleRowView[];
+}
+
+/** What the tab is showing right now. */
+export interface StylePanelView {
+  /** `empty` draws a teaching state; `editor` draws the Target Line, the filter and the sections. */
+  view: "empty" | "editor";
+  emptyMessage: string;
+  hasEmptyAction: boolean;
+  emptyActionLabel: string;
+  filter: string;
+  sections: StyleSectionView[];
+}
+
+/**
+ * What the reader can do here. Every one of them names a row by its `key`, never by its `prop`: the
+ * flow decides what a key commits into, and two rows may legitimately share a name.
+ */
+export interface StylePanelActions {
+  /** The empty state's one button. */
+  runEmptyAction: () => void;
+  setFilter: (value: string) => void;
+  toggleSection: (key: string, open: boolean) => void;
+  clearSection: (key: string) => void;
+  /** The reader is typing: commit after a pause, so the canvas follows without a write per key. */
+  editText: (key: string, value: string) => void;
+  /** The reader left the field or pressed Enter: commit now, cancelling any pending write. */
+  commitText: (key: string, value: string) => void;
+  /** The provenance chip, a custom pair's remove and a nested rule's remove are one verb. */
+  chipClick: (key: string) => void;
+  /** Open the Value Source picker under the chip that was pressed. */
+  pickSource: (key: string, anchor: unknown) => void;
+  /** Open the row's list of offerable values under the button that was pressed. */
+  pickChoice: (key: string, anchor: unknown) => void;
+  pressButton: (key: string, value: string) => void;
+  toggleShorthand: (key: string) => void;
+  renameCustom: (key: string, name: string) => void;
+  /** Enter in the add-a-property field. Given the field too, because it is emptied on success. */
+  addCustom: (key: string, field: unknown) => void;
+  openNested: (key: string) => void;
+  addNested: () => void;
+}
+
+/** Where the one announced host belongs. */
+export interface StyleHostSink {
+  /** The Target Line's container, as it is created — and `null` when the document is taken down. */
+  target: (host: HTMLElement | null) => void;
+}
+
+export interface StylePanelSurface {
+  /** Bring the standing document up to date. */
+  update: (view: StylePanelView) => void;
+  /** Whether the document this mounted is still standing in the host it was given. */
+  connected: () => boolean;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope the document reads: the view plus the actions, flat. */
+interface StylePanelScope extends Record<string, unknown>, StylePanelView, StylePanelActions {}
+
+/** A node definition's `part`, as written in the document. */
+function partOf(def: JxElement | string): string {
+  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
+  return typeof part === "string" ? part : "";
+}
+
+/** Write a whole view into the scope. Assignment only — the mount is never rebuilt for a repaint. */
+function project(scope: StylePanelScope, view: StylePanelView): void {
+  scope.view = view.view;
+  scope.emptyMessage = view.emptyMessage;
+  scope.hasEmptyAction = view.hasEmptyAction;
+  scope.emptyActionLabel = view.emptyActionLabel;
+  scope.filter = view.filter;
+  scope.sections = view.sections;
+}
+
+/**
+ * Mount the tab into `host` — the Inspector's own body for the Style tab.
+ *
+ * The host is CLEARED first: a document owns the node it is given, and whatever the dock painted
+ * there belongs to a state this tab is no longer in.
+ *
+ * @param {HTMLElement} host The Inspector's Style tab body.
+ * @param {StylePanelView} view What the tab says to begin with.
+ * @param {StylePanelActions} actions What each control does. Read once, when the scope is made.
+ * @param {StyleHostSink} hosts Where the announced Target Line host is handed to.
+ * @returns {StylePanelSurface}
+ */
+export function mountStylePanelSurface(
+  host: HTMLElement,
+  view: StylePanelView,
+  actions: StylePanelActions,
+  hosts: StyleHostSink,
+): StylePanelSurface {
+  const scope = reactive<StylePanelScope>({
+    ...actions,
+    emptyActionLabel: "",
+    emptyMessage: "",
+    filter: "",
+    hasEmptyAction: false,
+    sections: [],
+    view: "empty",
+  }) as StylePanelScope;
+  project(scope, view);
+
+  host.replaceChildren();
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  void mountSurface("style-panel", scope, host, {
+    onNodeCreated: (element, _path, def) => {
+      if (element instanceof HTMLElement && partOf(def) === "target-host") {
+        hosts.target(element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* While the mount is in flight the tab owns the host only for as long as the host is still the
+       empty one it was handed; once mounted, the question is whether the root is still in it — a
+       dock that redrew took the tab's root away without telling anyone. */
+    connected: () =>
+      !disposed &&
+      (mounted === null
+        ? host.childNodes.length === 0
+        : (mounted.root as Node).parentNode === host),
+    dispose() {
+      disposed = true;
+      hosts.target(null);
+      mounted?.dispose();
+      mounted = null;
+    },
+    update: (next) => project(scope, next),
+  };
+}

package/src/surfaces/stylebook-chrome.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioStylebookChrome",
+  "$description": "The bar across the top of the Project Styles canvas: the filter that narrows the specimen catalogue, and the toggle that reduces it to the elements this file has already styled. Both are shell state rather than document state — the adapter owns which — and the two names come in as values, because the surface is called Project Styles and the canvas view it draws is the wire word `stylebook`; nothing a reader sees here may be spelled from that. **The bar IS the kit's toolbar now.** It used to write `role=\"toolbar\"` and its own `aria-label` on a `<div>`, which is a role with none of the behaviour under it: two controls, two tab stops, and no arrow key between them. `jx-action-group` is not the element for it — that one roves `jx-action-button` and this bar's first control is a `jx-textfield` — so `jx-toolbar` is, and the field keeps its own arrows while its caret still has text to walk (ui.md §5.5).",
+  "tagName": "jx-toolbar",
+  "attributes": {
+    "part": "chrome"
+  },
+  "$props": {
+    "label": {
+      "$ref": "#/state/title"
+    }
+  },
+  "style": {
+    "$description": "What `.sb-chrome` said in `styles/overlays.css`, plus the six inline declarations the template carried beside it, plus `.tb-toggle` — all three go dead with this conversion, and none of them is shared with another surface. Three repairs on the way. The bar is one element rather than a positioned box wrapping a `role=\"toolbar\"` row that declared the same flex layout again. The flex layout is not declared here EITHER any more: `display: flex`, `align-items: center`, the `--jx-space-2` gap, the sans face and the foreground colour are all `jx-toolbar`'s own, so what is left below is only what a positioned BAND is. And `.tb-toggle` read `var(--spectrum-font-size-50, 11px)`, which the kit spells `--jx-text-sm` at the same value; the rest of its drawing is a `jx-action-button` reaching in through `part=\"control\"`, because what it has to look like is a small bordered chip and every fill and control height the kit draws would otherwise have to be taken back off.",
+    "position": "absolute",
+    "top": "0",
+    "left": "0",
+    "right": "0",
+    "zIndex": "15",
+    "flexShrink": "0",
+    "padding": "var(--jx-space-2) var(--jx-space-3)",
+    "background": "var(--bg-panel)",
+    "borderBottom": "1px solid var(--border)",
+    "& [part=\"filter\"]": {
+      "flex": "1",
+      "maxWidth": "200px"
+    },
+    "& [part=\"customized\"] > [part=\"control\"]": {
+      "$description": "Bordered, unfilled and dimmed until it is on, which is what says it is a filter rather than an action: the catalogue it narrows is the thing the reader is looking at, so the control has to be quieter than its subject.",
+      "padding": "3px var(--jx-space-3)",
+      "border": "1px solid var(--border)",
+      "borderRadius": "var(--radius)",
+      "background": "transparent",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)",
+      ":hover": {
+        "background": "var(--hover-bg)"
+      }
+    },
+    "& [part=\"customized\"][data-selected] > [part=\"control\"]": {
+      "$description": "`data-selected` and not `selected`: the kit reflects the pressed state as a data attribute (`jx-action-button.json`), and the property this document binds never reaches the attribute of the same name.",
+      "borderColor": "var(--accent)",
+      "background": "var(--accent-15)",
+      "color": "var(--accent)"
+    }
+  },
+  "children": [
+    {
+      "tagName": "jx-textfield",
+      "attributes": {
+        "part": "filter"
+      },
+      "$props": {
+        "size": "sm",
+        "type": "search",
+        "clearable": true,
+        "label": {
+          "$ref": "#/state/filterLabel"
+        },
+        "placeholder": "Filter…",
+        "value": {
+          "$ref": "#/state/filter"
+        }
+      },
+      "oninput": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/setFilter"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "tagName": "jx-action-button",
+      "$description": "`onchange` and not `onclick`: a `toggles` button owns its own pressed state and says so with `change` (`jx-action-button.json`), and an `onclick` written here would replace the element's own click handler on the same property — the toggle would stop flipping and stop announcing `aria-pressed`.",
+      "attributes": {
+        "part": "customized"
+      },
+      "$props": {
+        "size": "sm",
+        "toggles": true,
+        "selected": {
+          "$ref": "#/state/customizedOnly"
+        },
+        "label": {
+          "$ref": "#/state/customizedLabel"
+        },
+        "hint": {
+          "$ref": "#/state/customizedHint"
+        }
+      },
+      "onchange": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/toggleCustomized"
+            },
+            "value": []
+          }
+        ]
+      },
+      "children": [
+        {
+          "tagName": "span",
+          "textContent": "${state.customizedLabel}"
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/stylebook-chrome.ts

@@ -0,0 +1,122 @@
+/// <reference lib="dom" />
+/**
+ * The Project Styles chrome bar, as a mounted document.
+ *
+ * `panels/stylebook-panel.ts` is the flow — it decides which breakpoints the catalogue is drawn at,
+ * builds the specimen document and mounts one iframe per panel — and this is the one part of that
+ * stage that is chrome rather than canvas.
+ *
+ * **The host element belongs to this module, not to the stage.** The rest of `renderStylebookMode`
+ * is a lit template whose artboards are `TemplateResult`s handed in by `canvas/canvas-render.ts`,
+ * so there is no container in the stage to mount into and no way to make one without editing the
+ * canvas. So the surface carries its own: one `<div>` per pane, mounted once and handed to lit as a
+ * child value. lit inserts a Node it is given rather than cloning it, and re-inserting the same
+ * node is a no-op, so the document survives every rebuild of the stage around it — and leaving the
+ * mode merely `remove()`s the node, which leaves the document inside it intact for the next entry.
+ *
+ * The host is `display: contents` because the bar positions itself: the document root carries the
+ * `position: absolute` the chrome always had, and a wrapper box would become the stage's flex item
+ * in its place.
+ *
+ * **One record per PANE, keyed by the stage itself.** Two panes can both be showing Project Styles,
+ * and a module-level slot would hand the second pane's mount the first pane's host — the defect
+ * `scripts/check-pane-singletons.ts` exists for. A `WeakMap` keyed on the `CanvasSurface` also
+ * needs no teardown hook: the record goes when the pane does.
+ *
+ * @docs studio/design/stylebook
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import chromeDoc from "./stylebook-chrome.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("stylebook-chrome", chromeDoc as unknown as JxDocument);
+
+/** What the bar says right now. Every field is the panel's own wording, never a value it derives. */
+export interface StylebookChromeView {
+  /** The toolbar's accessible name — the surface's title, never the canvas view's wire value. */
+  title: string;
+  /** What the filter field holds: the reader's own text, not a normalised form of it. */
+  filter: string;
+  /** The filter field's accessible name. */
+  filterLabel: string;
+  /** Whether the catalogue is reduced to what this file has already styled. */
+  customizedOnly: boolean;
+  /** The toggle's visible text and its accessible name — one word, so they are one field. */
+  customizedLabel: string;
+  /** The toggle's tooltip: what reducing the catalogue actually does. */
+  customizedHint: string;
+}
+
+/** What the two controls can ask the panel to do. */
+export interface StylebookChromeActions {
+  /** Called with what the field now holds. */
+  setFilter: (value: string) => void;
+  toggleCustomized: () => void;
+}
+
+export interface StylebookChromeSurface {
+  /** The element the document lives in — handed to the stage's lit template as a child value. */
+  readonly host: HTMLElement;
+  /** Bring the standing surface up to date, remounting only if its root has been taken away. */
+  update: (view: StylebookChromeView) => void;
+}
+
+interface StylebookChromeScope
+  extends Record<string, unknown>, StylebookChromeView, StylebookChromeActions {}
+
+/**
+ * Create the bar's surface, mounted into a host of its own.
+ *
+ * There is no teardown, deliberately: the host is the thing lit takes in and out of the stage, and
+ * leaving Project Styles is a `remove()` of that node, which leaves the document inside it intact
+ * and ready to be inserted again.
+ *
+ * @param {StylebookChromeView} view What the bar says to begin with.
+ * @param {StylebookChromeActions} actions What the two controls do.
+ * @returns {StylebookChromeSurface}
+ */
+export function createStylebookChromeSurface(
+  view: StylebookChromeView,
+  actions: StylebookChromeActions,
+): StylebookChromeSurface {
+  const host = document.createElement("div");
+  host.style.display = "contents";
+  const scope = reactive({ ...view, ...actions }) as StylebookChromeScope;
+
+  /** `null` while a mount is in flight — which is a standing surface, not a missing one. */
+  let handle: SurfaceHandle | null = null;
+  let mounting = false;
+
+  function mount(): void {
+    mounting = true;
+    void mountSurface("stylebook-chrome", scope, host).then((mounted) => {
+      mounting = false;
+      handle = mounted;
+    });
+  }
+
+  mount();
+
+  return {
+    host,
+    update(next) {
+      Object.assign(scope, next);
+      /* A standing mount is only ASSIGNED to. The stage is rebuilt whenever the filter changes —
+         that is what makes the specimen catalogue narrow — so rebuilding the bar on every rebuild
+         would take the field out from under the reader on the keystroke that caused it. The
+         remount below answers the one case assignment cannot: a host the document has been taken
+         out of. It cannot fire while a mount is in flight, because a record with no handle yet IS
+         the standing one. */
+      if (mounting || (handle !== null && host.contains(handle.root))) {
+        return;
+      }
+      handle?.dispose();
+      handle = null;
+      host.textContent = "";
+      mount();
+    },
+  };
+}