@jxsuite/studio 4.0.0 → 5.0.0

package/src/surfaces/grid-cell.ts

@@ -0,0 +1,120 @@
+/// <reference lib="dom" />
+/**
+ * The grid's cell value picker, as a mounted document.
+ *
+ * This is the adapter. `grid/cell-popovers.ts` is the flow — which kinds edit this way, what a
+ * relationship column points at, what a pick writes through the edit buffer — and this is the panel
+ * it draws into.
+ *
+ * **The media picker is an ISLAND** (specs/studio-ui-guidelines.md §9.4), and it stayed one when it
+ * became a document. The document draws `[part="picker-host"]` empty and the CALLER fills it
+ * through {@link GridCellSurfaceOptions.island} — the same seam `surfaces/dialog.ts` gives a rich
+ * dialog body. What goes in the box is the decision of the module that owns the box's contents,
+ * which is why this adapter does not name the media picker at all.
+ *
+ * @docs studio/editing/grid
+ */
+
+import { reactive } from "../reactivity";
+import { openPopoverSurface } from "../ui/popover-surface";
+import { registerSurface } from "../ui/surface";
+import gridCellDoc from "./grid-cell.json";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import type { JxPath } from "@jxsuite/runtime/types";
+import type { PopoverSurfaceHandle } from "../ui/popover-surface";
+
+registerSurface("grid-cell", gridCellDoc as unknown as JxDocument);
+
+/** The slot id, and so the panel's region: `overlay.popover:grid/cell`. */
+const SLOT = "grid/cell";
+
+/** One row of a relationship column's list. */
+export interface GridCellOption {
+  value: string;
+  label: string;
+}
+
+/** Everything the panel draws. */
+export interface GridCellView {
+  x: number;
+  y: number;
+  /** The column's title — the panel's heading and its accessible name. */
+  title: string;
+  /** Which of the two pickers is drawn. */
+  kind: "reference" | "image";
+  /** "Entries of “post”", when the column names a target type. */
+  hint: string;
+  hintState: "hidden" | "shown";
+  options: GridCellOption[];
+  /** What the list holds; empty when the current value is not one of its rows. */
+  value: string;
+  /** What the free-text field holds: the current value when no row matches it. */
+  custom: string;
+}
+
+export interface GridCellSurfaceOptions {
+  view: GridCellView;
+  /** A pick, from either control. The empty string means "no value". */
+  pick: (value: string) => void;
+  /** Fill the media picker's host, once it exists. Only called for an `image` column. */
+  island?: (host: HTMLElement) => void;
+  /** The platform closed the panel, or Done was pressed. */
+  dismissed?: () => void;
+}
+
+export type GridCellSurfaceHandle = PopoverSurfaceHandle;
+
+interface GridCellScope extends Record<string, unknown>, GridCellView {
+  pick: (value: string) => void;
+  done: () => void;
+}
+
+/** 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 : "";
+}
+
+/**
+ * Open the cell value picker.
+ *
+ * @param {GridCellSurfaceOptions} options
+ * @returns {GridCellSurfaceHandle}
+ */
+export function openGridCellSurface(options: GridCellSurfaceOptions): GridCellSurfaceHandle {
+  const { view } = options;
+  const scope = reactive<GridCellScope>({
+    custom: view.custom,
+    done: () => {
+      handle.close();
+      options.dismissed?.();
+    },
+    hint: view.hint,
+    hintState: view.hintState,
+    kind: view.kind,
+    options: view.options,
+    pick: options.pick,
+    title: view.title,
+    value: view.value,
+    x: view.x,
+    y: view.y,
+  }) as GridCellScope;
+
+  const handle = openPopoverSurface({
+    anchor: null,
+    name: "grid-cell",
+    scope,
+    slot: SLOT,
+    ...(options.dismissed ? { onDismissed: options.dismissed } : {}),
+    ...(options.island
+      ? {
+          onNodeCreated: (element: HTMLElement | Text, _path: JxPath, def: JxElement | string) => {
+            if (partOf(def) === "picker-host" && element instanceof HTMLElement) {
+              options.island?.(element);
+            }
+          },
+        }
+      : {}),
+  });
+  return handle;
+}

package/src/surfaces/grid-open.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioGridOpen",
+  "$description": "Every grid-able source a project has, grouped by where it comes from: the project's own pages and content collections first, then each connection's tables. It is the ISLAND of a confirm dialog rather than a dialog of its own — `ui/layers.ts`'s dialog owns the headline, the cancel button, modality and focus, and this document is only the list — because a second answer to \"what is a dialog\" is a defect (§12.5). Group headings are why it is not the kit menu: a menu row can carry a divider above it and cannot carry a name for the run it opens.",
+  "tagName": "div",
+  "attributes": {
+    "part": "sources"
+  },
+  "style": {
+    "display": "flex",
+    "flexDirection": "column",
+    "gap": "var(--jx-space-3)",
+    "minWidth": "280px",
+    "fontFamily": "var(--jx-font-sans)",
+    "fontSize": "var(--jx-text-md)",
+    "color": "var(--fg)",
+    "& [part=\"group-title\"]": {
+      "margin": "0",
+      "fontSize": "var(--jx-text-xs)",
+      "fontWeight": "600",
+      "textTransform": "uppercase",
+      "letterSpacing": "0.04em",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"rows\"]": {
+      "display": "flex",
+      "flexDirection": "column",
+      "gap": "1px",
+      "marginTop": "var(--jx-space-1)"
+    },
+    "& [part=\"source\"]": {
+      "textAlign": "left",
+      "background": "none",
+      "border": "none",
+      "color": "var(--fg)",
+      "font": "inherit",
+      "padding": "var(--jx-space-2) var(--jx-space-2)",
+      "borderRadius": "var(--jx-radius-sm)",
+      "cursor": "pointer"
+    },
+    "& [part=\"source\"]:hover": {
+      "background": "var(--bg-hover)"
+    },
+    "& [part=\"source\"]:focus-visible": {
+      "outline": "var(--jx-focus-ring)",
+      "outlineOffset": "-2px"
+    },
+    "& [part=\"group-empty\"]": {
+      "margin": "0",
+      "padding": "var(--jx-space-2)",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)"
+    }
+  },
+  "children": [
+    {
+      "$prototype": "Array",
+      "items": {
+        "$ref": "#/state/groups"
+      },
+      "key": {
+        "$ref": "$map/item/key"
+      },
+      "map": {
+        "$description": "One origin of grid-able sources. A connection with no tables says why it has none instead of drawing an empty box — an author who has not pushed a schema yet is exactly the reader who needs the sentence.",
+        "tagName": "section",
+        "attributes": {
+          "part": "group",
+          "data-group": "${$map.item.key}"
+        },
+        "children": [
+          {
+            "tagName": "h3",
+            "attributes": {
+              "part": "group-title"
+            },
+            "textContent": "${$map.item.title}"
+          },
+          {
+            "tagName": "div",
+            "attributes": {
+              "part": "rows"
+            },
+            "$switch": {
+              "$ref": "$map/item/state"
+            },
+            "cases": {
+              "listed": {
+                "tagName": "div",
+                "attributes": {
+                  "part": "rows-list",
+                  "role": "none"
+                },
+                "style": {
+                  "display": "contents"
+                },
+                "children": [
+                  {
+                    "$prototype": "Array",
+                    "items": {
+                      "$ref": "$map/item/rows"
+                    },
+                    "key": {
+                      "$ref": "$map/item/id"
+                    },
+                    "map": {
+                      "tagName": "button",
+                      "attributes": {
+                        "part": "source",
+                        "type": "button",
+                        "data-source": "${$map.item.id}"
+                      },
+                      "onclick": {
+                        "$prototype": "Function",
+                        "body": [
+                          {
+                            "operator": "call",
+                            "target": {
+                              "$ref": "#/state/open"
+                            },
+                            "value": [
+                              {
+                                "$ref": "$map/item/id"
+                              }
+                            ]
+                          }
+                        ]
+                      },
+                      "textContent": "${$map.item.label}"
+                    }
+                  }
+                ]
+              },
+              "empty": {
+                "tagName": "p",
+                "attributes": {
+                  "part": "group-empty"
+                },
+                "textContent": "${$map.item.emptyMessage}"
+              }
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/surfaces/grid-open.ts

@@ -0,0 +1,87 @@
+/// <reference lib="dom" />
+/**
+ * The Open Grid source list, as a mounted document.
+ *
+ * This is the adapter. `grid/grid-open.ts` is the flow — which collections a project declares,
+ * whether the platform serves the data routes, what each row opens — and this is the list it
+ * draws.
+ *
+ * **It is an island inside the confirm dialog, not a dialog of its own.** `ui/layers.ts` owns the
+ * headline, the cancel button, modality, focus and Escape; a second answer to "what is a dialog" is
+ * a defect (specs/studio-ui-guidelines.md §12.5). What is here is the part that is genuinely this
+ * surface's: sources grouped by where they come from, with a heading per group — which is also why
+ * it is not the kit menu, whose rows can carry a divider above them and cannot carry a name for the
+ * run they open.
+ *
+ * @docs studio/data/grid
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import gridOpenDoc from "./grid-open.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("grid-open", gridOpenDoc as unknown as JxDocument);
+
+/** One openable source. The id is opaque here: only the flow knows what it names. */
+export interface GridSourceRow {
+  id: string;
+  label: string;
+}
+
+/** One origin of sources — the project itself, or one connection. */
+export interface GridSourceGroup {
+  /** The group's identity across repaints. */
+  key: string;
+  title: string;
+  state: "listed" | "empty";
+  rows: GridSourceRow[];
+  /** Why the group is empty, in a sentence. Empty when it is not. */
+  emptyMessage: string;
+}
+
+export interface GridOpenSurfaceHandle {
+  /** Resolves with the list's root once it has rendered. */
+  ready: Promise<HTMLElement>;
+  dispose: () => void;
+}
+
+interface GridOpenScope extends Record<string, unknown> {
+  groups: GridSourceGroup[];
+  open: (id: string) => void;
+}
+
+/**
+ * Mount the source list into `host`.
+ *
+ * @param {HTMLElement} host - The dialog's island node
+ * @param {GridSourceGroup[]} groups - What to list
+ * @param {(id: string) => void} open - What a row does
+ * @returns {GridOpenSurfaceHandle}
+ */
+export function mountGridOpenSurface(
+  host: HTMLElement,
+  groups: GridSourceGroup[],
+  open: (id: string) => void,
+): GridOpenSurfaceHandle {
+  const scope = reactive<GridOpenScope>({ groups, open }) as GridOpenScope;
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  const ready = mountSurface("grid-open", scope, host).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return surface.root as HTMLElement;
+    }
+    mounted = surface;
+    return surface.root as HTMLElement;
+  });
+  return {
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+  };
+}