@cosxai/ui 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "COSX design system \u2014 React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",

package/src/actionbar/ActionBar.tsx

@@ -155,7 +155,7 @@ export function ActionBar({
   if (!ctx) {
     throw new Error("<ActionBar> must be inside <ActionBarProvider>");
   }
-  const { items, categories, expandedKey, setExpandedKey, statusDot, panel, toast } = ctx;
+  const { items, categories, expandedKey, setExpandedKey, statusDot, panel, setPanelHost, toastActive, setToastHost } = ctx;
   const vp = useViewport();
   const isPhone = vp.isPhone;
 
@@ -332,6 +332,61 @@ export function ActionBar({
     return () => window.removeEventListener("keydown", onKey);
   }, [expandedKey, setExpandedKey]);
 
+  // ----- Panel slot (design#13): outside-click + Escape close. -----
+  // Hooks live ABOVE the early returns below — hook order must not
+  // change when the bar switches between empty/collapsed/full.
+  const panelOpen = Boolean(panel?.open);
+  const panelClose = panel?.onOpenChange;
+  useEffect(() => {
+    if (!panelOpen || !panelClose) return;
+    const onDown = (e: MouseEvent) => {
+      const t = e.target as Node | null;
+      if (t && barRef.current?.contains(t)) return;
+      panelClose(false);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") panelClose(false);
+    };
+    window.addEventListener("mousedown", onDown);
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("mousedown", onDown);
+      window.removeEventListener("keydown", onKey);
+    };
+  }, [panelOpen, panelClose]);
+
+  // Host refs — stable callbacks publishing the container DOM nodes
+  // through context so the consumer hooks can portal content in.
+  // useCallback keeps React from detach/re-attach churn per render.
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  const panelHostRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      panelRef.current = el;
+      setPanelHost(el);
+    },
+    [setPanelHost],
+  );
+  const toastHostRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      setToastHost(el);
+    },
+    [setToastHost],
+  );
+
+  // Horizontal clamp: centred on the bar unless that would push the
+  // panel past a viewport edge — then shift just enough to fit.
+  useLayoutEffect(() => {
+    if (!panelOpen) return;
+    const el = panelRef.current;
+    if (!el) return;
+    el.style.marginLeft = "0px";
+    const rect = el.getBoundingClientRect();
+    let shift = 0;
+    if (rect.left < 8) shift = 8 - rect.left;
+    else if (rect.right > window.innerWidth - 8) shift = window.innerWidth - 8 - rect.right;
+    if (shift !== 0) el.style.marginLeft = `${Math.round(shift)}px`;
+  }, [panelOpen, pos]);
+
   // ----- Empty state -----
   // Bar renders when EITHER any page item is registered OR the
   // status dot is set. Without the statusDot check, an app whose
@@ -383,42 +438,6 @@ export function ActionBar({
     );
   }
 
-  // ----- Panel slot (design#13): outside-click + Escape close. -----
-  const panelOpen = Boolean(panel?.open);
-  const panelClose = panel?.onOpenChange;
-  useEffect(() => {
-    if (!panelOpen || !panelClose) return;
-    const onDown = (e: MouseEvent) => {
-      const t = e.target as Node | null;
-      if (t && barRef.current?.contains(t)) return;
-      panelClose(false);
-    };
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") panelClose(false);
-    };
-    window.addEventListener("mousedown", onDown);
-    window.addEventListener("keydown", onKey);
-    return () => {
-      window.removeEventListener("mousedown", onDown);
-      window.removeEventListener("keydown", onKey);
-    };
-  }, [panelOpen, panelClose]);
-
-  // Horizontal clamp: centred on the bar unless that would push the
-  // panel past a viewport edge — then shift just enough to fit.
-  const panelRef = useRef<HTMLDivElement | null>(null);
-  useLayoutEffect(() => {
-    if (!panelOpen) return;
-    const el = panelRef.current;
-    if (!el) return;
-    el.style.marginLeft = "0px";
-    const rect = el.getBoundingClientRect();
-    let shift = 0;
-    if (rect.left < 8) shift = 8 - rect.left;
-    else if (rect.right > window.innerWidth - 8) shift = window.innerWidth - 8 - rect.right;
-    if (shift !== 0) el.style.marginLeft = `${Math.round(shift)}px`;
-  }, [panelOpen, pos]);
-
   // ----- Full bar -----
   const isDefault = pos.type === "default";
   return (
@@ -476,11 +495,13 @@ export function ActionBar({
     >
       {/* Panel slot (design#13) — the bar positions + the chrome
           themes style it (.ck-actionbar-panel); consumers own only
-          the content. Rendered inside the bar root so it follows
+          the content, PORTALLED in via useActionBarPanel (the div
+          here is an empty host — content never flows through
+          context state). Rendered inside the bar root so it follows
           drags natively. */}
       {panel?.open && (
         <div
-          ref={panelRef}
+          ref={panelHostRef}
           className="ck-actionbar-panel"
           role="region"
           aria-label={panel.ariaLabel ?? "Panel"}
@@ -493,12 +514,11 @@ export function ActionBar({
             maxWidth: "calc(100vw - 16px)",
             cursor: "default",
           }}
-        >
-          {panel.content}
-        </div>
+        />
       )}
-      {toast != null && !panel?.open && (
+      {toastActive && !panel?.open && (
         <div
+          ref={toastHostRef}
           className="ck-actionbar-toast"
           role="status"
           style={{
@@ -508,9 +528,7 @@ export function ActionBar({
             transform: "translateX(-50%)",
             whiteSpace: "nowrap",
           }}
-        >
-          {toast}
-        </div>
+        />
       )}
       {/* Left-edge button. Phone = collapse; desktop = drag grip. */}
       {isPhone && collapsibleOnPhone ? (

package/src/actionbar/ActionBarProvider.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { ActionBarContext } from "./actionbar-context";
-import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanel } from "./types";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanelMeta } from "./types";
 
 // Provider for the action-bar registry + expansion state +
 // category catalog. Mount once near the app root, inside the
@@ -24,8 +24,10 @@ export function ActionBarProvider({
   const [sources, setSources] = useState<Record<string, ActionBarItem[]>>({});
   const [expandedKey, setExpandedKey] = useState<string | null>(null);
   const [statusDot, setStatusDot] = useState<ActionBarStatusDot | null>(null);
-  const [panel, setPanel] = useState<ActionBarPanel | null>(null);
-  const [toast, setToast] = useState<ReactNode | null>(null);
+  const [panel, setPanel] = useState<ActionBarPanelMeta | null>(null);
+  const [panelHost, setPanelHost] = useState<HTMLDivElement | null>(null);
+  const [toastActive, setToastActive] = useState(false);
+  const [toastHost, setToastHost] = useState<HTMLDivElement | null>(null);
 
   const register = useCallback((sourceKey: string, items: ActionBarItem[]) => {
     setSources((prev) => {
@@ -71,10 +73,14 @@ export function ActionBarProvider({
       setStatusDot,
       panel,
       setPanel,
-      toast,
-      setToast,
+      panelHost,
+      setPanelHost,
+      toastActive,
+      setToastActive,
+      toastHost,
+      setToastHost,
     }),
-    [register, unregister, items, categories, expandedKey, statusDot, panel, toast],
+    [register, unregister, items, categories, expandedKey, statusDot, panel, panelHost, toastActive, toastHost],
   );
 
   return (

package/src/actionbar/actionbar-context.ts

@@ -1,6 +1,5 @@
 import { createContext } from "react";
-import type { ReactNode } from "react";
-import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanel } from "./types";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanelMeta } from "./types";
 
 // Registry + expansion + category catalog + status-dot slot. Items are
 // pushed by pages through useActionBarItems(); the status dot is
@@ -24,13 +23,23 @@ export interface ActionBarContextValue {
   // has registered one. Last call to setStatusDot wins.
   statusDot: ActionBarStatusDot | null;
   setStatusDot: (dot: ActionBarStatusDot | null) => void;
-  // Bar-intrinsic popover slot (design#13). Registered by
-  // useActionBarPanel; the bar positions + themes it.
-  panel: ActionBarPanel | null;
-  setPanel: (panel: ActionBarPanel | null) => void;
-  // Transient bubble above the bar (completion toasts etc.).
-  toast: ReactNode | null;
-  setToast: (toast: ReactNode | null) => void;
+  // Bar-intrinsic popover slot (design#13). useActionBarPanel
+  // registers META only (open/onOpenChange/width/ariaLabel); the bar
+  // renders an empty themed container and publishes its DOM node via
+  // panelHost, into which the hook PORTALS the consumer's content.
+  // Content never enters context state — a fresh JSX identity per
+  // consumer render would otherwise re-render-loop through setPanel.
+  panel: ActionBarPanelMeta | null;
+  setPanel: (panel: ActionBarPanelMeta | null) => void;
+  panelHost: HTMLDivElement | null;
+  setPanelHost: (el: HTMLDivElement | null) => void;
+  // Transient bubble above the bar (completion toasts etc.) — same
+  // portal-host pattern: consumers register only "active", content
+  // portals into toastHost.
+  toastActive: boolean;
+  setToastActive: (active: boolean) => void;
+  toastHost: HTMLDivElement | null;
+  setToastHost: (el: HTMLDivElement | null) => void;
 }
 
 export const ActionBarContext = createContext<ActionBarContextValue | null>(null);

package/src/actionbar/index.ts

@@ -22,6 +22,7 @@ export type {
   ActionBarItemSlot,
   ActionBarStatusDot,
   ActionBarPanel,
+  ActionBarPanelMeta,
   ActionBarCategory,
   ActionBarCategories,
 } from "./types";

package/src/actionbar/types.ts

@@ -129,10 +129,19 @@ export interface ActionBarPanel {
   // own affordance (typically the status dot's onClick).
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  // Content subtree. Rendered inside the themed panel container.
+  // Content subtree. Portalled into the themed panel container the
+  // bar renders — it stays in the CONSUMER's React tree (fresh JSX
+  // identity per render is fine; content never flows through
+  // context state, which would re-render-loop).
   content: ReactNode;
   // Panel width in px. Default 320; always viewport-clamped.
   width?: number;
   // aria-label for the panel region. Default "Panel".
   ariaLabel?: string;
 }
+
+// What the context actually stores for the panel slot: the config
+// minus `content`. Only stable primitives + the onOpenChange
+// callback go through context state, so the registration effect
+// re-runs on real changes only.
+export type ActionBarPanelMeta = Omit<ActionBarPanel, "content">;

package/src/actionbar/useActionBarPanel.ts

@@ -1,6 +1,8 @@
 import { useContext, useEffect } from "react";
+import { createPortal } from "react-dom";
 import { ActionBarContext } from "./actionbar-context";
 import type { ActionBarPanel } from "./types";
+import type { ReactNode } from "react";
 
 // Push a panel config into the action bar's popover slot (design#13).
 //
@@ -12,19 +14,26 @@ import type { ActionBarPanel } from "./types";
 // own background/border/shadow. The consumer owns only the content
 // subtree and the `open` state.
 //
+// RETURNS a ReactNode the consumer MUST render (a portal into the
+// bar's panel container, or null while closed). Content stays in the
+// consumer's own React tree — a fresh JSX identity every render is
+// fine because only the meta (open/onOpenChange/width/ariaLabel)
+// flows through context state; content in state would re-render-loop
+// (setPanel → context change → consumer re-render → new JSX →
+// setPanel → …).
+//
 // The bar calls `onOpenChange(false)` on outside-click and Escape.
 // Pass `null` to clear (also cleared automatically on unmount).
 // Last call wins — one panel at a time, same contract as the status
 // dot.
-export function useActionBarPanel(config: ActionBarPanel | null) {
+export function useActionBarPanel(config: ActionBarPanel | null): ReactNode {
   const ctx = useContext(ActionBarContext);
   if (!ctx) {
     throw new Error("useActionBarPanel must be used within <ActionBarProvider>");
   }
-  const { setPanel } = ctx;
+  const { setPanel, panelHost } = ctx;
   const open = config?.open;
   const onOpenChange = config?.onOpenChange;
-  const content = config?.content;
   const width = config?.width;
   const ariaLabel = config?.ariaLabel;
   useEffect(() => {
@@ -35,12 +44,13 @@ export function useActionBarPanel(config: ActionBarPanel | null) {
     setPanel({
       open,
       onOpenChange,
-      content,
       ...(width !== undefined ? { width } : {}),
       ...(ariaLabel !== undefined ? { ariaLabel } : {}),
     });
     return () => {
       setPanel(null);
     };
-  }, [setPanel, open, onOpenChange, content, width, ariaLabel]);
+  }, [setPanel, open, onOpenChange, width, ariaLabel]);
+  if (!config?.open || panelHost === null || config.content == null) return null;
+  return createPortal(config.content, panelHost);
 }

package/src/actionbar/useActionBarToast.ts

@@ -1,23 +1,33 @@
 import { useContext, useEffect } from "react";
-import type { ReactNode } from "react";
+import { createPortal } from "react-dom";
 import { ActionBarContext } from "./actionbar-context";
+import type { ReactNode } from "react";
 
 // Push a transient bubble into the bar's toast slot — rendered above
 // the bar (following it when dragged), themed via
-// `.ck-actionbar-toast`. The CONSUMER owns the lifetime: pass the
-// node to show, `null` to hide (typically driven by a setTimeout in
-// the consumer). Pairs with useActionBarPanel for the notification-
+// `.ck-actionbar-toast`, suppressed while the panel is open. The
+// CONSUMER owns the lifetime: pass the node to show, `null` to hide
+// (typically driven by a setTimeout in the consumer).
+//
+// RETURNS a ReactNode the consumer MUST render (a portal into the
+// bar's toast container, or null while hidden). Same portal-host
+// contract as useActionBarPanel: only the boolean "active" flag goes
+// through context state, so a fresh JSX identity per render can't
+// re-render-loop. Pairs with useActionBarPanel for the notification-
 // center pattern (design#13).
-export function useActionBarToast(content: ReactNode | null) {
+export function useActionBarToast(content: ReactNode | null): ReactNode {
   const ctx = useContext(ActionBarContext);
   if (!ctx) {
     throw new Error("useActionBarToast must be used within <ActionBarProvider>");
   }
-  const { setToast } = ctx;
+  const { setToastActive, toastHost } = ctx;
+  const active = content != null;
   useEffect(() => {
-    setToast(content ?? null);
+    setToastActive(active);
     return () => {
-      setToast(null);
+      setToastActive(false);
     };
-  }, [setToast, content]);
+  }, [setToastActive, active]);
+  if (!active || toastHost === null) return null;
+  return createPortal(content, toastHost);
 }