@jxsuite/studio 6.1.2 → 8.0.0

package/src/surfaces/site-panel.ts

@@ -0,0 +1,233 @@
+/// <reference lib="dom" />
+/**
+ * The Site panel, as a mounted document (`specs/studio.md` §5.7).
+ *
+ * `panels/site-panel.ts` is the flow — which files are pages and in what order, how a collection
+ * nests its pages, what a click opens and what a drag inserts — and this is the surface it draws
+ * into: the reactive scope `site-panel.json` reads, and the mount that stays put while the
+ * Navigator repaints around it.
+ *
+ * **Three islands, all through `onNodeCreated`.** A component card's preview box is filled with the
+ * component rendered live, a component card is a drag source, and a media thumbnail is a drag
+ * source. Each is announced to the flow as its node is CREATED, with the mapped row it was drawn
+ * for, which is the compliant seam for registering behaviour on a node a document created
+ * (studio-ui-guidelines.md §9.4) — never a query over the mounted DOM. The `disposed` guard comes
+ * first for the reason `surfaces/files-panel.ts` gives: a panel taken down inside the same turn
+ * still walks this callback for every row, and a registration made then would outlive it.
+ *
+ * @docs studio/interface
+ */
+
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import sitePanelDoc from "./site-panel.json";
+import type { JsonObject, JxElement } from "@jxsuite/schema/types";
+import type { JxScope } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "../ui/surface";
+import type {
+  SiteComponentRow,
+  SiteMediaRow,
+  SitePageRow,
+  SiteTemplateRow,
+} from "../panels/site-model";
+
+registerSurface("site-panel", sitePanelDoc);
+
+/** What a section draws: a sentence while reading, one when empty or filtered out, or its rows. */
+export type SiteSectionState = "loading" | "empty" | "nomatch" | "listed";
+
+/** Everything the document reads. Every field is a value. */
+export interface SitePanelValues {
+  /** `none` draws one sentence asking for a project; `project` draws the four sections. */
+  body: "none" | "project";
+  filter: string;
+  pages: SitePageRow[];
+  pagesState: SiteSectionState;
+  pagesCount: string;
+  templates: SiteTemplateRow[];
+  templatesState: SiteSectionState;
+  templatesCount: string;
+  components: SiteComponentRow[];
+  componentsState: SiteSectionState;
+  componentsCount: string;
+  media: SiteMediaRow[];
+  mediaState: SiteSectionState;
+  mediaCount: string;
+  /**
+   * The line under a strip that does not show every thumbnail the filter admits ("Show all 766 in
+   * Media"), or `""` when it shows them all.
+   */
+  mediaMore: string;
+}
+
+/** What a control can ask the panel to do. Read once, when the scope is made. */
+export interface SitePanelActions {
+  /** The filter field now holds `value`. */
+  setFilter: (value: string) => void;
+  /** Open a page, a template or a media file by its project path. */
+  open: (path: string) => void;
+  /** Open a component's definition by its tag. */
+  openComponent: (tagName: string) => void;
+  /** The `+` was pressed: open Add new. */
+  add: () => void;
+  /** Switch to the Media workspace. */
+  openMedia: () => void;
+}
+
+/** The islands the flow attaches behaviour to, each announced as it is created. */
+export interface SitePanelIslands {
+  /** A component card's empty preview box, for the component with this tag. */
+  preview: (element: HTMLElement, tagName: string) => void;
+  /** A component card, which drags an instance of the component with this tag. */
+  componentSource: (element: HTMLElement, tagName: string) => void;
+  /** A media thumbnail, which drags an element referencing the file at this path. */
+  mediaSource: (element: HTMLElement, path: string) => void;
+}
+
+export interface SitePanelSurfaceHandle {
+  /** Settles once the document is mounted. */
+  readonly ready: Promise<unknown>;
+  /** Whether the mounted root is still where it was put. */
+  connected: () => boolean;
+  update: (values: SitePanelValues) => void;
+  dispose: () => void;
+}
+
+interface SitePanelScope extends SitePanelValues, SitePanelActions {}
+
+/** The scope's shape before the first projection lands on it. */
+export function emptySitePanelValues(): SitePanelValues {
+  return {
+    body: "none",
+    components: [],
+    componentsCount: "",
+    componentsState: "loading",
+    filter: "",
+    media: [],
+    mediaCount: "",
+    mediaMore: "",
+    mediaState: "loading",
+    pages: [],
+    pagesCount: "",
+    pagesState: "loading",
+    templates: [],
+    templatesCount: "",
+    templatesState: "loading",
+  };
+}
+
+/** Write a projection in, field by field, so an unchanged field is inert. */
+function project(scope: SitePanelScope, values: SitePanelValues): void {
+  scope.body = values.body;
+  scope.filter = values.filter;
+  scope.pages = values.pages;
+  scope.pagesState = values.pagesState;
+  scope.pagesCount = values.pagesCount;
+  scope.templates = values.templates;
+  scope.templatesState = values.templatesState;
+  scope.templatesCount = values.templatesCount;
+  scope.components = values.components;
+  scope.componentsState = values.componentsState;
+  scope.componentsCount = values.componentsCount;
+  scope.media = values.media;
+  scope.mediaState = values.mediaState;
+  scope.mediaCount = values.mediaCount;
+  scope.mediaMore = values.mediaMore;
+}
+
+/** The `part` a node was declared with, or the empty string. */
+function partOf(def: JxElement | string): string {
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
+}
+
+/** The `$map` item a node was rendered inside, if it was rendered inside one. */
+function mapItem(state: JxScope | undefined): JsonObject | null {
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  return isJsonObject(item) ? item : null;
+}
+
+/** One string field of the mapped row, or the empty string. */
+function itemField(state: JxScope | undefined, field: string): string {
+  const value = mapItem(state)?.[field];
+  return isString(value) ? value : "";
+}
+
+/**
+ * Mount the Site 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.
+ * @param islands Where the flow attaches previews and drag sources.
+ */
+export function mountSitePanelSurface(
+  container: HTMLElement,
+  values: SitePanelValues,
+  actions: SitePanelActions,
+  islands: SitePanelIslands,
+): SitePanelSurfaceHandle {
+  const scope: SitePanelScope = reactive<SitePanelScope>({
+    ...emptySitePanelValues(),
+    ...actions,
+  });
+  project(scope, values);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("site-panel", scope, container, {
+    onNodeCreated: (element, _path, def, state) => {
+      if (disposed || !(element instanceof HTMLElement)) {
+        return;
+      }
+      switch (partOf(def)) {
+        case "card-preview": {
+          const tag = itemField(state, "tagName");
+          if (tag !== "") {
+            islands.preview(element, tag);
+          }
+          break;
+        }
+        case "component-card": {
+          const tag = itemField(state, "tagName");
+          if (tag !== "") {
+            islands.componentSource(element, tag);
+          }
+          break;
+        }
+        case "media-thumb": {
+          const path = itemField(state, "path");
+          if (path !== "") {
+            islands.mediaSource(element, path);
+          }
+          break;
+        }
+        default: {
+          break;
+        }
+      }
+    },
+  }).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return surface;
+    }
+    mounted = surface;
+    return surface;
+  });
+
+  return {
+    connected: () => !disposed && (mounted === null || mounted.root.parentNode === container),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => {
+      project(scope, next);
+    },
+  };
+}

package/src/surfaces/slash-menu.json

@@ -140,36 +140,78 @@
             {
               "$prototype": "Array",
               "items": {
-                "$ref": "#/state/rows"
+                "$ref": "#/state/groups"
               },
               "key": {
                 "$ref": "$map/item/key"
               },
               "map": {
-                "tagName": "jx-option",
+                "tagName": "div",
                 "attributes": {
-                  "part": "option",
-                  "id": "slash-menu-option-${$map.index}",
-                  "value": "${$map.item.key}",
-                  "label": "${$map.item.label}",
-                  "description": "${$map.item.description}"
+                  "part": "group",
+                  "role": "group",
+                  "aria-label": "${$map.item.name}"
                 },
-                "onmouseenter": {
-                  "$prototype": "Function",
-                  "body": [
-                    {
-                      "operator": "call",
-                      "target": {
-                        "$ref": "#/state/hover"
+                "children": [
+                  {
+                    "tagName": "div",
+                    "attributes": {
+                      "part": "group-label-slot",
+                      "role": "none"
+                    },
+                    "style": {
+                      "display": "contents"
+                    },
+                    "$switch": {
+                      "$ref": "$map/item/hasLabel"
+                    },
+                    "cases": {
+                      "true": {
+                        "tagName": "div",
+                        "attributes": {
+                          "part": "group-heading",
+                          "aria-hidden": "true"
+                        },
+                        "textContent": "${$map.item.label}"
+                      }
+                    }
+                  },
+                  {
+                    "$prototype": "Array",
+                    "items": {
+                      "$ref": "$map/item/rows"
+                    },
+                    "key": {
+                      "$ref": "$map/item/key"
+                    },
+                    "map": {
+                      "tagName": "jx-option",
+                      "attributes": {
+                        "part": "option",
+                        "id": "slash-menu-option-${$map.item.index}",
+                        "value": "${$map.item.key}",
+                        "label": "${$map.item.label}",
+                        "description": "${$map.item.description}"
                       },
-                      "value": [
-                        {
-                          "$ref": "$map/index"
-                        }
-                      ]
+                      "onmouseenter": {
+                        "$prototype": "Function",
+                        "body": [
+                          {
+                            "operator": "call",
+                            "target": {
+                              "$ref": "#/state/hover"
+                            },
+                            "value": [
+                              {
+                                "$ref": "$map/item/index"
+                              }
+                            ]
+                          }
+                        ]
+                      }
                     }
-                  ]
-                }
+                  }
+                ]
               }
             }
           ]

package/src/surfaces/slash-menu.ts

@@ -59,6 +59,23 @@ export interface SlashMenuRow {
   label: string;
   /** A muted note at the end of the row. Empty draws no box: `jx-option` hides its own part. */
   description: string;
+  /** The row's position in the FLAT list — its id, and what a hover reports. */
+  index: number;
+}
+
+/**
+ * One headed run of rows: the HTML elements (no heading), then the project's components under
+ * "Components" (§5.7). A `role="group"` wrapper is what `jx-listbox` reads headings from, and its
+ * rows stay its own (`optionsOf` keeps every descendant option whose nearest listbox is this one).
+ */
+export interface SlashMenuGroup {
+  key: string;
+  /** The visible heading; empty for the unheaded first group. */
+  label: string;
+  /** The group's accessible name, which the unheaded group needs too. */
+  name: string;
+  hasLabel: boolean;
+  rows: SlashMenuRow[];
 }
 
 /** What the panel is showing right now. */
@@ -71,7 +88,10 @@ export interface SlashMenuView {
   showFilter: boolean;
   /** What that field contains. */
   filter: string;
+  /** Every row, flat, in the order the keyboard walks them. */
   rows: SlashMenuRow[];
+  /** The same rows as the panel draws them, headed. */
+  groups: SlashMenuGroup[];
   /** The highlighted row, as an index into {@link SlashMenuView.rows}. */
   activeIndex: number;
 }
@@ -108,6 +128,7 @@ interface SlashMenuScope {
   showFilter: boolean;
   filter: string;
   rows: SlashMenuRow[];
+  groups: SlashMenuGroup[];
   /**
    * The active row's id — the ONE string the highlight is written as. The listbox turns it into a
    * row's `selected`, and the filter field, when there is one, puts the same string in its
@@ -193,6 +214,7 @@ export function openSlashMenuSurface(
       }
     },
     rows: [...view.rows],
+    groups: [...view.groups],
     showFilter: view.showFilter,
     x: view.x,
     y: view.y,
@@ -274,6 +296,7 @@ export function openSlashMenuSurface(
       scope.showFilter = next.showFilter;
       scope.filter = next.filter;
       scope.rows = [...next.rows];
+      scope.groups = [...next.groups];
       scope.activeId = activeIdOf(next);
       scope.isEmpty = next.rows.length === 0;
       scope.expanded = next.rows.length > 0;

package/src/surfaces/statusbar.ts

@@ -47,6 +47,8 @@ import { attachJumpBarHost, mountJumpBar, unmountJumpBar } from "../panels/jump-
 import { shell } from "../shell";
 import { effect, effectScope, reactive } from "../reactivity";
 import { activeTab } from "../workspace/workspace";
+import { PROJECT_STYLES_VIEW } from "../style/project-styles";
+import { stylebookTarget } from "../style/stylebook-target";
 import { activeRegistry } from "../commands/active-registry";
 import { runReported } from "../commands/run-reported";
 import { deployStatusItem } from "../publish/deploy-checklist";
@@ -164,6 +166,14 @@ export function aheadBehindLabel(ahead: number, behind: number): string {
   return `${ahead > 0 ? ` ↑${ahead}` : ""}${behind > 0 ? ` ↓${behind}` : ""}`;
 }
 
+/** "No changes", "1 changed file", "3 changed files": what the branch item's tooltip states. */
+export function changedFilesLabel(count: number): string {
+  if (count === 0) {
+    return "No changes";
+  }
+  return count === 1 ? "1 changed file" : `${count} changed files`;
+}
+
 function projectField_(registry: CommandRegistry | null): ProjectedField | null {
   const project = projectState;
   const { status } = shell.git;
@@ -183,11 +193,16 @@ function projectField_(registry: CommandRegistry | null): ProjectedField | null
        — and adjacent duplicate chrome is what the chrome budget (studio-ui-guidelines.md §12.2)
        forbids. `tests/statusbar.test.ts` pins the pairing from both ends, so deleting the
        checklist's repo step fails there rather than quietly taking the state off the bar. */
+    /* `publish.open { tab: "review" }` rather than the bare workspace setter: the setter's title
+       is "Switch Workspace", which says nothing about where a branch item goes, and the Publish
+       workspace remembers its last sub-tab, so a click from a count of changes could land on
+       Hosting. Review changes is the tab that count is a count of. */
     status?.isRepo === true && status.branch
       ? {
-          command: "panel.focus.git",
+          args: { tab: "review" },
+          command: "publish.open",
           label: `⑂ ${status.branch}${aheadBehindLabel(status.ahead, status.behind)}`,
-          title: `${status.files.length} changed file(s)`,
+          title: `${changedFilesLabel(status.files.length)} on ${status.branch}`,
         }
       : null,
     // Where the project stands with shipping — ambient state, so it belongs beside the branch and
@@ -203,7 +218,7 @@ function projectField_(registry: CommandRegistry | null): ProjectedField | null
           args: { tab: "problems" },
           command: "view.setBottomTab",
           label: `⚠ ${count}`,
-          title: `${count} problem(s)`,
+          title: count === 1 ? "1 problem" : `${count} problems`,
         }
       : null,
     /* `collab.showStatus` — "what is happening in this document?" — because that is the question a
@@ -233,28 +248,36 @@ function projectField_(registry: CommandRegistry | null): ProjectedField | null
  * states it permanently, with its ancestors, one field to the left.
  */
 function selectionField(registry: CommandRegistry | null): ProjectedField | null {
-  const paths = activeTab.value?.session.selection ?? [];
-  if (paths.length > 0) {
-    // A document selection owns the field even when it prints nothing: the Stylebook's selector
-    // Below would otherwise appear while an element is picked, which is two answers to one question.
-    return paths.length > 1
+  const tab = activeTab.value;
+  /* The Stylebook's selection is what the Style panel is editing, and it is a selection OF the
+     Stylebook canvas, so it is the field's content exactly while the focused tab draws that canvas,
+     and never elsewhere. It outlives a workspace switch (coming back to Styles finds `h1` still
+     picked), but a Content page or the Publish home is not editing `h1`, and the field used to say
+     it was there. The Style panel gates on the same mode (`panels/style-panel.ts`).
+
+     It also wins over the document selection here, because in that mode the document selection is
+     not the author's: picking a tag clears it (`selectStylebookTag`), so the "a single selection
+     prints nothing" rule below hid the rule being edited in the one place it applied. The command
+     bar and the Inspector header ask the same question through `stylebookTarget`. */
+  if (tab?.session.ui.canvasMode === PROJECT_STYLES_VIEW) {
+    const target = stylebookTarget(tab);
+    return target
       ? projectField(registry, "selection", [
           {
             command: null,
-            label: `${paths.length} selected`,
-            title: `${paths.length} elements are selected; the trail names the primary`,
+            label: target.replaceAll(" ", " › "),
+            title: "The style rule being edited",
           },
         ])
       : null;
   }
-  // The stylebook's own selection is a selection: it is what the Style panel is editing, and it is
-  // The only thing in this field when no document node is picked.
-  return shell.stylebook.selection
+  const paths = tab?.session.selection ?? [];
+  return paths.length > 1
     ? projectField(registry, "selection", [
         {
           command: null,
-          label: shell.stylebook.selection.replaceAll(" ", " › "),
-          title: "The style rule being edited",
+          label: `${paths.length} selected`,
+          title: `${paths.length} elements are selected; the trail names the primary`,
         },
       ])
     : null;
@@ -352,6 +375,7 @@ export function mountStatusbar(): void {
       // Reading it here is what repaints the bar from a skeleton into the real thing.
       void activeRegistry();
       void shell.stylebook.selection;
+      void activeTab.value?.session.ui.canvasMode;
       void shell.git.status;
       void problems.length;
       const tab = activeTab.value;