@jxsuite/studio 6.1.1 → 8.0.0

package/src/surfaces/preferences.json

@@ -206,6 +206,21 @@
       "flex": "1",
       "color": "var(--fg-dim)",
       "minWidth": "0"
+    },
+    "& [part=\"appearance\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-5)"
+    },
+    "& [part=\"developer-row\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "var(--jx-space-1)"
+    },
+    "& [part=\"developer-note\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-sm)",
+      "color": "var(--fg-dim)"
     }
   },
   "children": [
@@ -295,70 +310,127 @@
                 "appearance": {
                   "tagName": "div",
                   "attributes": {
-                    "part": "theme-row"
+                    "part": "appearance"
                   },
                   "children": [
                     {
-                      "tagName": "span",
+                      "tagName": "div",
                       "attributes": {
-                        "part": "theme-label"
+                        "part": "theme-row"
                       },
-                      "textContent": "Theme"
+                      "children": [
+                        {
+                          "tagName": "span",
+                          "attributes": {
+                            "part": "theme-label"
+                          },
+                          "textContent": "Theme"
+                        },
+                        {
+                          "tagName": "jx-action-group",
+                          "attributes": {
+                            "part": "themes"
+                          },
+                          "$props": {
+                            "selects": "single",
+                            "compact": true,
+                            "label": "Theme"
+                          },
+                          "children": [
+                            {
+                              "$prototype": "Array",
+                              "items": {
+                                "$ref": "#/state/themes"
+                              },
+                              "key": {
+                                "$ref": "$map/item/value"
+                              },
+                              "map": {
+                                "tagName": "jx-action-button",
+                                "attributes": {
+                                  "part": "theme",
+                                  "data-theme": "${$map.item.value}"
+                                },
+                                "$props": {
+                                  "size": "sm",
+                                  "checked": {
+                                    "$ref": "$map/item/checked"
+                                  }
+                                },
+                                "onclick": {
+                                  "$prototype": "Function",
+                                  "body": [
+                                    {
+                                      "operator": "call",
+                                      "target": {
+                                        "$ref": "#/state/setTheme"
+                                      },
+                                      "value": [
+                                        {
+                                          "$ref": "$map/item/value"
+                                        }
+                                      ]
+                                    }
+                                  ]
+                                },
+                                "children": [
+                                  {
+                                    "tagName": "span",
+                                    "textContent": "${$map.item.label}"
+                                  }
+                                ]
+                              }
+                            }
+                          ]
+                        }
+                      ]
                     },
                     {
-                      "tagName": "jx-action-group",
+                      "tagName": "div",
                       "attributes": {
-                        "part": "themes"
-                      },
-                      "$props": {
-                        "selects": "single",
-                        "compact": true,
-                        "label": "Theme"
+                        "part": "developer-row"
                       },
                       "children": [
                         {
-                          "$prototype": "Array",
-                          "items": {
-                            "$ref": "#/state/themes"
+                          "tagName": "jx-switch",
+                          "attributes": {
+                            "part": "developer-panels"
                           },
-                          "key": {
-                            "$ref": "$map/item/value"
+                          "$props": {
+                            "size": "sm",
+                            "checked": {
+                              "$ref": "#/state/developerPanels"
+                            }
                           },
-                          "map": {
-                            "tagName": "jx-action-button",
-                            "attributes": {
-                              "part": "theme",
-                              "data-theme": "${$map.item.value}"
-                            },
-                            "$props": {
-                              "size": "sm",
-                              "checked": {
-                                "$ref": "$map/item/checked"
-                              }
-                            },
-                            "onclick": {
-                              "$prototype": "Function",
-                              "body": [
-                                {
-                                  "operator": "call",
-                                  "target": {
-                                    "$ref": "#/state/setTheme"
-                                  },
-                                  "value": [
-                                    {
-                                      "$ref": "$map/item/value"
-                                    }
-                                  ]
-                                }
-                              ]
-                            },
-                            "children": [
+                          "onchange": {
+                            "$prototype": "Function",
+                            "body": [
                               {
-                                "tagName": "span",
-                                "textContent": "${$map.item.label}"
+                                "operator": "call",
+                                "target": {
+                                  "$ref": "#/state/setDeveloperPanels"
+                                },
+                                "value": [
+                                  {
+                                    "$ref": "event#/target/checked"
+                                  }
+                                ]
                               }
                             ]
-                          }
+                          },
+                          "children": [
+                            {
+                              "tagName": "span",
+                              "textContent": "Show developer panels"
+                            }
+                          ]
+                        },
+                        {
+                          "tagName": "p",
+                          "attributes": {
+                            "part": "developer-note"
+                          },
+                          "textContent": "Puts Files and Packages on the Design rail. Both stay in the command palette either way."
                         }
                       ]
                     }

package/src/surfaces/preferences.ts

@@ -27,17 +27,18 @@
  * @docs studio/interface/preferences
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
-import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { whenReady } from "./dialog";
 import preferencesDoc from "./preferences.json";
-import type { JxElement, JxDocument } 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("preferences", preferencesDoc as unknown as JxDocument);
+registerSurface("preferences", preferencesDoc);
 
 /** One row of the section list. `current` is the string `aria-current` takes. */
 export interface PreferencesSectionRow {
@@ -110,6 +111,8 @@ export interface PreferencesView {
   sectionTitle: string;
   sectionBlurb: string;
   themes: PreferencesThemeRow[];
+  /** Whether **Show developer panels** is on: Files and Packages on the Design rail (§5.1). */
+  developerPanels: boolean;
   accounts: PreferencesAccountRow[];
   /** Why there is no keyboard sheet at all. Empty means there is one. */
   keyboardEmpty: string;
@@ -137,6 +140,8 @@ export interface PreferencesSurfaceOptions {
   view: PreferencesView;
   onSelectSection: (id: string) => void;
   onSetTheme: (value: string) => void;
+  /** The **Show developer panels** switch moved. */
+  onSetDeveloperPanels: (show: boolean) => void;
   /** One account button was pressed, named by its `"<account>/<action>"` key. */
   onAccountAction: (key: string) => void;
   onKeyQuery: (value: string) => void;
@@ -173,9 +178,10 @@ interface PreferencesFlags {
   hasConflict: boolean;
 }
 
-interface PreferencesScope extends Record<string, unknown>, PreferencesView, PreferencesFlags {
+interface PreferencesScope extends PreferencesView, PreferencesFlags {
   selectSection: (id: string) => void;
   setTheme: (value: string) => void;
+  setDeveloperPanels: (show: boolean) => void;
   runAccountAction: (key: string) => void;
   setKeyQuery: (value: string) => void;
   toggleKeystroke: () => void;
@@ -199,8 +205,8 @@ function derive(view: PreferencesView): PreferencesView & PreferencesFlags {
 
 /** 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 : "";
 }
 
 /**
@@ -234,10 +240,16 @@ export function openPreferencesSurface(
     closed = true;
     options.onClosed();
   };
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
 
-  const scope = reactive({
+  const scope: PreferencesScope = reactive<PreferencesScope>({
     ...derive(options.view),
     capture: (_scope: JxScope, event: Event) => {
+      /* SAFETY: `preferences.json` names `capture` in exactly one place, the keys sheet's
+         `onkeydown`, so the event the runtime hands it is always the platform's `KeyboardEvent`. */
       options.onCaptureKey(event as KeyboardEvent);
     },
     closed: finish,
@@ -258,6 +270,9 @@ export function openPreferencesSurface(
       scope.keyQuery = value;
       options.onKeyQuery(value);
     },
+    setDeveloperPanels: (show: boolean) => {
+      options.onSetDeveloperPanels(show);
+    },
     setTheme: (value: string) => {
       options.onSetTheme(value);
     },
@@ -270,7 +285,7 @@ export function openPreferencesSurface(
     toggleRebind: (commandId: string) => {
       options.onToggleRebind(commandId);
     },
-  }) as PreferencesScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("preferences", scope, slot, {
@@ -287,13 +302,16 @@ export function openPreferencesSurface(
     },
   }).then(async (surface) => {
     mounted = surface;
+    /* SAFETY: `preferences.json`'s root definition carries `tagName: "jx-dialog"`, so the runtime
+       mounts an HTMLElement; a `Text` root only comes from a document whose root is a bare
+       string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     /* The region goes on the platform's own `<dialog>`, which is the one element here that HAS a
@@ -323,7 +341,7 @@ export function openPreferencesSurface(
       const element = mounted?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it came from; then the document.
-        closeDialog(element);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does — `finish` tells it so.
       mounted?.dispose();

package/src/surfaces/progress-modal.ts

@@ -21,13 +21,12 @@
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import { overlayRegion, REGION_ATTR } from "../ui/regions";
-import { close as closeDialog, showModal } from "@jxsuite/ui/behaviors/dialog";
+import { close, showModal } from "@jxsuite/ui/behaviors/dialog";
 import { whenReady } from "./dialog";
 import progressDoc from "./progress-modal.json";
 import type { SurfaceHandle } from "../ui/surface";
-import type { JxDocument } from "@jxsuite/schema/types";
 
-registerSurface("progress-modal", progressDoc as unknown as JxDocument);
+registerSurface("progress-modal", progressDoc);
 
 /** What the flow hands the surface. Everything is a projection; the flow keeps the operation. */
 export interface ProgressSurfaceOptions {
@@ -64,7 +63,7 @@ export interface ProgressSurfaceHandle {
   close: () => void;
 }
 
-interface ProgressScope extends Record<string, unknown> {
+interface ProgressScope {
   title: string;
   status: string;
   /**
@@ -91,7 +90,11 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
   options.layer.append(slot);
 
   let closed = false;
-  const scope = reactive<ProgressScope>({
+  /* Read through a call, not the bare binding: `close()` can run while the mount is awaiting the
+     element, and a direct `closed` test after that `await` would be narrowed to the value the test
+     before it saw. */
+  const isClosed = (): boolean => closed;
+  const scope: ProgressScope = reactive<ProgressScope>({
     background: () => {
       options.onBackground();
     },
@@ -104,12 +107,15 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
     },
     status: options.status,
     title: options.title,
-  }) as ProgressScope;
+  });
 
   let mounted: SurfaceHandle | null = null;
   const ready = mountSurface("progress-modal", scope, slot).then(async (surface) => {
+    /* SAFETY: `progress-modal.json`'s root definition carries `tagName: "jx-dialog"`, so the
+       runtime mounts an HTMLElement; a `Text` root only comes from a document whose root is a
+       bare string. */
     const element = surface.root as HTMLElement;
-    if (closed) {
+    if (isClosed()) {
       surface.dispose();
       return element;
     }
@@ -118,7 +124,7 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
        DOCUMENT rendered, while the element's OWN template is one `connectedCallback` later.
        `showModal` in between finds no `<dialog>` to open, and the surface never shows. */
     await whenReady(element);
-    if (closed) {
+    if (isClosed()) {
       return element;
     }
     showModal(element);
@@ -134,7 +140,7 @@ export function openProgressSurface(options: ProgressSurfaceOptions): ProgressSu
       const element = mounted?.root;
       if (element instanceof HTMLElement) {
         // The platform's close first, so focus goes back where it came from; then the document.
-        closeDialog(element);
+        close(element);
       }
       // A mount that has not landed yet is disposed by `ready` when it does.
       mounted?.dispose();

package/src/surfaces/properties-panel.json

@@ -629,7 +629,7 @@
                             "display": "contents"
                           },
                           "$switch": {
-                            "$ref": "$map/item/shape"
+                            "$ref": "$map/item/variant"
                           },
                           "cases": {
                             "field": {

package/src/surfaces/properties-panel.ts

@@ -31,14 +31,16 @@
  * @docs studio/design/properties
  */
 
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
 import { reactive } from "../reactivity";
 import { mountSurface, registerSurface } from "../ui/surface";
 import propertiesPanelDoc from "./properties-panel.json";
-import type { SurfaceHandle } from "../ui/surface";
+import type { SurfaceAction, SurfaceHandle, SurfaceOption } from "../ui/surface";
+import type { ColorTokenView } from "../ui/color-selector";
 import type { JxScope } from "@jxsuite/runtime/types";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxElement } from "@jxsuite/schema/types";
 
-registerSurface("properties-panel", propertiesPanelDoc as unknown as JxDocument);
+registerSurface("properties-panel", propertiesPanelDoc);
 
 /** Which control a `field` row draws. The flow picks it; the document switches on it. */
 export type ContentFieldKind =
@@ -52,25 +54,7 @@ export type ContentFieldKind =
   | "control";
 
 /** What a row is drawn as. Everything a section body can hold is one of these. */
-export type ContentRowShape = "field" | "kv" | "note" | "action" | "file";
-
-/**
- * One colour the project has named, as a `color` row's palette draws it.
- *
- * The same three fields the Style tab projects, and for the same reason: `value` is the reference a
- * click commits, `color` is only how it reads on screen, and `label` is what a reader hears.
- */
-export interface ContentTokenView extends Record<string, unknown> {
-  value: string;
-  color: string;
-  label: string;
-}
-
-/** A choice a select offers, in the shape the kit's select reads. */
-export interface ContentOption {
-  value: string;
-  label: string;
-}
+export type ContentRowVariant = "field" | "kv" | "note" | "action" | "file";
 
 /**
  * One row of a section — every field already decided, whatever shape it is.
@@ -81,7 +65,7 @@ export interface ContentOption {
 export interface ContentRowView {
   /** The row's reconcile identity AND what every callback hands back. */
   key: string;
-  shape: ContentRowShape;
+  variant: ContentRowVariant;
   /** `data-prop` — what `inspector/field:<prop>` addresses. Every shape carries one. */
   prop: string;
   /** The visible label of a `field`; the accessible name of a `kv` pair's controls. */
@@ -99,9 +83,9 @@ export interface ContentRowView {
   /** Draw the text control monospaced — a template, a pointer, a code-ish value. */
   mono: boolean;
   /** Choices for `select`; the routes or the popover ids for a `link`'s value half. */
-  options: ContentOption[];
+  options: SurfaceOption[];
   /** The palette a `color` row offers inside its picker, and whether it has one to offer. */
-  tokens: ContentTokenView[];
+  tokens: ColorTokenView[];
   hasTokens: boolean;
   /**
    * The provenance chip's shape: `""` draws nothing (§6.7's `default` state, where absence IS the
@@ -125,7 +109,7 @@ export interface ContentRowView {
   source: string;
   /** A `link` row's kind half: the chosen kind, and the five it chooses between. */
   linkKind: string;
-  kindOptions: ContentOption[];
+  kindOptions: SurfaceOption[];
   /** `route` draws a picker of the site's own routes; `text` draws a field. */
   linkValueKind: string;
   /** A `kv` pair's key cell, and the remove button's accessible name. */
@@ -151,12 +135,6 @@ export interface ContentSectionView {
   rows: ContentRowView[];
 }
 
-/** A button an empty state offers — the action that fills the region. */
-export interface ContentEmptyAction {
-  id: string;
-  label: string;
-}
-
 /** Everything the document reads. */
 export interface ContentPanelView {
   /**
@@ -168,7 +146,7 @@ export interface ContentPanelView {
   emptyMessage: string;
   emptyDetail: string;
   hasEmptyDetail: boolean;
-  emptyActions: ContentEmptyAction[];
+  emptyActions: SurfaceAction[];
   hasEmptyActions: boolean;
   /** The layout card: the tag clicked, its class, the file it came from. */
   layoutTag: string;
@@ -218,8 +196,7 @@ export interface ContentPanelSurface {
 /** A control host the document drew, reported as the runtime created it. */
 export type ContentControlSink = (key: string, host: HTMLElement) => void;
 
-interface ContentPanelScope
-  extends Record<string, unknown>, ContentPanelView, ContentPanelActions {}
+interface ContentPanelScope extends ContentPanelView, ContentPanelActions {}
 
 /** The scope's starting shape, before the first projection lands on it. */
 export function emptyContentView(): ContentPanelView {
@@ -267,15 +244,16 @@ function controlKeyOf(part: string, state: JxScope | undefined): string {
   if (part !== "control-host") {
     return "";
   }
-  const item = (state?.["$map"] as { item?: Record<string, unknown> } | undefined)?.item;
-  const key = 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 : "";
 }
 
 /** 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 : "";
+  const part = isString(def) ? undefined : def.attributes?.["part"];
+  return isString(part) ? part : "";
 }
 
 /**
@@ -296,10 +274,10 @@ export function mountContentSurface(
   actions: ContentPanelActions,
   onControlHost: ContentControlSink,
 ): ContentPanelSurface {
-  const scope = reactive<ContentPanelScope>({
+  const scope: ContentPanelScope = reactive<ContentPanelScope>({
     ...emptyContentView(),
     ...actions,
-  }) as ContentPanelScope;
+  });
   project(scope, values);
 
   let mounted: SurfaceHandle | null = null;