@jxsuite/studio 4.1.0 → 5.0.0

package/src/panels/elements-panel.ts

@@ -1,204 +1,265 @@
 /// <reference lib="dom" />
-/** Elements panel — block/component palette with categorized accordion and search filter. */
+/**
+ * Elements panel — the Insert palette: the blocks and components a page is built out of.
+ *
+ * **The body is a Jx document** (`surfaces/panel-elements.json`, mounted by
+ * `surfaces/panel-elements.ts`), so `render` draws nothing and `afterRender` mounts. What stays
+ * here is everything that is a DECISION — which categories survive the filter, which npm components
+ * the open document has enabled, what a card inserts and where — projected into a scope whose every
+ * card already carries the tag it inserts. `afterRender` runs on every repaint, so
+ * {@link mountElementsPanel} is idempotent: the standing surface is updated where it is still
+ * there, and re-mounted only where lit has taken it out (which is what a switch to another panel
+ * does, because the document is appended into the `.panel-content` lit renders `nothing` into).
+ *
+ * **Filtering no longer repaints the Navigator, and that fixes a defect.** `panel-scheduler.ts`
+ * withholds a repaint while a text input inside the panel has focus — which is exactly when
+ * somebody is typing in the filter — so the palette used to sit stale, marked `data-jx-stale`,
+ * until the field was blurred. A document is updated in place instead: the cards that no longer
+ * match leave, the field is untouched, and no repaint is asked for at all.
+ *
+ * @docs studio/design/elements
+ */
 
-import { html, nothing } from "lit-html";
+import { nothing } from "lit-html";
+import { buildComponentInstance, componentRegistry } from "../files/components";
 import { childList, getNodeAtPath } from "../store";
-import { activeTab } from "../workspace/workspace";
+import { getEffectiveElements } from "../site-context";
+import { mountElementsSurface } from "../surfaces/panel-elements";
 import { mutateInsertNode, transactDoc } from "../tabs/transact";
 import { primarySelection } from "../tabs/selection";
-import { view } from "../view";
-import { getEffectiveElements } from "../site-context";
-import { buildComponentInstance, componentRegistry } from "../files/components";
-import { renderEmptyState } from "./empty-state";
 import { registerPanel } from "./panel-registry";
+import { activeTab } from "../workspace/workspace";
+import { view } from "../view";
 
 import type { ComponentEntry } from "../files/components";
+import type {
+  ComponentCardView,
+  ElementCategoryView,
+  ElementsActions,
+  ElementsSurfaceHandle,
+  ElementsValues,
+} from "../surfaces/panel-elements";
 import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
+import type { NavigatorPanelContext, NavigatorPanelDeps, PanelBody } from "./panel-registry";
+
+/** The palette's source of blocks, as `NavigatorPanelDeps.webdata` carries it. */
+interface ElementsWebdata {
+  elements: Record<string, { tag: string }[]>;
+}
+
+/** The Components section's name — its accordion label AND its key in `view.elementsCollapsed`. */
+const COMPONENTS = "Components";
+
+/**
+ * What the palette is built from, held at module scope rather than closed over at mount.
+ *
+ * The standing surface outlives the {@link NavigatorPanelContext} that mounted it — a card clicked
+ * ten repaints later must reach the CURRENT `defaultDef` and the current drag registrations — so
+ * the seat is rewritten on every `afterRender` and the actions read it rather than a captured
+ * copy.
+ */
+let panelDeps: NavigatorPanelDeps | null = null;
 
 /**
- * @param {{
- *   webdata: { elements: Record<string, { tag: string }[]> };
- *   defaultDef: (tag: string) => JxMutableNode;
- *   rerender: () => void;
- * }} ctx
- * @returns {import("lit-html").TemplateResult}
+ * The surface standing in the Navigator, and the node it was mounted into.
+ *
+ * One slot rather than a per-host map, because there is one Navigator: a mount into a DIFFERENT
+ * node is the old one being replaced, and holding both would leave the first one's effects running
+ * against a scope nobody writes any more.
  */
-export function renderElementsTemplate(ctx: {
-  webdata: { elements: Record<string, { tag: string }[]> };
-  defaultDef: (tag: string) => JxMutableNode;
-  rerender: () => void;
-}) {
-  const tab = activeTab.value;
+let standing: { host: HTMLElement; handle: ElementsSurfaceHandle } | null = null;
 
-  const categories = Object.entries(ctx.webdata.elements).map(
-    (/** @type {[string, { tag: string }[]]} */ [category, elements]) => {
-      const filtered = view.elementsFilter
-        ? elements.filter((/** @type {{ tag: string }} */ e) => e.tag.includes(view.elementsFilter))
-        : elements;
-      if (filtered.length === 0) {
-        return nothing;
-      }
+/** What the filter matches on: the reader's text, lower-cased at the point of comparison. */
+function needle(): string {
+  return view.elementsFilter.toLowerCase();
+}
 
-      return html`
-        <sp-accordion-item
-          label=${category}
-          ?open=${!view.elementsCollapsed.has(category)}
-          @sp-accordion-item-toggle=${(e: Event) => {
-            if ((e.target as HTMLElement & { open: boolean }).open) {
-              view.elementsCollapsed.delete(category);
-            } else {
-              view.elementsCollapsed.add(category);
-            }
-          }}
-        >
-          ${filtered.map((/** @type {{ tag: string }} */ { tag }) => {
-            const def = ctx.defaultDef(tag);
-            return html`
-              <div
-                class="element-card"
-                data-block-tag=${tag}
-                @click=${() => {
-                  const t = activeTab.value;
-                  const parentPath = primarySelection(t?.session.selection) ?? [];
-                  const parent = getNodeAtPath(t!.doc.document, parentPath);
-                  const idx = childList(parent).length;
-                  transactDoc(t!, (tr) =>
-                    mutateInsertNode(tr, parentPath, idx, structuredClone(def)),
-                  );
-                }}
-              >
-                <div class="element-card-preview"></div>
-                <div class="element-card-label">&lt;${tag}&gt;</div>
-              </div>
-            `;
-          })}
-        </sp-accordion-item>
-      `;
-    },
-  );
+/** The categories that still have something in them, with the filter applied. */
+function categoryViews(webdata: ElementsWebdata, filter: string): ElementCategoryView[] {
+  const sections: ElementCategoryView[] = [];
+  for (const [name, elements] of Object.entries(webdata.elements ?? {})) {
+    const matched = filter ? elements.filter((entry) => entry.tag.includes(filter)) : elements;
+    if (matched.length === 0) {
+      continue;
+    }
+    sections.push({
+      elements: matched.map(({ tag }) => ({ tag })),
+      name,
+      open: !view.elementsCollapsed.has(name),
+    });
+  }
+  return sections;
+}
 
-  const effectiveEls = getEffectiveElements(
+/**
+ * The tag names the open document's `$elements` turn on.
+ *
+ * An entry is either `<package>/<modulePath>`, which names one component, or a bare package, which
+ * names every component in it. A project component is not gated at all — it is in the project.
+ */
+function enabledNpmTags(): Set<string> {
+  const tab = activeTab.value;
+  const entries = getEffectiveElements(
     tab?.doc.document?.$elements as (string | JxElement)[] | undefined,
   );
-  const enabledTags = new Set<string>();
-  for (const entry of effectiveEls) {
+  const tags = new Set<string>();
+  for (const entry of entries) {
     if (typeof entry !== "string") {
       continue;
     }
-    const comp = componentRegistry.find(
-      (c: ComponentEntry) =>
-        c.source === "npm" && c.modulePath && entry === `${c.package}/${c.modulePath}`,
+    const named = componentRegistry.find(
+      (comp: ComponentEntry) =>
+        comp.source === "npm" && comp.modulePath && entry === `${comp.package}/${comp.modulePath}`,
     );
-    if (comp) {
-      enabledTags.add(comp.tagName);
-    } else {
-      for (const c of componentRegistry) {
-        if (c.source === "npm" && c.package === entry) {
-          enabledTags.add(c.tagName);
-        }
+    if (named) {
+      tags.add(named.tagName);
+      continue;
+    }
+    for (const comp of componentRegistry) {
+      if (comp.source === "npm" && comp.package === entry) {
+        tags.add(comp.tagName);
       }
     }
   }
-  const compsFiltered =
-    componentRegistry.length > 0
-      ? componentRegistry
-          .filter((c: ComponentEntry) => c.source !== "npm" || enabledTags.has(c.tagName))
-          .filter(
-            (c: ComponentEntry) =>
-              !view.elementsFilter || c.tagName.toLowerCase().includes(view.elementsFilter),
-          )
-      : [];
-
-  const componentsAccordion =
-    compsFiltered.length > 0
-      ? html`
-          <sp-accordion-item
-            label="Components"
-            ?open=${!view.elementsCollapsed.has("Components")}
-            @sp-accordion-item-toggle=${(e: Event) => {
-              if ((e.target as HTMLElement & { open: boolean }).open) {
-                view.elementsCollapsed.delete("Components");
-              } else {
-                view.elementsCollapsed.add("Components");
-              }
-            }}
-          >
-            <div class="components-section">
-              ${compsFiltered.map(
-                (comp: ComponentEntry) => html`
-                  <div
-                    class="element-card"
-                    data-component-tag=${comp.tagName}
-                    title=${
-                      comp.source === "npm" ? `${comp.package}: <${comp.tagName}>` : comp.path
-                    }
-                    @click=${() => {
-                      const t = activeTab.value;
-                      const parentPath = primarySelection(t?.session.selection) ?? [];
-                      const parent = getNodeAtPath(t!.doc.document, parentPath);
-                      const idx = childList(parent).length;
-                      const instanceDef = buildComponentInstance(comp);
-                      transactDoc(t!, (tr) =>
-                        mutateInsertNode(tr, parentPath, idx, structuredClone(instanceDef)),
-                      );
-                    }}
-                  >
-                    <div class="element-card-preview">
-                      <span
-                        style="color:var(--fg-dim);font-size:var(--spectrum-font-size-50, 11px);font-style:italic"
-                        >&lt;${comp.tagName}&gt;</span
-                      >
-                    </div>
-                    <div class="element-card-label">${comp.tagName}</div>
-                  </div>
-                `,
-              )}
-            </div>
-          </sp-accordion-item>
-        `
-      : nothing;
-
-  const nothingToShow =
-    componentsAccordion === nothing && categories.every((entry) => entry === nothing);
-
-  return html`
-    <sp-search
-      size="s"
-      placeholder="Filter elements…"
-      value=${view.elementsFilter}
-      @input=${(e: Event) => {
-        view.elementsFilter = (e.target as HTMLInputElement).value.toLowerCase();
-        ctx.rerender();
-      }}
-    ></sp-search>
-    ${
-      nothingToShow
-        ? renderEmptyState(
-            view.elementsFilter
-              ? {
-                  actions: [
-                    {
-                      label: "Clear the filter",
-                      run: () => {
-                        view.elementsFilter = "";
-                        ctx.rerender();
-                      },
-                    },
-                  ],
-                  message: `Nothing here matches “${view.elementsFilter}”.`,
-                }
-              : {
-                  message:
-                    "Elements you can drop onto the page live here — " +
-                    "text, images, layout containers and your own components.",
-                },
-          )
-        : nothing
+  return tags;
+}
+
+/** The component cards: the project's own, plus the npm ones this document has enabled. */
+function componentViews(filter: string): ComponentCardView[] {
+  if (componentRegistry.length === 0) {
+    return [];
+  }
+  const enabled = enabledNpmTags();
+  return componentRegistry
+    .filter((comp) => comp.source !== "npm" || enabled.has(comp.tagName))
+    .filter((comp) => !filter || comp.tagName.toLowerCase().includes(filter))
+    .map((comp) => ({
+      tagName: comp.tagName,
+      title:
+        comp.source === "npm" ? `${comp.package}: <${comp.tagName}>` : (comp.path ?? comp.tagName),
+    }));
+}
+
+/** Everything the document draws, as one value. */
+function panelValues(source: NavigatorPanelDeps): ElementsValues {
+  const filter = needle();
+  const categories = categoryViews(source.webdata as unknown as ElementsWebdata, filter);
+  const components = componentViews(filter);
+  const bare = categories.length === 0 && components.length === 0;
+  return {
+    categories,
+    components,
+    componentsOpen: !view.elementsCollapsed.has(COMPONENTS),
+    emptyState: bare ? (filter ? "filtered" : "empty") : "none",
+    /* The reader's own text, not `filter`: the field is bound to this, and a scope holding the
+       lower-cased form would rewrite what was typed on every keystroke. */
+    filter: view.elementsFilter,
+    hasComponents: components.length > 0,
+  };
+}
+
+/** Insert a node as the last child of the selected element — what both kinds of card do. */
+function insertAtSelection(def: JxMutableNode): void {
+  const tab = activeTab.value;
+  if (!tab) {
+    return;
+  }
+  const parentPath = primarySelection(tab.session.selection) ?? [];
+  const parent = getNodeAtPath(tab.doc.document, parentPath);
+  const index = childList(parent).length;
+  transactDoc(tab, (tr) => mutateInsertNode(tr, parentPath, index, structuredClone(def)));
+}
+
+/**
+ * Push a fresh projection into the standing surface, then re-register the drags.
+ *
+ * The drag registrations are deferred until the document has rendered: `mountSurface` resolving is
+ * what says the cards exist, and a mapped array coalesces its re-render into a microtask, so a
+ * registration that ran on the same turn as the write would walk the previous set of cards.
+ */
+function refresh(): void {
+  const seat = standing;
+  if (!seat || !panelDeps) {
+    return;
+  }
+  seat.handle.update(panelValues(panelDeps));
+  void seat.handle.ready.then(() => {
+    if (standing !== seat) {
+      return;
     }
-    <sp-accordion class="elements-list" allow-multiple
-      >${componentsAccordion}${categories}</sp-accordion
-    >
-  `;
+    panelDeps?.registerElementsDnD();
+    panelDeps?.registerComponentsDnD();
+  });
+}
+
+/** What the document's controls do. Every one of them is a decision this module owns. */
+const ACTIONS: ElementsActions = {
+  clearFilter: () => {
+    view.elementsFilter = "";
+    refresh();
+  },
+  insertComponent: (tagName) => {
+    const comp = componentRegistry.find((entry: ComponentEntry) => entry.tagName === tagName);
+    if (comp) {
+      insertAtSelection(buildComponentInstance(comp));
+    }
+  },
+  insertElement: (tag) => {
+    if (panelDeps) {
+      insertAtSelection(panelDeps.defaultDef(tag) as JxMutableNode);
+    }
+  },
+  setComponentsOpen: (open) => {
+    setCollapsed(COMPONENTS, !open);
+    refresh();
+  },
+  /* The echo: what the field now holds goes into the state the palette is filtered by, before
+     anything is decided about it. */
+  setFilter: (value) => {
+    view.elementsFilter = value;
+    refresh();
+  },
+  setSectionOpen: (name, open) => {
+    setCollapsed(name, !open);
+    refresh();
+  },
+};
+
+/** Remember a section's disclosure across repaints and across panel switches. */
+function setCollapsed(name: string, collapsed: boolean): void {
+  if (collapsed) {
+    view.elementsCollapsed.add(name);
+  } else {
+    view.elementsCollapsed.delete(name);
+  }
+}
+
+/**
+ * Draw the panel body — mounting the document the first time, updating it every time after.
+ *
+ * The document goes into `.panel-content`, not into the `.panel-body` this is handed. Both are
+ * lit's, but only one of them is the node lit renders this panel's body INTO: a repaint commits
+ * `nothing` there, 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. Appending to `.panel-body`
+ * instead would survive the switch — and leave the palette drawn underneath the Files tree.
+ *
+ * @param {NavigatorPanelContext} ctx
+ * @param {HTMLElement} host - The painted `.panel-body`
+ */
+export function mountElementsPanel(ctx: NavigatorPanelContext, host: HTMLElement): void {
+  panelDeps = ctx.deps;
+  const container = host.querySelector<HTMLElement>(".panel-content") ?? host;
+  if (standing && (standing.host !== container || !standing.handle.connected())) {
+    standing.handle.dispose();
+    standing = null;
+  }
+  if (!standing) {
+    standing = {
+      handle: mountElementsSurface(container, panelValues(ctx.deps), ACTIONS),
+      host: container,
+    };
+  }
+  refresh();
 }
 
 /**
@@ -220,17 +281,13 @@ export function registerInsertPanel(): void {
     title: "Insert",
     level: "document",
     dock: "navigator",
-    icon: "sp-icon-view-grid",
+    icon: "grid-four",
     rail: false,
-    render: (ctx) =>
-      renderElementsTemplate({
-        defaultDef: ctx.deps.defaultDef,
-        rerender: ctx.rerender,
-        webdata: ctx.deps.webdata,
-      } as Parameters<typeof renderElementsTemplate>[0]),
-    afterRender: (ctx) => {
-      ctx.deps.registerElementsDnD();
-      ctx.deps.registerComponentsDnD();
+    // The body is a document, so lit draws nothing and the mount happens against the painted DOM.
+    // `afterRender` runs on every repaint; {@link mountElementsPanel} is idempotent.
+    render: (): PanelBody => nothing,
+    afterRender: (ctx, host) => {
+      mountElementsPanel(ctx, host);
     },
   });
 }

package/src/panels/empty-state.ts

@@ -2,8 +2,9 @@
 /**
  * The one empty-state pattern.
  *
- * Every region in the shell that can be empty renders through {@link renderEmptyState} instead of
- * hand-writing its own block, so the copy rules below are inherited rather than re-decided:
+ * Every region in the shell that can be empty says its piece through {@link EmptyStateSpec} — drawn
+ * by `surfaces/empty-state.json`, or by a converted panel's own `[part="empty"]` block — instead of
+ * hand-writing one, so the copy rules below are inherited rather than re-decided:
  *
  * 1. **One sentence saying what the region is _for_.** Not what is absent — "No state defined" is a
  *    dead end, "Data this page can read, compute or fetch lives here" tells you what it is.
@@ -17,16 +18,19 @@
  * container.
  */
 
-import { html, nothing } from "lit-html";
-import { classMap } from "lit-html/directives/class-map.js";
-import type { TemplateResult } from "lit-html";
-
-/** A button offered by an empty state. */
+/**
+ * A button offered by an empty state.
+ *
+ * There is no `icon` here any more, and its absence is the point rather than an omission: it was
+ * typed `TemplateResult` and every value passed to it was an `sp-icon-*`, which is a Spectrum
+ * element smuggled through a shared vocabulary into surfaces that have no other Spectrum in them.
+ * `panels/git-panel.ts` was the last caller and it is a document now, so the field went with it —
+ * `surfaces/empty-state.json` draws a word, and a region that needs a glyph beside one is asking
+ * for a control the kit declares rather than for a hole in this type.
+ */
 export interface EmptyStateAction {
   /** Imperative naming what happens — "Add a value", not "Go to the Data panel". */
   label: string;
-  /** Optional Spectrum icon. Must carry `slot="icon"`. */
-  icon?: TemplateResult;
   run: () => void;
   disabled?: boolean;
 }
@@ -77,36 +81,16 @@ export function openPageAction(label = "Open a page…"): EmptyStateAction {
   };
 }
 
-/** Render an empty state. */
-export function renderEmptyState(spec: EmptyStateSpec): TemplateResult {
-  const actions = spec.actions ?? [];
-  return html`
-    <div
-      class=${classMap({
-        "empty-state": true,
-        "empty-state--compact": Boolean(spec.compact),
-        "empty-state--teach": true,
-      })}
-    >
-      <p class="empty-state-message">${spec.message}</p>
-      ${spec.detail ? html`<p class="empty-state-detail">${spec.detail}</p>` : nothing}
-      ${
-        actions.length > 0
-          ? html`<div class="empty-state-actions">
-              ${actions.map(
-                (action) => html`
-                  <sp-action-button
-                    size="s"
-                    class="empty-state-action"
-                    ?disabled=${Boolean(action.disabled)}
-                    @click=${() => action.run()}
-                    >${action.icon ?? nothing}${action.label}</sp-action-button
-                  >
-                `,
-              )}
-            </div>`
-          : nothing
-      }
-    </div>
-  `;
-}
+/*
+ * `renderEmptyState` was here, and it is GONE rather than kept beside the document.
+ *
+ * It drew the pattern as a lit template over an `sp-action-button`, and by the end of this batch it
+ * had no caller: the Navigator's bodies, the Bottom dock and a derived stage hand their box to
+ * `surfaces/empty-state.ts`'s `emptyState()`, the nine panels that are documents draw a
+ * `[part="empty"]` of their own, and `ui/expression-editor.ts` — the last lit caller — converted
+ * alongside them.
+ *
+ * What is left here is the half that was never about drawing: {@link EmptyStateSpec}, which the
+ * document reads verbatim, and the copy rules at the top of this file, which are the reason a
+ * region says what it is FOR rather than what is absent. One vocabulary, one renderer.
+ */