@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/panel-elements.json

@@ -0,0 +1,367 @@
+{
+  "$schema": "https://jxsuite.com/schema/v1",
+  "$id": "StudioPanelElements",
+  "$description": "The Insert panel: the palette a page is built out of. One filter, then one accordion — the project's own components first, then the HTML elements by category — and a card per thing that can be inserted. The adapter (`surfaces/panel-elements.ts`) is handed sections whose cards are already filtered, already open or closed, and already carry the tag they insert, so nothing here asks what an element is, which npm components the document has enabled, or what the filter means. A card is inserted by CLICK from this document and by DRAG from `panels/dnd.ts`, which registers against the painted card — that seam is why three class names survive the conversion, and the style block says why.",
+  "tagName": "div",
+  "attributes": {
+    "part": "palette"
+  },
+  "style": {
+    "$description": "What this block does NOT contain is most of the conversion. `.elements-list` and `.elements-list sp-accordion-item` are gone rather than moved: the first removed a border Spectrum's accordion drew and the kit's does not, and the second drew the hairline between two sections and set an 11px header — `jx-accordion` draws that separator itself (`& > :not([hidden]) ~ *`) and `jx-accordion-item` owns its own summary, so transcribing either would be re-deciding something the kit has already decided. `.element-card`, `.element-card-preview` and `.element-card-label` are NOT this document's to take, and that is why they are still spelled as classes here: the same card is drawn by `panels/stylebook-doc.ts` for its specimens and re-declared inside the canvas iframe by `canvas/iframe-render.ts`, and `panels/dnd.ts` addresses `.components-section` and `.element-card-preview` BY SELECTOR to hang the drag on a row and to fill its preview with a live element. A card is a shared object with three readers; moving its look in here would fork it. An element card's preview is drawn EMPTY for the same reason: `dnd.ts` fills it with the element rendered live, and it fills only a preview it finds with no children in it. What is left below is what belongs to the palette alone.",
+    "display": "flex",
+    "flexDirection": "column",
+    "minHeight": "0",
+    "fontFamily": "var(--jx-font-sans)",
+    "color": "var(--fg)",
+    "& [part=\"filter\"]": {
+      "$description": "The filter is inset from the panel's edges; `.panel-body` sets `padding: 0`, so the field sat flush against three of them. It stretches because the palette is a flex column, which is also what `sp-search` got for free from being a block.",
+      "margin": "var(--jx-space-2)"
+    },
+    "& [part=\"empty\"]": {
+      "$description": "The one empty-state pattern (`panels/empty-state.ts`), drawn here because a document cannot render a lit helper. `.empty-state` and `.empty-state--teach` keep their stylesheet — every panel still lit renders through that helper — so this is a copy rather than a move, and it goes when the last of them converts. Its 13px was the one value with no token behind it; the kit's `--jx-text-md` is the scale this chrome is on.",
+      "display": "flex",
+      "flexDirection": "column",
+      "alignItems": "center",
+      "gap": "var(--jx-space-3)",
+      "padding": "var(--jx-space-6)",
+      "textAlign": "center",
+      "fontSize": "var(--jx-text-md)",
+      "color": "var(--fg-dim)"
+    },
+    "& [part=\"empty-message\"]": {
+      "margin": "0",
+      "maxWidth": "34ch",
+      "lineHeight": "1.5"
+    },
+    "& [part=\"component-tag\"]": {
+      "$description": "What a component card shows until `panels/dnd.ts` replaces it with the component rendered live. It was an inline `style=` reading `--spectrum-font-size-50` with an 11px fallback — a name that resolves only inside `<sp-theme>`, and this document is mounted into the Navigator's panel body, where that element is not an ancestor — so the size is the kit's scale and the colour the studio layer's.",
+      "color": "var(--fg-dim)",
+      "fontSize": "var(--jx-text-sm)",
+      "fontStyle": "italic"
+    }
+  },
+  "children": [
+    {
+      "tagName": "jx-textfield",
+      "attributes": {
+        "part": "filter"
+      },
+      "$props": {
+        "size": "sm",
+        "type": "search",
+        "clearable": true,
+        "label": "Filter elements",
+        "placeholder": "Filter elements…",
+        "value": {
+          "$ref": "#/state/filter"
+        }
+      },
+      "oninput": {
+        "$prototype": "Function",
+        "body": [
+          {
+            "operator": "call",
+            "target": {
+              "$ref": "#/state/setFilter"
+            },
+            "value": [
+              {
+                "$ref": "event#/target/value"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "tagName": "div",
+      "attributes": {
+        "part": "empty-slot",
+        "role": "none"
+      },
+      "style": {
+        "display": "contents"
+      },
+      "$switch": {
+        "$ref": "#/state/emptyState"
+      },
+      "cases": {
+        "filtered": {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty-message"
+              },
+              "textContent": "Nothing here matches “${state.filter}”."
+            },
+            {
+              "tagName": "div",
+              "attributes": {
+                "part": "empty-actions"
+              },
+              "children": [
+                {
+                  "tagName": "jx-button",
+                  "$props": {
+                    "size": "sm"
+                  },
+                  "attributes": {
+                    "part": "clear-filter"
+                  },
+                  "onclick": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/clearFilter"
+                        }
+                      }
+                    ]
+                  },
+                  "children": [
+                    {
+                      "tagName": "span",
+                      "textContent": "Clear the filter"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        },
+        "empty": {
+          "tagName": "div",
+          "attributes": {
+            "part": "empty"
+          },
+          "children": [
+            {
+              "tagName": "p",
+              "attributes": {
+                "part": "empty-message"
+              },
+              "textContent": "Elements you can drop onto the page live here — text, images, layout containers and your own components."
+            }
+          ]
+        }
+      }
+    },
+    {
+      "tagName": "jx-accordion",
+      "attributes": {
+        "part": "list"
+      },
+      "children": [
+        {
+          "tagName": "div",
+          "attributes": {
+            "part": "components-slot",
+            "role": "none",
+            "hidden": "${state.hasComponents ? null : ''}"
+          },
+          "style": {
+            "$description": "The section stands or falls as a whole, so the slot is `display: contents` — the accordion item inside it has to be the accordion's own layout child. `hidden` is what keeps the separator honest: `jx-accordion` gives a top border to every child that FOLLOWS a visible one, so an empty slot left visible would draw a line above the first category with nothing above it.",
+            "display": "contents"
+          },
+          "$switch": {
+            "$ref": "#/state/hasComponents"
+          },
+          "cases": {
+            "true": {
+              "tagName": "jx-accordion-item",
+              "$props": {
+                "label": "Components",
+                "open": {
+                  "$ref": "#/state/componentsOpen"
+                }
+              },
+              "attributes": {
+                "data-section": "components"
+              },
+              "ontoggle": {
+                "$prototype": "Function",
+                "body": [
+                  {
+                    "operator": "call",
+                    "target": {
+                      "$ref": "#/state/setComponentsOpen"
+                    },
+                    "value": [
+                      {
+                        "$ref": "event#/detail"
+                      }
+                    ]
+                  }
+                ]
+              },
+              "children": [
+                {
+                  "tagName": "div",
+                  "attributes": {
+                    "class": "components-section"
+                  },
+                  "children": [
+                    {
+                      "$prototype": "Array",
+                      "items": {
+                        "$ref": "#/state/components"
+                      },
+                      "key": {
+                        "$ref": "$map/item/tagName"
+                      },
+                      "map": {
+                        "tagName": "div",
+                        "attributes": {
+                          "class": "element-card",
+                          "data-component-tag": "${$map.item.tagName}",
+                          "title": "${$map.item.title}"
+                        },
+                        "onclick": {
+                          "$prototype": "Function",
+                          "body": [
+                            {
+                              "operator": "call",
+                              "target": {
+                                "$ref": "#/state/insertComponent"
+                              },
+                              "value": [
+                                {
+                                  "$ref": "$map/item/tagName"
+                                }
+                              ]
+                            }
+                          ]
+                        },
+                        "children": [
+                          {
+                            "tagName": "div",
+                            "attributes": {
+                              "class": "element-card-preview"
+                            },
+                            "children": [
+                              {
+                                "tagName": "span",
+                                "attributes": {
+                                  "part": "component-tag"
+                                },
+                                "textContent": "<${$map.item.tagName}>"
+                              }
+                            ]
+                          },
+                          {
+                            "tagName": "div",
+                            "attributes": {
+                              "class": "element-card-label"
+                            },
+                            "textContent": "${$map.item.tagName}"
+                          }
+                        ]
+                      }
+                    }
+                  ]
+                }
+              ]
+            }
+          }
+        },
+        {
+          "$prototype": "Array",
+          "items": {
+            "$ref": "#/state/categories"
+          },
+          "key": {
+            "$ref": "$map/item/name"
+          },
+          "map": {
+            "tagName": "jx-accordion-item",
+            "$props": {
+              "label": {
+                "$ref": "$map/item/name"
+              },
+              "open": {
+                "$ref": "$map/item/open"
+              }
+            },
+            "attributes": {
+              "data-section": "${$map.item.name}"
+            },
+            "ontoggle": {
+              "$prototype": "Function",
+              "body": [
+                {
+                  "operator": "call",
+                  "target": {
+                    "$ref": "#/state/setSectionOpen"
+                  },
+                  "value": [
+                    {
+                      "$ref": "$map/item/name"
+                    },
+                    {
+                      "$ref": "event#/detail"
+                    }
+                  ]
+                }
+              ]
+            },
+            "children": [
+              {
+                "$prototype": "Array",
+                "items": {
+                  "$ref": "$map/item/elements"
+                },
+                "key": {
+                  "$ref": "$map/item/tag"
+                },
+                "map": {
+                  "tagName": "div",
+                  "attributes": {
+                    "class": "element-card",
+                    "data-block-tag": "${$map.item.tag}"
+                  },
+                  "onclick": {
+                    "$prototype": "Function",
+                    "body": [
+                      {
+                        "operator": "call",
+                        "target": {
+                          "$ref": "#/state/insertElement"
+                        },
+                        "value": [
+                          {
+                            "$ref": "$map/item/tag"
+                          }
+                        ]
+                      }
+                    ]
+                  },
+                  "children": [
+                    {
+                      "tagName": "div",
+                      "attributes": {
+                        "class": "element-card-preview"
+                      }
+                    },
+                    {
+                      "tagName": "div",
+                      "attributes": {
+                        "class": "element-card-label"
+                      },
+                      "textContent": "<${$map.item.tag}>"
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}

package/src/surfaces/panel-elements.ts

@@ -0,0 +1,175 @@
+/// <reference lib="dom" />
+/**
+ * The Insert surface: the Navigator's element palette, as a Jx document over the kit.
+ *
+ * This is the adapter. `panels/elements-panel.ts` keeps the panel — what the palette contains,
+ * which npm components the open document has enabled, what the filter matches, and what a click
+ * inserts where — and hands this module a projection with no decisions left in it: a section per
+ * category that already knows whether it is open, a card per thing that can be inserted, and the
+ * one of three empty states the palette is in.
+ *
+ * The flattening is here rather than in the document for the reason `surfaces/settings-overview.ts`
+ * gives: `$switch` over a value is the only conditional a document has, and "is there anything to
+ * show, and is that because the filter matched nothing" is two questions.
+ *
+ * **The filter value is an echo.** `setFilter` is handed what the field now holds and the panel
+ * writes exactly that back into the scope — not a normalised form of it. A binding only writes when
+ * the scope value changes, so a scope holding the lower-cased text while the field holds what was
+ * typed is a binding that fires on every keystroke and puts the reader's caret back at the end of a
+ * word it just rewrote. Matching lower-cases at the point of comparison instead.
+ *
+ * **The container is NOT cleared**, which is the difference between a panel and a settings section.
+ * A section is handed the pane's whole content area; a panel is handed `.panel-content`, a node lit
+ * owns and renders `nothing` into, so its markers are already there and taking them out would leave
+ * lit holding a part whose ends are detached. Appending beside them is safe both ways: a repaint of
+ * the same panel commits `nothing` again, which lit skips, and a switch to another panel commits
+ * that panel's template, which clears to the end of the parent and takes this document with it.
+ * {@link ElementsSurfaceHandle.connected} is then how the panel finds out.
+ *
+ * @docs studio/design/elements
+ */
+
+import { reactive } from "../reactivity";
+import { mountSurface, registerSurface } from "../ui/surface";
+import elementsDoc from "./panel-elements.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("panel-elements", elementsDoc as unknown as JxDocument);
+
+/** One insertable HTML element: the tag is its identity, its caption and what a click inserts. */
+export interface ElementCardView {
+  tag: string;
+}
+
+/** One category of the palette — an accordion section, keyed and labelled by its name. */
+export interface ElementCategoryView {
+  name: string;
+  open: boolean;
+  elements: ElementCardView[];
+}
+
+/** One insertable component. `title` is the row's tooltip: its package, or its path on disk. */
+export interface ComponentCardView {
+  tagName: string;
+  title: string;
+}
+
+/**
+ * Which body the palette is showing under its filter.
+ *
+ * `"filtered"` and `"empty"` are different answers rather than one with a flag: a palette nothing
+ * matches offers to clear the filter, and a palette with nothing in it teaches what the region is
+ * for, because there is no filter to clear.
+ */
+export type ElementsEmptyState = "none" | "filtered" | "empty";
+
+/** What the panel says the surface should be showing right now. */
+export interface ElementsValues {
+  /** What the filter field holds — the reader's own text, never a normalised form of it. */
+  filter: string;
+  categories: ElementCategoryView[];
+  components: ComponentCardView[];
+  componentsOpen: boolean;
+  hasComponents: boolean;
+  emptyState: ElementsEmptyState;
+}
+
+/** What a control can ask the panel to do. Every one of them is a decision the panel owns. */
+export interface ElementsActions {
+  setFilter: (value: string) => void;
+  clearFilter: () => void;
+  setSectionOpen: (name: string, open: boolean) => void;
+  setComponentsOpen: (open: boolean) => void;
+  insertElement: (tag: string) => void;
+  insertComponent: (tagName: string) => void;
+}
+
+export interface ElementsSurfaceHandle {
+  /** Bring the mounted document up to date. */
+  update: (values: ElementsValues) => void;
+  /**
+   * Settles once the document has rendered.
+   *
+   * The palette has an imperative step after every paint — `panels/dnd.ts` hangs the drag on each
+   * card and fills its preview — and a mount is asynchronous, so the panel needs somewhere to
+   * wait.
+   */
+  ready: Promise<void>;
+  /** Whether the document this mounted is still standing in the container it was given. */
+  connected: () => boolean;
+  /** Take the document down. Idempotent. */
+  dispose: () => void;
+}
+
+/** The scope the document reads: {@link ElementsValues} plus the actions its controls call. */
+interface ElementsScope extends Record<string, unknown>, ElementsValues, ElementsActions {}
+
+/** Write a projection into the scope. */
+function project(scope: ElementsScope, values: ElementsValues): void {
+  scope.filter = values.filter;
+  scope.categories = values.categories;
+  scope.components = values.components;
+  scope.componentsOpen = values.componentsOpen;
+  scope.hasComponents = values.hasComponents;
+  scope.emptyState = values.emptyState;
+}
+
+/**
+ * Mount the Insert document into `container`, wired to `actions`.
+ *
+ * @param {HTMLElement} container - The panel's `.panel-content`
+ * @param {ElementsValues} values - What to draw right now
+ * @param {ElementsActions} actions - What each control does
+ * @returns {ElementsSurfaceHandle}
+ */
+export function mountElementsSurface(
+  container: HTMLElement,
+  values: ElementsValues,
+  actions: ElementsActions,
+): ElementsSurfaceHandle {
+  const scope = reactive<ElementsScope>({
+    categories: [],
+    clearFilter: actions.clearFilter,
+    components: [],
+    componentsOpen: true,
+    emptyState: "none",
+    filter: "",
+    hasComponents: false,
+    insertComponent: actions.insertComponent,
+    insertElement: actions.insertElement,
+    setComponentsOpen: actions.setComponentsOpen,
+    setFilter: actions.setFilter,
+    setSectionOpen: actions.setSectionOpen,
+  }) as ElementsScope;
+  project(scope, values);
+
+  let mounted: SurfaceHandle | null = null;
+  let disposed = false;
+  /* Nothing is called on an element here, so the mount is all there is to wait for: the DOCUMENT is
+     what this surface renders, and the kit elements inside it settle their own templates one
+     `connectedCallback` later without anybody asking them to (§1.1, "await the element"). */
+  const ready = mountSurface("panel-elements", scope, container).then((surface) => {
+    if (disposed) {
+      surface.dispose();
+      return;
+    }
+    mounted = surface;
+  });
+
+  return {
+    /* In flight the answer is yes: nothing has landed yet, so there is nothing that could have been
+       taken away, and answering no would start a second mount racing the first. Once mounted the
+       question is whether the root is still in the container — a panel that was switched away from
+       had its document cleared out from under it by lit. */
+    connected: () =>
+      !disposed && (mounted === null || (mounted.root as Node).parentNode === container),
+    dispose() {
+      disposed = true;
+      mounted?.dispose();
+      mounted = null;
+    },
+    ready,
+    update: (next) => project(scope, next),
+  };
+}