@jxsuite/studio 6.1.1 → 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

@@ -41,17 +41,16 @@ import { clearLayerSlot, getLayerSlot } from "../ui/layers";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
 import slashMenuDoc from "./slash-menu.json";
-import type { JxDocument } from "@jxsuite/schema/types";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type { SurfaceHandle } from "../ui/surface";
 
-registerSurface("slash-menu", slashMenuDoc as unknown as JxDocument);
+registerSurface("slash-menu", slashMenuDoc);
 
 /** The popover slot id; the region is `overlay.menu:slash-menu`, which is what the shots crop. */
 const SLOT = "slash-menu";
 
 /** One offer, as the document reads it. */
-export interface SlashMenuRow extends Record<string, unknown> {
+export interface SlashMenuRow {
   /**
    * The element's tag — unique in the list, so it is the repeater's key AND the row's `value`,
    * which is what a picked row names in its `select` event.
@@ -60,6 +59,23 @@ export interface SlashMenuRow extends Record<string, unknown> {
   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. */
@@ -72,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;
 }
@@ -103,12 +122,13 @@ export interface SlashMenuSurface {
 }
 
 /** The scope `slash-menu.json` reads. */
-interface SlashMenuScope extends Record<string, unknown> {
+interface SlashMenuScope {
   x: number;
   y: number;
   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
@@ -168,7 +188,7 @@ export function openSlashMenuSurface(
   let mounted: SurfaceHandle | null = null;
   let closed = false;
 
-  const scope = reactive<SlashMenuScope>({
+  const scope: SlashMenuScope = reactive<SlashMenuScope>({
     activeId: activeIdOf(view),
     expanded: view.rows.length > 0,
     filter: view.filter,
@@ -184,6 +204,9 @@ export function openSlashMenuSurface(
          one bubbling handler on the listbox replaces a closure per row, and the position the flow
          wants is resolved here against the list the panel is showing rather than baked into the
          row when it was drawn. */
+      /* SAFETY: `slash-menu.json` binds this handler to the listbox's `onselect` alone, and `select`
+         is raised by the `dispatchEvent` statement in `jx-option.json`, which the runtime always
+         constructs as a `CustomEvent` whose `detail` is the row's value. */
       const tag = String((event as CustomEvent<unknown>).detail);
       const index = scope.rows.findIndex((row) => row.key === tag);
       if (index !== -1) {
@@ -191,10 +214,11 @@ export function openSlashMenuSurface(
       }
     },
     rows: [...view.rows],
+    groups: [...view.groups],
     showFilter: view.showFilter,
     x: view.x,
     y: view.y,
-  }) as SlashMenuScope;
+  });
 
   const finish = (fromPlatform: boolean): void => {
     if (closed) {
@@ -210,12 +234,20 @@ export function openSlashMenuSurface(
     }
   };
 
+  /* Read through a call, not the property path: `close()` can abort the controller while the panel
+     is awaiting `jx-ready`, and a direct test after that `await` would be narrowed to the value the
+     test before it saw. */
+  const aborted = (): boolean => controller.signal.aborted;
+
   const ready = (async () => {
     const surface = await mountSurface("slash-menu", scope, slot, { signal: controller.signal });
-    if (controller.signal.aborted) {
+    if (aborted()) {
       return;
     }
     mounted = surface;
+    /* SAFETY: `slash-menu.json`'s root definition carries `tagName: "jx-popover"`, so the mounted
+       root is the kit's popover element, which reflects `open` and inherits `showPopover` and
+       `hidePopover` from HTMLElement. */
     panel = surface.root as PopoverElement;
     /* The region rides on the PANEL as well as on the slot `getLayerSlot` stamped: a popover is
        `position: fixed` in the top layer, so the slot around it has a zero-height box and the
@@ -223,7 +255,7 @@ export function openSlashMenuSurface(
        takes the last match in document order, which is the panel. */
     panel.setAttribute(REGION_ATTR, overlayRegion("popover", SLOT));
     panel.addEventListener("toggle", (event) => {
-      if ((event as { newState?: string }).newState === "closed") {
+      if (event.newState === "closed") {
         finish(true);
       }
     });
@@ -234,7 +266,7 @@ export function openSlashMenuSurface(
         panel!.addEventListener("jx-ready", () => resolve(), { once: true });
       });
     }
-    if (controller.signal.aborted) {
+    if (aborted()) {
       return;
     }
     panel.showPopover(anchor instanceof HTMLElement ? { source: anchor } : undefined);
@@ -264,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/statements.ts

@@ -26,25 +26,20 @@
  * @docs studio/logic/statements
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { REGION_ATTR } from "../ui/regions";
 import { mountSurface, registerSurface } from "../ui/surface";
 import statementsDoc from "./statements.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";
+import type { SurfaceHandle, SurfaceOption } from "../ui/surface";
 
-registerSurface("statements", statementsDoc as unknown as JxDocument);
+registerSurface("statements", statementsDoc);
 
 /** Which control one operand of a statement draws. The flow picks it; the document switches on it. */
 export type StatementFieldKind = "control" | "text" | "select" | "flags";
 
-/** A closed list of choices, in the shape the kit's select reads. */
-export interface StatementOption {
-  value: string;
-  label: string;
-}
-
 /** One `eventInit` flag of a `dispatchEvent` statement. */
 export interface StatementFlagView {
   /** `<row>::<prop>::<flag>` — self-contained, because a third `$map` shadows both above it. */
@@ -64,7 +59,7 @@ export interface StatementFieldView {
   /** What a `text` or `select` control holds. Empty for the other two kinds. */
   value: string;
   placeholder: string;
-  options: StatementOption[];
+  options: SurfaceOption[];
   flags: StatementFlagView[];
 }
 
@@ -119,7 +114,7 @@ export interface StatementIslands {
   controlSlot: (id: string, host: HTMLElement) => void;
 }
 
-interface StatementScope extends Record<string, unknown>, StatementActions {
+interface StatementScope extends StatementActions {
   rows: StatementRowView[];
 }
 
@@ -171,7 +166,7 @@ export function renderStatementsSurface(
      region is a fact about the HOST — who is drawing this editor — not about the document inside
      it, so it should be true the moment the host is claimed rather than a frame later. */
   host.setAttribute(REGION_ATTR, region);
-  const scope = reactive({ ...actions, rows }) as StatementScope;
+  const scope: StatementScope = reactive<StatementScope>({ ...actions, rows });
   const record: Mounted = { disposed: false, handle: null, scope };
   mounts.set(host, record);
   /* No race to arbitrate: a repaint arriving while this is in flight takes the branch above — a
@@ -200,16 +195,16 @@ export function renderStatementsSurface(
 
 /** The `part` a node was rendered with, or "". */
 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 `key` of the `$map` item a node was rendered inside, or "". */
 function itemKey(state: JxScope | undefined): string {
-  const item = (state?.["$map"] as { item?: unknown } | undefined)?.item;
-  const key =
-    item !== null && typeof item === "object" ? (item as Record<string, unknown>).key : "";
-  return typeof key === "string" ? key : "";
+  const map = state?.["$map"];
+  const item = isJsonObject(map) ? map["item"] : undefined;
+  const key = isJsonObject(item) ? item["key"] : "";
+  return isString(key) ? key : "";
 }
 
 /**