@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/styles-panel.ts

@@ -0,0 +1,195 @@
+/// <reference lib="dom" />
+/**
+ * The Styles panel surface: the Styles workspace's Navigator, as a Jx document over the kit
+ * (`specs/studio.md` §7.1).
+ *
+ * This is the adapter. `panels/styles-panel.ts` keeps every decision (which custom properties the
+ * project declares and how they group, what each colour resolves to, which tags the catalogue holds
+ * and which of them project.json already styles, which color schemes `$media` declares, and which
+ * row is current) and hands this module one projection whose every field is already a string. The
+ * document draws three sections and decides nothing.
+ *
+ * @docs studio/design/tokens
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import stylesPanelDoc from "./styles-panel.json";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("styles-panel", stylesPanelDoc);
+
+/** One custom property under its group. */
+export interface StylesVariableRow {
+  /** The property, by its real name: `--accent`. Also the row's key. */
+  name: string;
+  /** What it is declared as, as text. */
+  value: string;
+  /** `swatch` for a colour, whose chip is drawn; `none` for every other group. */
+  swatchState: "swatch" | "none";
+  /** The colour the chip is painted, already resolved through any `var()` chain; "" for none. */
+  swatch: string;
+  /** Whether this is the property the Variables view is pointed at. */
+  selected: boolean;
+}
+
+/** One group of custom properties: Colors, Fonts, Sizes & Spacing, Other. */
+export interface StylesVariableGroup {
+  /** The token group id, `color`; the key, and what a heading click shows. */
+  id: string;
+  title: string;
+  /** How many the group holds, as text: "6". */
+  count: string;
+  /** The count, said in words for a screen reader: "6 variables". */
+  countLabel: string;
+  variables: StylesVariableRow[];
+}
+
+/** One element default, by tag name. */
+export interface StylesElementRow {
+  /** What a click selects: the compound path (`ul li`), or a component's tag. Also the key. */
+  key: string;
+  /** The tag name the row shows: `h1`, `li`, `site-card`. */
+  tag: string;
+  /** How deep the row sits, as a CSS length, read through `--row-indent`. */
+  indent: string;
+  /** Whether project.json already styles this tag: the dot. */
+  customized: boolean;
+  /** Whether this is the tag the Elements view has selected. */
+  selected: boolean;
+}
+
+/** One block of the catalogue: Headings, Lists, Components. */
+export interface StylesElementGroup {
+  key: string;
+  label: string;
+  rows: StylesElementRow[];
+}
+
+/** One color scheme the project declares. */
+export interface StylesSchemeRow {
+  /** The `$media` entry, `--dark`. */
+  key: string;
+  /** "Light" or "Dark". */
+  label: string;
+  /** The media query that selects it: "(prefers-color-scheme: dark)". */
+  query: string;
+}
+
+/** Everything the document draws. */
+export interface StylesPanelValues {
+  /** `none` asks for a project; `styles` draws the three sections. */
+  body: "none" | "styles";
+  /** Every custom property in the root style block, as text. */
+  variableCount: string;
+  variablesState: "empty" | "listed";
+  groups: StylesVariableGroup[];
+  elementGroups: StylesElementGroup[];
+  /** How many tags project.json styles, as the on-screen count ("3 styled"), and in full words. */
+  customizedCount: string;
+  customizedLabel: string;
+  schemesState: "empty" | "listed";
+  schemes: StylesSchemeRow[];
+}
+
+/** What a control can ask the panel to do. Every one is a decision the flow owns. */
+export interface StylesPanelActions {
+  /** A group heading: the Variables view, at that group. */
+  showGroup: (group: string) => void;
+  /** A variable row: the Variables view, at that property. */
+  selectVariable: (name: string) => void;
+  /** **Add variable**: the Variables view's add row. */
+  addVariable: () => void;
+  /** An element row: the Elements view, with that tag selected. */
+  selectElement: (path: string) => void;
+  /** **Manage color schemes…**: Project Settings › Contexts. */
+  manageSchemes: () => void;
+}
+
+export interface StylesPanelSurfaceHandle {
+  readonly ready: Promise<unknown>;
+  /** Whether the mounted root is still where it was put. */
+  connected: () => boolean;
+  update: (values: StylesPanelValues) => void;
+  dispose: () => void;
+}
+
+interface StylesPanelScope extends StylesPanelValues, StylesPanelActions {}
+
+/** The scope's shape before the first projection lands on it. */
+export function emptyStylesPanelValues(): StylesPanelValues {
+  return {
+    body: "none",
+    customizedCount: "0",
+    customizedLabel: "",
+    elementGroups: [],
+    groups: [],
+    schemes: [],
+    schemesState: "empty",
+    variableCount: "0",
+    variablesState: "empty",
+  };
+}
+
+/** Write a projection in, field by field, so an unchanged field is inert. */
+function project(scope: StylesPanelScope, values: StylesPanelValues): void {
+  scope.body = values.body;
+  scope.variableCount = values.variableCount;
+  scope.variablesState = values.variablesState;
+  scope.groups = values.groups;
+  scope.elementGroups = values.elementGroups;
+  scope.customizedCount = values.customizedCount;
+  scope.customizedLabel = values.customizedLabel;
+  scope.schemesState = values.schemesState;
+  scope.schemes = values.schemes;
+}
+
+/**
+ * Mount the Styles panel into `container`, the content box the Navigator painted.
+ *
+ * @param container Where the document goes.
+ * @param values What it shows to begin with.
+ * @param actions What its controls do.
+ */
+export function mountStylesPanelSurface(
+  container: HTMLElement,
+  values: StylesPanelValues,
+  actions: StylesPanelActions,
+): StylesPanelSurfaceHandle {
+  const scope: StylesPanelScope = reactive<StylesPanelScope>({
+    ...emptyStylesPanelValues(),
+    ...actions,
+  });
+  project(scope, values);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("styles-panel", scope, container).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return surface;
+    }
+    mounted = surface;
+    return surface;
+  });
+
+  return {
+    connected: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      // A mount still in flight is not yet in the container, and is not a reason to remount.
+      return root === undefined ? true : container.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => {
+      project(scope, next);
+    },
+  };
+}

package/src/surfaces/styles-variables.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioStylesVariables",
+  "$description": "The Styles workspace's Variables view (studio.md §7.1): the project's CSS custom properties, the `--` keys of `project.json`'s root style block, edited in the pane over the same tab as the Elements view and the Code view. It draws the view's frame and nothing it edits: a heading, one sentence saying what these are, one saying when an edit reaches the file (a variable is written as it is changed, which also writes any element style edit still waiting for Save, because both live in the one file), the door to Project Settings › Contexts where colour schemes and breakpoints are declared, and an empty `editor` island the CSS Variables editor (`settings/css-vars-editor.ts`) is mounted into (studio-ui-guidelines.md §9.4). `style/variables-view.ts` decides every word.",
+  "tagName": "section",
+  "attributes": {
+    "part": "variables-view",
+    "aria-labelledby": "${state.headingId}",
+    "data-jx-region": "${state.region}"
+  },
+  "style": {
+    "$description": "Fills the pane's stage by its own geometry, as the workspace home does (`workspace-home.json`): the stage is `position: relative`, so the view takes the whole of it and scrolls itself without the stage being restyled for it. The column is capped so a value field never stretches across a wide pane.",
+    "position": "absolute",
+    "inset": "0",
+    "overflowY": "auto",
+    "boxSizing": "border-box",
+    "padding": "var(--jx-space-6)",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "background": "var(--bg-panel)",
+    "& [part=\"column\"]": {
+      "maxWidth": "760px",
+      "margin": "0 auto"
+    },
+    "& [part=\"head\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-2)",
+      "marginBottom": "var(--jx-space-5)"
+    },
+    "& [part=\"title\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-lg)",
+      "fontWeight": "600"
+    },
+    "& [part=\"lede\"], & [part=\"saving\"]": {
+      "margin": "0",
+      "maxWidth": "68ch",
+      "lineHeight": "1.5",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"saving\"]": {
+      "fontSize": "var(--jx-text-sm)"
+    },
+    "& [part=\"schemes\"]": {
+      "display": "flex",
+      "alignItems": "center",
+      "flexWrap": "wrap",
+      "gap": "var(--jx-space-2)",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"schemes-text\"]": {
+      "margin": "0"
+    }
+  },
+  "children": [
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "column"
+      },
+      "children": [
+        {
+          "tagName": "header",
+          "attributes": {
+            "part": "head"
+          },
+          "children": [
+            {
+              "tagName": "h2",
+              "attributes": {
+                "part": "title",
+                "id": "${state.headingId}"
+              },
+              "textContent": "${state.title}"
+            },
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "lede"
+              },
+              "textContent": "${state.lede}"
+            },
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "saving"
+              },
+              "textContent": "${state.saving}"
+            },
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "schemes"
+              },
+              "children": [
+                {
+                  "tagName": "p",
+                  "attributes": {
+                    "part": "schemes-text"
+                  },
+                  "textContent": "${state.schemes}"
+                },
+                {
+                  "tagName": "jx-action-button",
+                  "attributes": {
+                    "part": "manage-contexts"
+                  },
+                  "$props": {
+                    "size": "sm",
+                    "quiet": true
+                  },
+                  "onclick": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/manageContexts"
+                        },
+                        "value": []
+                      }
+                    ],
+                    "description": "Opens Project Settings on Contexts, the one place a colour scheme or a breakpoint is declared (studio.md §17.1)."
+                  },
+                  "children": [
+                    {
+                      "tagName": "span",
+                      "textContent": "${state.manageLabel}"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "editor",
+            "role": "none"
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/styles-variables.ts

@@ -0,0 +1,145 @@
+/// <reference lib="dom" />
+/**
+ * The Variables view surface: the frame the Styles workspace draws around the CSS Variables editor,
+ * as a Jx document over the kit.
+ *
+ * This is the adapter. `style/variables-view.ts` keeps the flow (which pane holds the view, what
+ * the editor island is handed, when the view follows an edit made elsewhere) and hands this module
+ * one projection: the heading, the sentences and the region. The document renders that and decides
+ * nothing.
+ *
+ * **The editor is an ISLAND.** The CSS Variables editor is a surface of its own
+ * (`surfaces/settings-css-vars.json`), mounted into a container it is handed, so this document
+ * renders an empty `editor` node and announces it through `onNodeCreated`, the one seam for an
+ * island (studio-ui-guidelines.md §9.4). Nothing here knows what a token is.
+ *
+ * **The container is CLEARED, because this is a pane and not a panel**, for the reason
+ * `surfaces/media-pane.ts` gives: the canvas stage is handed to whichever mode owns it whole.
+ *
+ * @docs studio/design/tokens
+ */
+
+import { isString } from "@jxsuite/schema/guards";
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import variablesDoc from "./styles-variables.json";
+import type { JxElement } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("styles-variables", variablesDoc);
+
+/** What the view draws, with every word already decided. */
+export interface VariablesView {
+  /** The pane region the view answers to (`pane.primary/variables`). */
+  region: string;
+  title: string;
+  /** What these are: the project's CSS custom properties. */
+  lede: string;
+  /** When an edit reaches the file. */
+  saving: string;
+  /** Where colour schemes and breakpoints are declared. */
+  schemes: string;
+  /** The button that goes there. */
+  manageLabel: string;
+}
+
+/** What the view's own control does. */
+export interface VariablesActions {
+  /** Open Project Settings on Contexts. */
+  manageContexts: () => void;
+}
+
+/** Where the CSS Variables editor lands. */
+export interface VariablesIslands {
+  /** Called with the `editor` node every time the document creates one. */
+  editorSlot: (host: HTMLElement) => void;
+}
+
+/**
+ * A mounted view: whether it still stands, and a way to take it down. There is no update: every
+ * word the view draws is a constant, and the editor island redraws itself.
+ */
+export interface VariablesSurfaceHandle {
+  /** Whether the mount is still in the host it was given (a mount still in flight counts). */
+  attached: () => boolean;
+  dispose: () => void;
+  /** Settles once the document is in the host. */
+  ready: Promise<void>;
+}
+
+interface VariablesScope extends VariablesView, VariablesActions {
+  headingId: string;
+}
+
+/** The view as the document reads it. */
+function project(scope: VariablesScope, view: VariablesView): void {
+  Object.assign(scope, view);
+  scope.headingId = `styles-variables-${view.region.replaceAll(/[^\w-]/g, "-")}`;
+}
+
+/** The `part` a node was authored with, or `""`: the only thing this adapter asks about a node. */
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/**
+ * Mount the Variables view into `host`, the pane's canvas stage.
+ *
+ * @param {HTMLElement} host The pane's canvas stage, emptied first.
+ * @param {VariablesView} view What to draw right now.
+ * @param {VariablesActions} actions What the view's control does.
+ * @param {VariablesIslands} islands Where the editor lands.
+ * @returns {VariablesSurfaceHandle}
+ */
+export function mountVariablesSurface(
+  host: HTMLElement,
+  view: VariablesView,
+  actions: VariablesActions,
+  islands: VariablesIslands,
+): VariablesSurfaceHandle {
+  host.replaceChildren();
+  const scope: VariablesScope = reactive<VariablesScope>({
+    headingId: "",
+    lede: "",
+    manageContexts: actions.manageContexts,
+    manageLabel: "",
+    region: "",
+    saving: "",
+    schemes: "",
+    title: "",
+  });
+  project(scope, view);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("styles-variables", scope, host, {
+    onNodeCreated: (element, _path, def) => {
+      if (element instanceof HTMLElement && partOf(def) === "editor") {
+        islands.editorSlot(element);
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    attached: () => {
+      if (disposed) {
+        return false;
+      }
+      const root = mounted?.root;
+      return root === undefined ? true : host.contains(root);
+    },
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+  };
+}

package/src/surfaces/tab-strip.json

@@ -115,7 +115,7 @@
       "color": "var(--jx-bg)"
     },
     "& [part=\"pin\"]": {
-      "$description": "`.tab-strip-pin`, in `jx-tab`'s actions slot. A click on it never also selects the tab, and that is the KIT's doing now rather than a `stopPropagation` this document has to remember: `jx-tab` stops a click inside its actions slot exactly as it stops one on its own close button.",
+      "$description": "`.tab-strip-pin`, in `jx-tab`'s actions slot, on the current chip and on a pinned one (the rule below). A click on it never also selects the tab, and that is the KIT's doing now rather than a `stopPropagation` this document has to remember: `jx-tab` stops a click inside its actions slot exactly as it stops one on its own close button.",
       "display": "flex",
       "alignItems": "center",
       "justifyContent": "center",
@@ -130,7 +130,6 @@
       "lineHeight": "1",
       "borderRadius": "var(--radius)",
       "cursor": "pointer",
-      "opacity": "0",
       ":hover": {
         "background": "var(--hover-bg)",
         "color": "var(--fg)"
@@ -140,8 +139,9 @@
         "outlineOffset": "-1px"
       }
     },
-    "& [part=\"tab\"]:hover [part=\"pin\"], & [part=\"tab\"][aria-selected=\"true\"] [part=\"pin\"], & [part=\"tab\"][data-pinned] [part=\"pin\"]": {
-      "opacity": "1"
+    "& [part=\"tab\"]:not([aria-selected=\"true\"]):not([data-pinned]) [part=\"pin\"]": {
+      "$description": "An inactive, unpinned chip draws no pin and keeps no box for one. It was `opacity: 0` here and revealed on hover, so the invisible button still took 16px of the chip and every click on it: the centre of a short chip (the Media home's, beside its viewer tab) was the pin, so the click toggled a pin nobody could see and the tab did not activate. A box that takes clicks is a control, and a control is either shown or absent. The current chip shows its pin, a pinned chip shows its mark, and any chip pins from its context menu (`document.togglePinned`).",
+      "display": "none"
     },
     "& [part=\"tab\"][data-pinned] [part=\"pin\"]": {
       "color": "var(--accent)"

package/src/surfaces/tab-strip.ts

@@ -28,20 +28,21 @@
  * @docs studio/interface
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import tabStripDoc from "./tab-strip.json";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("tab-strip", tabStripDoc as unknown as JxDocument);
+registerSurface("tab-strip", tabStripDoc);
 
 /**
  * One chip, as the document draws it. Every field is a value: the document asks no question about a
  * tab, and there is no branch in it that a projection has not already decided.
  */
-export interface TabChipView extends Record<string, unknown> {
+export interface TabChipView {
   /** The tab id: the repeater's key, the tab's `value`, and what every action is addressed with. */
   key: string;
   /** The shortest suffix that tells this document apart, or a page's route. */
@@ -107,7 +108,7 @@ export interface TabStripActions {
   /** The chevron, or a derived pane's ✕. The anchor is the button that was pressed. */
   openTrailing: (anchor: HTMLElement | null) => void;
   /** A wheel over the strip. A host function in handler position, so it takes the event. */
-  wheel: (scope: unknown, event: WheelEvent) => void;
+  wheel: (scope: JxScope, event: WheelEvent) => void;
   /** A chip element exists. `panels/tab-strip.ts` makes it a pragmatic drag source and drop target. */
   chipHost: (element: HTMLElement, id: string) => void;
   /**
@@ -146,20 +147,20 @@ export interface TabStripSurface {
 }
 
 /** The scope `tab-strip.json` reads. */
-interface TabStripScope
-  extends Record<string, unknown>, TabStripValues, TabStripActions, TabStripDragState {}
+interface TabStripScope extends TabStripValues, TabStripActions, TabStripDragState {}
 
 /** The `part` a node's definition carries, or `""` for a text node or an unmarked element. */
 function partOf(def: JxElement | string): string {
-  const part = typeof def === "string" ? undefined : def.attributes?.["part"];
-  return typeof part === "string" ? part : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /** The tab id a mapped `jx-tab` node was rendered for, read from the row scope, or `""`. */
 function mappedChipKey(state: JxScope | undefined): string {
-  const map = state?.["$map"] as { item?: { key?: unknown } } | undefined;
-  const key = map?.item?.key;
-  return typeof key === "string" ? key : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const key = isJsonObject(item) ? item["key"] : undefined;
+  return isString(key) ? key : "";
 }
 
 /**
@@ -178,13 +179,13 @@ export function mountTabStripSurface(
   values: TabStripValues,
   actions: TabStripActions,
 ): TabStripSurface {
-  const scope = reactive<TabStripScope>({
+  const scope: TabStripScope = reactive<TabStripScope>({
     ...values,
     ...actions,
     dragKey: "",
     dropIndex: -1,
     dropTail: false,
-  }) as TabStripScope;
+  });
 
   host.replaceChildren();
   let mounted: SurfaceHandle | null = null;

package/src/surfaces/target-line.ts

@@ -46,11 +46,10 @@ import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { openMenu } from "./menu";
 import targetLineDoc from "./target-line.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { MenuHandle, MenuRowProjection } from "./menu";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("target-line", targetLineDoc as unknown as JxDocument);
+registerSurface("target-line", targetLineDoc);
 
 /** The region the line stamps on itself, so a shot can crop it. */
 const REGION = "inspector/target";
@@ -108,7 +107,7 @@ export const BASE_SELECTOR_LABEL = "base rule";
 // ─── The projection ──────────────────────────────────────────────────────────
 
 /** One word of the sentence, as the document reads it. */
-interface ProjectedSegment extends Record<string, unknown> {
+interface ProjectedSegment {
   key: string;
   label: string;
   title: string;
@@ -119,7 +118,7 @@ interface ProjectedSegment extends Record<string, unknown> {
 }
 
 /** The scope `target-line.json` reads. */
-interface TargetLineScope extends Record<string, unknown> {
+interface TargetLineScope {
   region: string;
   segments: ProjectedSegment[];
   selectorLabel: string;
@@ -201,7 +200,7 @@ function scope(): TargetLineScope {
     toggleLabel: "Show affected",
     warn: false,
     warningText: "",
-  }) as TargetLineScope;
+  });
   return _scope;
 }
 
@@ -311,11 +310,11 @@ export function openSelectorMenu(): void {
       },
       title: BASE_SELECTOR_LABEL,
     },
-    ...selector.options.map((option, index) => ({
+    ...selector.options.map((option, index): MenuRowProjection => ({
       /* What the ● in the old menu said: this element already DECLARES this rule. Where you are is
          stated once, by the trigger's own label — a row that carried both facts would be two
          answers on one line. */
-      checked: (selector.declared.has(option) ? "true" : "false") as "true" | "false",
+      checked: selector.declared.has(option) ? "true" : "false",
       destructive: false,
       disabled: false,
       dividerAbove: index === 0,