streetui 1.6.1 → 1.8.0

package/dist/index.cjs

@@ -70,8 +70,10 @@ __export(src_exports, {
   buttonUpdate: () => buttonUpdate,
   compile: () => compile,
   compileGraph: () => compileGraph,
+  component: () => component,
   consoleDiagnosticSink: () => consoleDiagnosticSink,
   consoleHydrationDiagnosticSink: () => consoleHydrationDiagnosticSink,
+  containFocus: () => containFocus,
   createApplication: () => createApplication,
   createBrowserHistory: () => createBrowserHistory,
   createContext: () => createContext,
@@ -98,17 +100,20 @@ __export(src_exports, {
   flushSync: () => flushSync,
   focusById: () => focusById,
   focusFirst: () => focusFirst,
+  focusInitial: () => focusInitial,
   formatDiagnostic: () => formatDiagnostic,
   formatDiagnosticContext: () => formatDiagnosticContext,
   formatHydrationDiagnostic: () => formatHydrationDiagnostic,
   frameworkError: () => frameworkError,
   generateApplicationId: () => generateApplicationId,
   generateNodeId: () => generateNodeId,
+  getFocusable: () => getFocusable,
   globalEventBus: () => globalEventBus,
   headingUpdate: () => headingUpdate,
   hydrateGraph: () => hydrateGraph,
   inputUpdate: () => inputUpdate,
   inspectApplication: () => inspectApplication,
+  inspectComponents: () => inspectComponents,
   inspectContext: () => inspectContext,
   inspectForm: () => inspectForm,
   inspectGraph: () => inspectGraph,
@@ -118,6 +123,7 @@ __export(src_exports, {
   inspectSignal: () => inspectSignal,
   interpolate: () => interpolate,
   isBatching: () => isBatching,
+  isComponentDefinition: () => isComponentDefinition,
   matchPattern: () => matchPattern,
   matchRoutes: () => matchRoutes,
   maxLength: () => maxLength,
@@ -130,6 +136,7 @@ __export(src_exports, {
   nodeTypeStats: () => nodeTypeStats,
   normalizePath: () => normalizePath,
   observerCount: () => observerCount,
+  onEscape: () => onEscape,
   patchNode: () => patchNode,
   patchProp: () => patchProp,
   pattern: () => pattern,
@@ -146,8 +153,10 @@ __export(src_exports, {
   resetIdCounter: () => resetIdCounter,
   resolveTag: () => resolveTag,
   resource: () => resource,
+  restoreFocus: () => restoreFocus,
   routerOutlet: () => routerOutlet,
   runValidators: () => runValidators,
+  saveFocus: () => saveFocus,
   scheduleImmediate: () => scheduleImmediate,
   scheduleUpdate: () => scheduleUpdate,
   scheduler: () => scheduler,
@@ -162,15 +171,18 @@ __export(src_exports, {
   textUpdate: () => textUpdate,
   toIdToken: () => toIdToken,
   transformGraph: () => transformGraph,
+  trapFocus: () => trapFocus,
   validateGraph: () => validateGraph,
+  wireComponentBehavior: () => wireComponentBehavior,
   wireEvents: () => wireEvents,
+  wireOverlayBehavior: () => wireOverlayBehavior,
   wireReactiveList: () => wireReactiveList,
   wireSignalBindings: () => wireSignalBindings
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/version.ts
-var VERSION = "1.6.0";
+var VERSION = "1.8.0";
 
 // ../state/src/signal.ts
 var _activeConsumer = null;
@@ -973,6 +985,8 @@ var ApplicationGraph = class {
     }
     this.handlers.delete(`__listbuild__${node.id}`);
     this.handlers.delete(`__listplan__${node.id}`);
+    this.handlers.delete(`__overlay__${node.id}`);
+    this.handlers.delete(`__component__${node.id}`);
   }
   // ── Handler registry ──────────────────────────────────────────────────────
   registerHandler(key, fn) {
@@ -1087,6 +1101,7 @@ function applyA11yProps(props, options) {
   if (options.ariaCurrent !== void 0) props["aria-current"] = String(options.ariaCurrent);
   if (options.ariaInvalid !== void 0) props["aria-invalid"] = String(options.ariaInvalid);
   if (options.ariaRequired !== void 0) props["aria-required"] = String(options.ariaRequired);
+  if (options.ariaModal !== void 0) props["aria-modal"] = String(options.ariaModal);
 }
 function containerProps(options) {
   const props = {};
@@ -1118,6 +1133,49 @@ function reactiveListItemSignature(item) {
 function reactiveListItemKey(item, index) {
   return itemIdentity(item, index);
 }
+var OVERLAY_KINDS = {
+  dialog: {
+    role: "dialog",
+    modal: true,
+    takesFocus: true,
+    ariaModal: true,
+    defaultCloseOnEscape: true,
+    defaultRestoreFocus: true
+  },
+  popover: {
+    role: "dialog",
+    modal: false,
+    takesFocus: true,
+    ariaModal: false,
+    defaultCloseOnEscape: true,
+    defaultRestoreFocus: true
+  },
+  tooltip: {
+    role: "tooltip",
+    modal: false,
+    takesFocus: false,
+    ariaModal: false,
+    defaultCloseOnEscape: false,
+    defaultRestoreFocus: false
+  },
+  dropdown: {
+    role: "menu",
+    modal: false,
+    takesFocus: true,
+    ariaModal: false,
+    defaultCloseOnEscape: true,
+    defaultRestoreFocus: true
+  },
+  toast: {
+    role: "status",
+    modal: false,
+    takesFocus: false,
+    ariaModal: false,
+    ariaLive: "polite",
+    defaultCloseOnEscape: false,
+    defaultRestoreFocus: false
+  }
+};
 var ContentBuilderBase = class {
   constructor(_node, _graph) {
     this._node = _node;
@@ -1390,6 +1448,131 @@ var ContainerBuilderBase = class extends ContentBuilderBase {
       );
     }, { id });
   }
+  // ── Portals & overlays ──────────────────────────────────────────────────────
+  portal(key, builder, options = {}) {
+    const node = this._graph.createNode("portal", {
+      key,
+      parent: this._node,
+      props: containerProps(options)
+    });
+    builder(new ContainerBuilderImpl(node, this._graph));
+  }
+  /**
+   * Shared assembly for every overlay kind: a `portal` node whose single child
+   * is a `when(open, panel)` conditional. The panel container carries the
+   * kind's ARIA semantics; `builder` fills it. An `__overlay__<portalId>`
+   * descriptor is registered so the renderer wires focus/keyboard behavior to
+   * the same `open` signal that drives the panel. Reuses existing primitives
+   * (portal + when + container) — no new render path.
+   */
+  _overlay(kind, key, options, builder) {
+    const graph = this._graph;
+    const portalNode = graph.createNode("portal", {
+      key,
+      parent: this._node,
+      props: { key }
+    });
+    const openBindable = options.open;
+    const openSignal = isSignal(openBindable) ? openBindable : signal(openBindable);
+    const panelOptions = {
+      role: options.role ?? kind.role,
+      ...kind.ariaModal ? { ariaModal: true } : {},
+      ...kind.ariaLive !== void 0 ? { ariaLive: kind.ariaLive } : {},
+      ...options.class !== void 0 ? { class: options.class } : {},
+      ...options.ariaLabel !== void 0 ? { ariaLabel: options.ariaLabel } : {},
+      ...options.ariaLabelledBy !== void 0 ? { ariaLabelledBy: options.ariaLabelledBy } : {},
+      ...options.ariaDescribedBy !== void 0 ? { ariaDescribedBy: options.ariaDescribedBy } : {}
+    };
+    const portalBuilder = new ContainerBuilderImpl(portalNode, graph);
+    portalBuilder.when(openSignal, (panelHost) => {
+      panelHost.container(`${key}__panel`, builder, panelOptions);
+    });
+    const descriptor = {
+      open: openSignal,
+      modal: kind.modal,
+      takesFocus: kind.takesFocus,
+      closeOnEscape: options.closeOnEscape ?? kind.defaultCloseOnEscape,
+      restoreFocus: options.restoreFocus ?? kind.defaultRestoreFocus,
+      ...options.initialFocusId !== void 0 ? { initialFocusId: options.initialFocusId } : {},
+      ...options.onClose !== void 0 ? { onClose: options.onClose } : {}
+    };
+    graph.registerHandler(
+      `__overlay__${portalNode.id}`,
+      () => descriptor
+    );
+  }
+  dialog(key, options, builder) {
+    this._overlay(OVERLAY_KINDS.dialog, key, options, builder);
+  }
+  popover(key, options, builder) {
+    this._overlay(OVERLAY_KINDS.popover, key, options, builder);
+  }
+  tooltip(key, options, builder) {
+    this._overlay(OVERLAY_KINDS.tooltip, key, options, builder);
+  }
+  dropdown(key, options, builder) {
+    this._overlay(OVERLAY_KINDS.dropdown, key, options, builder);
+  }
+  toast(key, options, builder) {
+    this._overlay(OVERLAY_KINDS.toast, key, options, builder);
+  }
+  // ── Components ────────────────────────────────────────────────────────────
+  /**
+   * Instantiate a reusable component (§3–§9). Creates a `'component'` node
+   * (rendered as a `<div>` wrapper — preserves the one-node/one-element
+   * positional-hydration invariant), then runs `def.setup(props, ctx)`
+   * synchronously to obtain the render function and fills the component's own
+   * container scope with it — structurally identical to `container`/
+   * `errorBoundary`. Cleanups the setup registers via `ctx.effect`/
+   * `ctx.onCleanup` are collected into a closure and exposed to the renderer
+   * through a `__component__<id>` handler (mirroring `__overlay__`); the mount/
+   * hydrate paths read it and route each into `NodeInstance.trackCleanup`, so
+   * teardown runs (children-first) when the component leaves the graph.
+   *
+   * `setup` runs once per instance here at build time. When this component sits
+   * inside a keyed list / conditional, a rebuild disposes the old instance
+   * (running its cleanups + pruning its `__component__` entry) and re-runs this
+   * method for the new node — so re-invocation is safe and leak-free.
+   */
+  component(key, def, props, children) {
+    const graph = this._graph;
+    const node = graph.createNode("component", {
+      key,
+      parent: this._node,
+      // `data-streetui-component` is a non-underscore prop, so it reaches the
+      // DOM as an attribute and is visible to DevTools (§21) — unlike the
+      // internal `_`-prefixed metadata the renderer hides.
+      props: { key, "data-streetui-component": def.name }
+    });
+    const cleanups = [];
+    const ctx = {
+      key,
+      onCleanup(fn) {
+        cleanups.push(fn);
+      },
+      effect(fn) {
+        cleanups.push(effect(fn));
+      },
+      renderChildren(content) {
+        if (children !== void 0) children(content);
+      }
+    };
+    let render;
+    try {
+      render = def.setup(props, ctx);
+      render(new ContainerBuilderImpl(node, graph));
+    } catch (err) {
+      queueMicrotask(() => {
+        throw err;
+      });
+    }
+    if (cleanups.length > 0) {
+      graph.registerHandler(
+        `__component__${node.id}`,
+        () => cleanups
+      );
+    }
+  }
 };
 var SectionBuilderImpl = class extends ContainerBuilderBase {
 };
@@ -1423,6 +1606,18 @@ var AppBuilder = class {
   }
 };
 
+// ../dsl/src/component.ts
+function component(setup, options = {}) {
+  return {
+    __streetui_component: true,
+    name: options.name ?? setup.name ?? "Component",
+    setup
+  };
+}
+function isComponentDefinition(value) {
+  return value !== null && typeof value === "object" && value.__streetui_component === true;
+}
+
 // ../dsl/src/dsl.ts
 var StreetApp = class {
   _graph;
@@ -1990,6 +2185,18 @@ var BrowserDOMAdapter = class {
   focus(element) {
     element.focus?.();
   }
+  body() {
+    return document.body ?? null;
+  }
+  activeElement() {
+    return document.activeElement ?? null;
+  }
+  contains(ancestor, node) {
+    return ancestor.contains(node);
+  }
+  matches(element, selector) {
+    return typeof element.matches === "function" && element.matches(selector);
+  }
   isElement(node) {
     return node.nodeType === Node.ELEMENT_NODE;
   }
@@ -2357,6 +2564,18 @@ var ServerDOMAdapter = class {
   }
   focus() {
   }
+  body() {
+    return null;
+  }
+  activeElement() {
+    return null;
+  }
+  contains(_ancestor, _node) {
+    return false;
+  }
+  matches(_element, _selector) {
+    return false;
+  }
   isElement(node) {
     return asServer(node).kind === "element";
   }
@@ -2422,6 +2641,66 @@ function focusFirst(dom, container, selector = FOCUSABLE_SELECTOR) {
   dom.focus(el);
   return true;
 }
+function getFocusable(dom, container, selector = FOCUSABLE_SELECTOR) {
+  return Array.from(dom.querySelectorAll(container, selector)).filter(
+    (el) => dom.matches(el, selector)
+  );
+}
+function saveFocus(dom) {
+  return dom.activeElement();
+}
+function restoreFocus(dom, saved) {
+  if (saved !== null) dom.focus(saved);
+}
+function focusInitial(dom, container, initialFocusId) {
+  if (initialFocusId !== void 0 && focusById(dom, container, initialFocusId)) return;
+  focusFirst(dom, container);
+}
+function trapFocus(dom, container) {
+  const onKeydown = (event) => {
+    if (event.key !== "Tab") return;
+    const items = getFocusable(dom, container);
+    if (items.length === 0) {
+      event.preventDefault();
+      return;
+    }
+    const first = items[0];
+    const last = items[items.length - 1];
+    const active = dom.activeElement();
+    if (active === null || !dom.contains(container, active)) {
+      event.preventDefault();
+      dom.focus(first);
+    } else if (event.shiftKey && active === first) {
+      event.preventDefault();
+      dom.focus(last);
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      dom.focus(first);
+    }
+  };
+  dom.addEventListener(container, "keydown", onKeydown);
+  return () => dom.removeEventListener(container, "keydown", onKeydown);
+}
+function containFocus(dom, container) {
+  const body = dom.body();
+  if (body === null) return () => {
+  };
+  const onFocusIn = (event) => {
+    const target = event.target;
+    if (target !== null && !dom.contains(container, target)) {
+      focusFirst(dom, container);
+    }
+  };
+  dom.addEventListener(body, "focusin", onFocusIn);
+  return () => dom.removeEventListener(body, "focusin", onFocusIn);
+}
+function onEscape(dom, target, handler) {
+  const onKeydown = (event) => {
+    if (event.key === "Escape") handler();
+  };
+  dom.addEventListener(target, "keydown", onKeydown);
+  return () => dom.removeEventListener(target, "keydown", onKeydown);
+}
 
 // ../renderer/src/render-context.ts
 function createRenderContext(dom, graph, container, hydrationDiagnostics, staticHTML) {
@@ -2580,7 +2859,12 @@ var TAG_MAP = {
   component: "div",
   slot: "div",
   fragment: "div",
-  "reactive-list": "ul"
+  "reactive-list": "ul",
+  // A portal renders as a neutral inline anchor <div> at its declaration site;
+  // its children are relocated to a document.body container on the browser
+  // (see the portal branch in mount.ts). On the server (no body) it renders
+  // inline, so the anchor tag is what SSR/hydration positionally match on.
+  portal: "div"
 };
 function resolveTag(type) {
   return TAG_MAP[type] ?? "div";
@@ -2992,6 +3276,28 @@ function mountNode(ctx, graphNode, parentDom) {
     wireReactiveList(ctx, graphNode, instance2, el2);
     return instance2;
   }
+  if (graphNode.type === "portal") {
+    const anchor = dom.createElement(resolveTag("portal"));
+    dom.setAttribute(anchor, "data-streetui-portal", "");
+    applyNodeProps(ctx, graphNode, anchor);
+    const instance2 = new NodeInstance(graphNode, anchor);
+    ctx.instances.set(graphNode.id, instance2);
+    const body = dom.body();
+    let target = anchor;
+    if (body !== null) {
+      const portalContainer = dom.createElement("div");
+      dom.setAttribute(portalContainer, "data-streetui-portal-container", "");
+      dom.appendChild(body, portalContainer);
+      instance2.trackCleanup(() => dom.removeChild(body, portalContainer));
+      target = portalContainer;
+    }
+    for (const child of graphNode.children) {
+      instance2.addChild(mountNode(ctx, child, target));
+    }
+    dom.appendChild(parentDom, anchor);
+    wireOverlayBehavior(ctx, graphNode, instance2, target);
+    return instance2;
+  }
   const tag = resolveTag(graphNode.type);
   const el = dom.createElement(tag);
   applyNodeProps(ctx, graphNode, el);
@@ -3011,6 +3317,7 @@ function mountNode(ctx, graphNode, parentDom) {
     instance.addChild(childInstance);
   }
   dom.appendChild(parentDom, el);
+  if (graphNode.type === "component") wireComponentBehavior(ctx, graphNode, instance);
   return instance;
 }
 function textUpdate(dom, el, textNode) {
@@ -3141,6 +3448,49 @@ function forgetInstance(ctx, instance) {
   ctx.instances.delete(instance.graphNode.id);
   for (const child of instance.children) forgetInstance(ctx, child);
 }
+function wireOverlayBehavior(ctx, graphNode, instance, target) {
+  const { dom, graph } = ctx;
+  if (dom.body() === null) return;
+  const descFn = graph.getHandler(`__overlay__${graphNode.id}`);
+  if (descFn === void 0) return;
+  const desc = descFn();
+  const openSig = desc.open;
+  if (openSig === void 0 || typeof openSig.subscribe !== "function") return;
+  let active = [];
+  let saved = null;
+  const teardown = () => {
+    for (const fn of active) fn();
+    active = [];
+  };
+  const onOpenChange = (isOpen) => {
+    if (isOpen) {
+      if (desc.restoreFocus) saved = saveFocus(dom);
+      if (desc.takesFocus) focusInitial(dom, target, desc.initialFocusId);
+      if (desc.modal) {
+        active.push(trapFocus(dom, target));
+        active.push(containFocus(dom, target));
+      }
+      if (desc.closeOnEscape && desc.onClose !== void 0) {
+        active.push(onEscape(dom, target, desc.onClose));
+      }
+    } else {
+      teardown();
+      if (desc.restoreFocus && saved !== null) {
+        restoreFocus(dom, saved);
+        saved = null;
+      }
+    }
+  };
+  const unsub = openSig.subscribe(onOpenChange);
+  instance.trackCleanup(unsub);
+  instance.trackCleanup(teardown);
+  if (openSig.peek() === true) onOpenChange(true);
+}
+function wireComponentBehavior(ctx, graphNode, instance) {
+  const fn = ctx.graph.getHandler(`__component__${graphNode.id}`);
+  if (fn === void 0) return;
+  for (const cleanup of fn()) instance.trackCleanup(cleanup);
+}
 
 // ../renderer/src/hydration-diagnostics.ts
 function formatHydrationDiagnostic(d) {
@@ -3243,6 +3593,25 @@ function hydrateNode(ctx, graphNode, domNode, path) {
       wireReactiveList(ctx, graphNode, instance, domNode);
       return instance;
     }
+    case "portal": {
+      const instance = new NodeInstance(graphNode, domNode);
+      ctx.instances.set(graphNode.id, instance);
+      const body = dom.body();
+      let target = domNode;
+      if (body !== null) {
+        const portalContainer = dom.createElement("div");
+        dom.setAttribute(portalContainer, "data-streetui-portal-container", "");
+        for (const child of dom.childNodes(domNode)) {
+          dom.appendChild(portalContainer, child);
+        }
+        dom.appendChild(body, portalContainer);
+        instance.trackCleanup(() => dom.removeChild(body, portalContainer));
+        target = portalContainer;
+      }
+      hydrateChildren(ctx, graphNode, instance, target, path);
+      wireOverlayBehavior(ctx, graphNode, instance, target);
+      return instance;
+    }
     default: {
       const instance = new NodeInstance(graphNode, domNode);
       ctx.instances.set(graphNode.id, instance);
@@ -3253,6 +3622,7 @@ function hydrateNode(ctx, graphNode, domNode, path) {
         return instance;
       }
       hydrateChildren(ctx, graphNode, instance, domNode, path);
+      if (graphNode.type === "component") wireComponentBehavior(ctx, graphNode, instance);
       return instance;
     }
   }
@@ -3486,7 +3856,9 @@ function analyzeGraph(graph) {
     const hasEvents = node.events.length > 0;
     const isList = node.type === "reactive-list";
     const isConditional = node.type === "conditional";
-    const isStatic = node.stateRefs.length === 0 && !hasEvents && !isList && !isConditional;
+    const isPortal = node.type === "portal";
+    const isComponent = node.type === "component";
+    const isStatic = node.stateRefs.length === 0 && !hasEvents && !isList && !isConditional && !isPortal && !isComponent;
     const isStaticSubtree = isStatic && allChildrenStatic;
     nodes.set(node.id, {
       isStatic,
@@ -4193,6 +4565,21 @@ function nodeTypeStats(graph) {
   });
   return counts;
 }
+function inspectComponents(graph) {
+  const out = [];
+  graph.walk((node, depth) => {
+    if (node.type !== "component") return;
+    const name = node.props["data-streetui-component"];
+    out.push({
+      id: node.id,
+      key: node.key,
+      name: typeof name === "string" ? name : "Component",
+      depth,
+      childCount: node.children.length
+    });
+  });
+  return out;
+}
 
 // ../devtools/src/application.ts
 function collectPerf(node, distinctSignals, acc) {
@@ -4577,8 +4964,10 @@ function defineConfig(config) {
   buttonUpdate,
   compile,
   compileGraph,
+  component,
   consoleDiagnosticSink,
   consoleHydrationDiagnosticSink,
+  containFocus,
   createApplication,
   createBrowserHistory,
   createContext,
@@ -4605,17 +4994,20 @@ function defineConfig(config) {
   flushSync,
   focusById,
   focusFirst,
+  focusInitial,
   formatDiagnostic,
   formatDiagnosticContext,
   formatHydrationDiagnostic,
   frameworkError,
   generateApplicationId,
   generateNodeId,
+  getFocusable,
   globalEventBus,
   headingUpdate,
   hydrateGraph,
   inputUpdate,
   inspectApplication,
+  inspectComponents,
   inspectContext,
   inspectForm,
   inspectGraph,
@@ -4625,6 +5017,7 @@ function defineConfig(config) {
   inspectSignal,
   interpolate,
   isBatching,
+  isComponentDefinition,
   matchPattern,
   matchRoutes,
   maxLength,
@@ -4637,6 +5030,7 @@ function defineConfig(config) {
   nodeTypeStats,
   normalizePath,
   observerCount,
+  onEscape,
   patchNode,
   patchProp,
   pattern,
@@ -4653,8 +5047,10 @@ function defineConfig(config) {
   resetIdCounter,
   resolveTag,
   resource,
+  restoreFocus,
   routerOutlet,
   runValidators,
+  saveFocus,
   scheduleImmediate,
   scheduleUpdate,
   scheduler,
@@ -4669,8 +5065,11 @@ function defineConfig(config) {
   textUpdate,
   toIdToken,
   transformGraph,
+  trapFocus,
   validateGraph,
+  wireComponentBehavior,
   wireEvents,
+  wireOverlayBehavior,
   wireReactiveList,
   wireSignalBindings
 });