@jxsuite/studio 6.1.2 → 8.0.1

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/welcome.ts

@@ -26,7 +26,7 @@ import { getProjectList } from "../project-list";
 import { reactive } from "../reactivity";
 import { MINUTE, now } from "../services/clock";
 import { clearRecentProjects, getRecentProjects, removeRecentProject } from "../recent-projects";
-import { platformSupportsClone } from "../panels/git-panel";
+import { platformSupportsClone } from "../publish/source-control";
 import { mountSurface, registerSurface } from "../ui/surface";
 import welcomeDoc from "./welcome.json";
 import type { SurfaceHandle } from "../ui/surface";

package/src/surfaces/writing-banner.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioWritingBanner",
+  "$description": "The writing-mode banner (specs/studio.md §22.5): one slim line above the canvas while a collection entry is written inside its template's layout, saying what the arrangement is (the text and media are editable, the layout is locked) with the door to the template, which opens it in Design. `content/writing-banner.ts` decides whether there is a template to open and what it is called; this document draws a sentence and, when there is one, the button.",
+  "tagName": "div",
+  "attributes": {
+    "part": "banner",
+    "role": "note",
+    "data-jx-region": "${state.region}"
+  },
+  "style": {
+    "$description": "A quiet band, the Content-Entry board's: the canvas is the subject, so the banner is a tinted line rather than a panel, and its action is a quiet button.",
+    "display": "flex",
+    "alignItems": "center",
+    "flexWrap": "wrap",
+    "gap": "var(--jx-space-2)",
+    "padding": "var(--jx-space-1) var(--jx-space-4)",
+    "background": "color-mix(in srgb, var(--accent) 10%, var(--bg-panel))",
+    "borderBottom": "1px solid var(--border)",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-sm)",
+    "color": "var(--fg-dim)",
+    "& [part=\"glyph\"]": {
+      "flexShrink": "0",
+      "color": "var(--accent)"
+    },
+    "& [part=\"text\"]": {
+      "flex": "1",
+      "minWidth": "0"
+    },
+    "& [part=\"action-slot\"]": {
+      "display": "contents"
+    }
+  },
+  "children": [
+    {
+      "tagName": "jx-icon",
+      "attributes": {
+        "part": "glyph"
+      },
+      "$props": {
+        "name": "lock-simple"
+      }
+    },
+    {
+      "tagName": "span",
+      "attributes": {
+        "part": "text"
+      },
+      "textContent": "${state.text}"
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "action-slot",
+        "role": "none"
+      },
+      "$switch": {
+        "$ref": "#/state/actionState"
+      },
+      "cases": {
+        "shown": {
+          "tagName": "jx-action-button",
+          "attributes": {
+            "part": "edit-template"
+          },
+          "$props": {
+            "size": "sm",
+            "quiet": true
+          },
+          "onclick": {
+            "$prototype": "Function",
+            "body": [
+              {
+                "operator": "call",
+                "target": {
+                  "$ref": "#/state/openTemplate"
+                },
+                "value": []
+              }
+            ],
+            "description": "Opening the template is activating it, which enters Design (studio.md §22.1)."
+          },
+          "children": [
+            {
+              "tagName": "span",
+              "textContent": "${state.actionLabel}"
+            }
+          ]
+        }
+      }
+    }
+  ]
+}