@cosxai/ui 0.16.0 → 0.17.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.16.0",
-  "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
+  "version": "0.17.1",
+  "description": "COSX design system \u2014 React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",
   "main": "./src/index.ts",

package/src/actionbar/ActionBar.tsx

@@ -1,6 +1,7 @@
 import {
   useCallback,
   useContext,
+  useLayoutEffect,
   useEffect,
   useMemo,
   useRef,
@@ -154,7 +155,7 @@ export function ActionBar({
   if (!ctx) {
     throw new Error("<ActionBar> must be inside <ActionBarProvider>");
   }
-  const { items, categories, expandedKey, setExpandedKey, statusDot } = ctx;
+  const { items, categories, expandedKey, setExpandedKey, statusDot, panel, toast } = ctx;
   const vp = useViewport();
   const isPhone = vp.isPhone;
 
@@ -331,6 +332,44 @@ 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]);
+
+  // 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]);
+
   // ----- Empty state -----
   // Bar renders when EITHER any page item is registered OR the
   // status dot is set. Without the statusDot check, an app whose
@@ -437,6 +476,44 @@ export function ActionBar({
         ...style,
       }}
     >
+      {/* 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
+          drags natively. */}
+      {panel?.open && (
+        <div
+          ref={panelRef}
+          className="ck-actionbar-panel"
+          role="region"
+          aria-label={panel.ariaLabel ?? "Panel"}
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 8px)",
+            left: "50%",
+            transform: "translateX(-50%)",
+            width: panel.width ?? 320,
+            maxWidth: "calc(100vw - 16px)",
+            cursor: "default",
+          }}
+        >
+          {panel.content}
+        </div>
+      )}
+      {toast != null && !panel?.open && (
+        <div
+          className="ck-actionbar-toast"
+          role="status"
+          style={{
+            position: "absolute",
+            bottom: "calc(100% + 8px)",
+            left: "50%",
+            transform: "translateX(-50%)",
+            whiteSpace: "nowrap",
+          }}
+        >
+          {toast}
+        </div>
+      )}
       {/* Left-edge button. Phone = collapse; desktop = drag grip. */}
       {isPhone && collapsibleOnPhone ? (
         <button

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 } from "./types";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanel } from "./types";
 
 // Provider for the action-bar registry + expansion state +
 // category catalog. Mount once near the app root, inside the
@@ -24,6 +24,8 @@ 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 register = useCallback((sourceKey: string, items: ActionBarItem[]) => {
     setSources((prev) => {
@@ -67,8 +69,12 @@ export function ActionBarProvider({
       setExpandedKey,
       statusDot,
       setStatusDot,
+      panel,
+      setPanel,
+      toast,
+      setToast,
     }),
-    [register, unregister, items, categories, expandedKey, statusDot],
+    [register, unregister, items, categories, expandedKey, statusDot, panel, toast],
   );
 
   return (

package/src/actionbar/actionbar-context.ts

@@ -1,5 +1,6 @@
 import { createContext } from "react";
-import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot } from "./types";
+import type { ReactNode } from "react";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot, ActionBarPanel } from "./types";
 
 // Registry + expansion + category catalog + status-dot slot. Items are
 // pushed by pages through useActionBarItems(); the status dot is
@@ -23,6 +24,13 @@ 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;
 }
 
 export const ActionBarContext = createContext<ActionBarContextValue | null>(null);

package/src/actionbar/index.ts

@@ -6,6 +6,8 @@ export { ActionBarButton } from "./ActionBarButton";
 export type { ActionBarButtonProps } from "./ActionBarButton";
 export { useActionBarItems, useActionBarItemsContext } from "./useActionBarItems";
 export { useActionBarStatusDot } from "./useActionBarStatusDot";
+export { useActionBarPanel } from "./useActionBarPanel";
+export { useActionBarToast } from "./useActionBarToast";
 export { ActionBarModeHandle } from "./ActionBarModeHandle";
 export type { ActionBarModeHandleProps } from "./ActionBarModeHandle";
 export { useActionBarMode } from "./useActionBarMode";
@@ -19,6 +21,7 @@ export type {
   ActionBarItemVariant,
   ActionBarItemSlot,
   ActionBarStatusDot,
+  ActionBarPanel,
   ActionBarCategory,
   ActionBarCategories,
 } from "./types";

package/src/actionbar/types.ts

@@ -117,3 +117,22 @@ export interface ActionBarStatusDot {
   // pulsing reads as attention-grabbing.
   pulse?: boolean;
 }
+
+// Registered via `useActionBarPanel()` — the bar-intrinsic popover
+// slot (design#13). The BAR owns positioning (docked above itself,
+// following drag natively) and the chrome themes own the panel's
+// visual identity via `.ck-actionbar-panel`; the consumer owns only
+// the content subtree. One panel at a time (last call wins).
+export interface ActionBarPanel {
+  // Controlled visibility. The bar calls onOpenChange(false) on
+  // outside-click and Escape; the consumer toggles open from its
+  // own affordance (typically the status dot's onClick).
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  // Content subtree. Rendered inside the themed panel container.
+  content: ReactNode;
+  // Panel width in px. Default 320; always viewport-clamped.
+  width?: number;
+  // aria-label for the panel region. Default "Panel".
+  ariaLabel?: string;
+}

package/src/actionbar/useActionBarPanel.ts

@@ -0,0 +1,46 @@
+import { useContext, useEffect } from "react";
+import { ActionBarContext } from "./actionbar-context";
+import type { ActionBarPanel } from "./types";
+
+// Push a panel config into the action bar's popover slot (design#13).
+//
+// The BAR owns positioning: docked above itself, centered, following
+// drag natively (it renders the panel inside its own fixed-position
+// root — no polling, no rect maths in the consumer) and viewport-
+// clamped at the edges. The chrome themes own the panel's visual
+// identity via `.ck-actionbar-panel`; consumers must NOT paint their
+// own background/border/shadow. The consumer owns only the content
+// subtree and the `open` state.
+//
+// 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) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("useActionBarPanel must be used within <ActionBarProvider>");
+  }
+  const { setPanel } = ctx;
+  const open = config?.open;
+  const onOpenChange = config?.onOpenChange;
+  const content = config?.content;
+  const width = config?.width;
+  const ariaLabel = config?.ariaLabel;
+  useEffect(() => {
+    if (open === undefined || onOpenChange === undefined) {
+      setPanel(null);
+      return;
+    }
+    setPanel({
+      open,
+      onOpenChange,
+      content,
+      ...(width !== undefined ? { width } : {}),
+      ...(ariaLabel !== undefined ? { ariaLabel } : {}),
+    });
+    return () => {
+      setPanel(null);
+    };
+  }, [setPanel, open, onOpenChange, content, width, ariaLabel]);
+}

package/src/actionbar/useActionBarToast.ts

@@ -0,0 +1,23 @@
+import { useContext, useEffect } from "react";
+import type { ReactNode } from "react";
+import { ActionBarContext } from "./actionbar-context";
+
+// 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-
+// center pattern (design#13).
+export function useActionBarToast(content: ReactNode | null) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("useActionBarToast must be used within <ActionBarProvider>");
+  }
+  const { setToast } = ctx;
+  useEffect(() => {
+    setToast(content ?? null);
+    return () => {
+      setToast(null);
+    };
+  }, [setToast, content]);
+}

package/src/styles/base.css

@@ -122,3 +122,30 @@ a:visited { color: var(--ck-accent); }
 :root {
   scrollbar-color: var(--ck-border-strong, rgba(0, 0, 0, 0.25)) transparent;
 }
+
+/* ── ActionBar panel + toast slots (design#13) ─────────────────────
+   Base chrome for the bar-intrinsic popover (useActionBarPanel) and
+   transient bubble (useActionBarToast). Token-driven so every theme
+   reads correctly by default; chrome-*.css sharpens identity themes
+   (neobrutalism ink shadows, sketch wobble, terminal flatness). */
+.ck-actionbar-panel {
+  background: var(--ck-bg-surface, #fff);
+  border: 1px solid var(--ck-border-subtle, #e5e7eb);
+  border-radius: 12px;
+  box-shadow: var(--ck-shadow-3, 0 16px 48px rgba(0, 0, 0, 0.12));
+  padding: 16px;
+  font-family: var(--ck-font-sans, system-ui, sans-serif);
+  color: var(--ck-text-primary);
+  user-select: none;
+}
+.ck-actionbar-toast {
+  background: var(--ck-bg-surface, #fff);
+  border: 1px solid var(--ck-border-subtle, #e5e7eb);
+  border-radius: 10px;
+  box-shadow: var(--ck-shadow-3, 0 16px 48px rgba(0, 0, 0, 0.12));
+  padding: 10px 14px;
+  font-size: 12px;
+  font-family: var(--ck-font-sans, system-ui, sans-serif);
+  color: var(--ck-text-primary);
+  user-select: none;
+}

package/src/styles/chrome-ambient.css

@@ -223,3 +223,13 @@ html[data-ck-chrome="ambient"] [role="dialog"] > div > div {
     transition: none !important;
   }
 }
+
+html[data-ck-chrome="ambient"] .ck-actionbar-panel,
+html[data-ck-chrome="ambient"] .ck-actionbar-toast {
+  background: var(--ck-bg-sidebar);
+  backdrop-filter: var(--ck-blur-overlay);
+  -webkit-backdrop-filter: var(--ck-blur-overlay);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 20px;
+  box-shadow: var(--ck-shadow-2);
+}

package/src/styles/chrome-bento.css

@@ -182,3 +182,11 @@ html[data-ck-chrome="bento"] [data-ck-bento-cell][data-interactive="true"]:hover
   transform: translateY(-3px);
   box-shadow: var(--ck-shadow-3);
 }
+
+html[data-ck-chrome="bento"] .ck-actionbar-panel,
+html[data-ck-chrome="bento"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 16px;
+  box-shadow: var(--ck-shadow-2);
+}

package/src/styles/chrome-editorial.css

@@ -158,3 +158,11 @@ html[data-ck-chrome="editorial"] [role="dialog"] > div:first-child {
 [data-ck-spotlight] .ck-card .ck-tag {
   color: var(--ck-text-secondary);
 }
+
+/* ActionBar panel/toast — flat paper, hairline, no drop glow. */
+html[data-ck-chrome="editorial"] .ck-actionbar-panel,
+html[data-ck-chrome="editorial"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border-color: var(--ck-border-subtle);
+  box-shadow: var(--ck-shadow-1, 0 2px 8px rgba(0, 0, 0, 0.06));
+}

package/src/styles/chrome-neobrutalism.css

@@ -316,3 +316,11 @@ html[data-ck-chrome="neobrutalism"] [role="switch"] {
     box-shadow: 4px 4px 0 0 var(--neobrut-ink);
   }
 }
+
+html[data-ck-chrome="neobrutalism"] .ck-actionbar-panel,
+html[data-ck-chrome="neobrutalism"] .ck-actionbar-toast {
+  border: 2px solid var(--neobrut-ink);
+  border-radius: 5px;
+  box-shadow: 4px 4px 0 0 var(--neobrut-ink);
+  background: var(--ck-bg-surface);
+}

package/src/styles/chrome-riso.css

@@ -329,3 +329,11 @@ html[data-ck-chrome="riso"] hr {
 }
 .ck-riso-marks::before { top: 4px; left: 8px; }
 .ck-riso-marks::after  { bottom: 4px; right: 8px; }
+
+html[data-ck-chrome="riso"] .ck-actionbar-panel,
+html[data-ck-chrome="riso"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 2px solid var(--ck-text-primary);
+  border-radius: 4px;
+  box-shadow: 5px 5px 0 var(--ck-riso-blue);
+}

package/src/styles/chrome-sketch.css

@@ -352,3 +352,11 @@ html[data-ck-chrome="sketch"] hr {
     stroke-dasharray: none;
   }
 }
+
+html[data-ck-chrome="sketch"] .ck-actionbar-panel,
+html[data-ck-chrome="sketch"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 2px solid var(--ck-text-primary);
+  border-radius: 14px 18px 16px 20px / 18px 14px 20px 16px;
+  box-shadow: 4px 5px 0 var(--ck-text-primary);
+}

package/src/styles/chrome-swiss.css

@@ -255,3 +255,11 @@ html[data-ck-chrome="swiss"] a {
   text-underline-offset: 3px;
   text-decoration-thickness: 1px;
 }
+
+html[data-ck-chrome="swiss"] .ck-actionbar-panel,
+html[data-ck-chrome="swiss"] .ck-actionbar-toast {
+  background: var(--ck-bg-canvas);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 0;
+  box-shadow: var(--ck-shadow-1, 0 2px 8px rgba(0, 0, 0, 0.08));
+}

package/src/styles/chrome-terminal.css

@@ -261,3 +261,12 @@ html[data-ck-chrome="terminal"] [role="dialog"] > div > div {
   box-shadow: none;
   font-family: var(--ck-font-mono);
 }
+
+html[data-ck-chrome="terminal"] .ck-actionbar-panel,
+html[data-ck-chrome="terminal"] .ck-actionbar-toast {
+  background: var(--ck-bg-surface);
+  border: 1px solid var(--ck-border-subtle);
+  border-radius: 2px;
+  box-shadow: none;
+  font-family: var(--ck-font-mono);
+}