@cosxai/ui 0.3.0 → 0.3.2

package/package.json

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

package/src/actionbar/ActionBar.tsx

@@ -146,7 +146,7 @@ export function ActionBar({
   if (!ctx) {
     throw new Error("<ActionBar> must be inside <ActionBarProvider>");
   }
-  const { items, categories, expandedKey, setExpandedKey } = ctx;
+  const { items, categories, expandedKey, setExpandedKey, statusDot } = ctx;
   const vp = useViewport();
   const isPhone = vp.isPhone;
 
@@ -276,7 +276,11 @@ export function ActionBar({
   }, [expandedKey, setExpandedKey]);
 
   // ----- Empty state -----
-  if (items.length === 0) return null;
+  // Bar renders when EITHER any page item is registered OR the
+  // status dot is set. Without the statusDot check, an app whose
+  // only consumer is `useActionBarStatusDot` (e.g. a system-status-
+  // only surface) would never see the bar at all.
+  if (items.length === 0 && !statusDot) return null;
 
   // ----- Collapsed handle (phone only) -----
   if (isPhone && collapsibleOnPhone && collapsed) {
@@ -402,11 +406,11 @@ export function ActionBar({
       {/* Leading entries — flat items + group heads with disclosure regions. */}
       {leadingEntries.map(renderEntry)}
 
-      {/* Spacer pushes trailing entries to the right edge of the bar.
-          Only rendered when there's at least one trailing entry, so the
-          bar still hugs its content tightly when no trailing slot is in
-          use. */}
-      {trailingEntries.length > 0 && (
+      {/* Spacer pushes whatever is right-aligned (trailing entries +/or
+          the bar-intrinsic status dot) to the right edge. Only rendered
+          when there IS something on the right, so the bar still hugs
+          its content tightly when neither is in use. */}
+      {(trailingEntries.length > 0 || statusDot) && (
         <span
           aria-hidden
           data-ck-actionbar-spacer
@@ -417,6 +421,35 @@ export function ActionBar({
       {/* Trailing entries — pin to the right edge regardless of
           registration order. Same rendering rules as leading. */}
       {trailingEntries.map(renderEntry)}
+
+      {/* Status dot — bar-intrinsic chrome at the right edge,
+          mirroring the left-edge drag grip. Consumer-controlled via
+          `useActionBarStatusDot()`. Visual: a small coloured dot in
+          a 28×BAR_HEIGHT slot. Renders as a button when an onClick
+          is provided; otherwise a plain span (no interactive
+          affordances). */}
+      {statusDot &&
+        (statusDot.onClick ? (
+          <button
+            type="button"
+            onClick={statusDot.onClick}
+            aria-label={statusDot.title ?? "Status"}
+            title={statusDot.title ?? "Status"}
+            data-ck-actionbar-status-dot
+            style={rightEdgeButtonStyle}
+          >
+            <StatusDotGlyph color={statusDot.color} pulse={statusDot.pulse} />
+          </button>
+        ) : (
+          <span
+            aria-label={statusDot.title ?? "Status"}
+            title={statusDot.title ?? "Status"}
+            data-ck-actionbar-status-dot
+            style={rightEdgeButtonStyle}
+          >
+            <StatusDotGlyph color={statusDot.color} pulse={statusDot.pulse} />
+          </span>
+        ))}
     </div>
   );
 
@@ -472,3 +505,49 @@ const leftEdgeButtonStyle: CSSProperties = {
   color: "var(--ck-text-tertiary)",
   borderRadius: 0,
 };
+
+// Right-edge button — mirrors leftEdgeButtonStyle in dimensions, used
+// for the status dot. Cursor stays default for the non-interactive
+// span variant; the interactive (onClick) path is a real <button>
+// that picks up :hover / :focus styles from base.css.
+const rightEdgeButtonStyle: CSSProperties = {
+  ...leftEdgeButtonStyle,
+};
+
+// StatusDotGlyph — the actual coloured circle, sized to read at par
+// with the grip's six-dot icon. Pulse via a shared keyframe injected
+// at module scope (one stylesheet entry; idempotent across mounts).
+interface StatusDotGlyphProps {
+  color: string;
+  pulse?: boolean | undefined;
+}
+function StatusDotGlyph({ color, pulse }: StatusDotGlyphProps) {
+  return (
+    <span
+      aria-hidden
+      style={{
+        display: "inline-block",
+        width: 8,
+        height: 8,
+        borderRadius: "50%",
+        background: color,
+        animation: pulse ? "ck-actionbar-status-pulse 1.4s ease-in-out infinite" : undefined,
+      }}
+    />
+  );
+}
+
+// One global stylesheet entry for the pulse keyframe. Injected once
+// on first import. Idempotent — re-imports check by id.
+if (typeof document !== "undefined") {
+  const STYLE_ID = "ck-actionbar-status-pulse";
+  if (!document.getElementById(STYLE_ID)) {
+    const el = document.createElement("style");
+    el.id = STYLE_ID;
+    el.textContent = `@keyframes ck-actionbar-status-pulse {
+        0%, 100% { opacity: 1; }
+        50% { opacity: 0.45; }
+      }`;
+    document.head.appendChild(el);
+  }
+}

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 } from "./types";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot } from "./types";
 
 // Provider for the action-bar registry + expansion state +
 // category catalog. Mount once near the app root, inside the
@@ -23,6 +23,7 @@ export function ActionBarProvider({
 }: ActionBarProviderProps) {
   const [sources, setSources] = useState<Record<string, ActionBarItem[]>>({});
   const [expandedKey, setExpandedKey] = useState<string | null>(null);
+  const [statusDot, setStatusDot] = useState<ActionBarStatusDot | null>(null);
 
   const register = useCallback((sourceKey: string, items: ActionBarItem[]) => {
     setSources((prev) => {
@@ -64,8 +65,10 @@ export function ActionBarProvider({
       categories,
       expandedKey,
       setExpandedKey,
+      statusDot,
+      setStatusDot,
     }),
-    [register, unregister, items, categories, expandedKey],
+    [register, unregister, items, categories, expandedKey, statusDot],
   );
 
   return (

package/src/actionbar/actionbar-context.ts

@@ -1,10 +1,11 @@
 import { createContext } from "react";
-import type { ActionBarItem, ActionBarCategories } from "./types";
+import type { ActionBarItem, ActionBarCategories, ActionBarStatusDot } from "./types";
 
-// Registry + expansion + category catalog. Items are pushed by
-// pages through useActionBarItems(); categories are declared at
-// the provider level (passed as a prop). expandedKey tracks which
-// group is currently open (one at a time).
+// Registry + expansion + category catalog + status-dot slot. Items are
+// pushed by pages through useActionBarItems(); the status dot is
+// pushed by a separate hook (useActionBarStatusDot) because it's
+// bar-intrinsic chrome, not page-level content. expandedKey tracks
+// which group is currently open (one at a time).
 
 export interface ActionBarContextValue {
   register: (sourceKey: string, items: ActionBarItem[]) => void;
@@ -18,6 +19,10 @@ export interface ActionBarContextValue {
   // Which group head is currently expanded. null = none.
   expandedKey: string | null;
   setExpandedKey: (key: string | null) => void;
+  // Bar-intrinsic right-edge status indicator. null when no consumer
+  // has registered one. Last call to setStatusDot wins.
+  statusDot: ActionBarStatusDot | null;
+  setStatusDot: (dot: ActionBarStatusDot | null) => void;
 }
 
 export const ActionBarContext = createContext<ActionBarContextValue | null>(null);

package/src/actionbar/index.ts

@@ -5,10 +5,12 @@ export type { ActionBarProps } from "./ActionBar";
 export { ActionBarButton } from "./ActionBarButton";
 export type { ActionBarButtonProps } from "./ActionBarButton";
 export { useActionBarItems, useActionBarItemsContext } from "./useActionBarItems";
+export { useActionBarStatusDot } from "./useActionBarStatusDot";
 export type {
   ActionBarItem,
   ActionBarItemVariant,
   ActionBarItemSlot,
+  ActionBarStatusDot,
   ActionBarCategory,
   ActionBarCategories,
 } from "./types";

package/src/actionbar/types.ts

@@ -62,3 +62,33 @@ export interface ActionBarSource {
   sourceKey: string;
   items: ActionBarItem[];
 }
+
+// Status dot — bar-intrinsic chrome rendered at the right edge,
+// mirroring the left-edge drag grip. Distinct from `ActionBarItem`
+// (which is page-level content registered through the items
+// registry): a status dot is a fixed system affordance —
+// connection / sync / identity health. The grip on the left says
+// "you can move this thing"; the status dot on the right says
+// "here's how the system is doing."
+//
+// Visual: a small coloured dot, optionally pulsing. Hover shows the
+// title as a native tooltip. Click fires `onClick` — the bar owns
+// no popover behaviour; consumers render their own popover anchored
+// to body / wherever fits their UX.
+//
+// Registered via `useActionBarStatusDot()`. One source of truth at
+// any time (last call wins). Pass `null` to clear.
+export interface ActionBarStatusDot {
+  // Colour of the dot. Any CSS colour string — typically a token
+  // like `var(--ck-status-success)`. The bar applies no defaulting,
+  // so omit the entry (pass null to the hook) to render no dot.
+  color: string;
+  // Hover tooltip + aria-label. Falls back to "Status".
+  title?: string;
+  // Click handler. When omitted the dot renders as a non-interactive
+  // span (no focus ring, no cursor change, no role=button).
+  onClick?: () => void;
+  // When true, the dot pulses (CSS animation). Use sparingly —
+  // pulsing reads as attention-grabbing.
+  pulse?: boolean;
+}

package/src/actionbar/useActionBarStatusDot.ts

@@ -0,0 +1,49 @@
+import { useContext, useEffect } from "react";
+import { ActionBarContext } from "./actionbar-context";
+import type { ActionBarStatusDot } from "./types";
+
+// Push a status-dot config into the action bar's right-edge slot.
+// The bar renders the dot as bar-intrinsic chrome (mirroring the
+// left-edge drag grip), separate from the items registry.
+//
+// Pass `null` to clear. Last call wins — there's no source-key
+// fan-out as with items, because the status dot is a single
+// system-level affordance (sync / connection / identity) and
+// stacking multiple makes no UX sense.
+//
+// On unmount, the dot is cleared automatically.
+//
+// **Important**: pass a stable config object (typically via
+// `useMemo`), or omit fields you don't change between renders.
+// The effect re-runs when individual fields change — colour
+// transitions or pulse toggles re-render the dot but don't thrash
+// the bar.
+export function useActionBarStatusDot(config: ActionBarStatusDot | null) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("useActionBarStatusDot must be used within <ActionBarProvider>");
+  }
+  const { setStatusDot } = ctx;
+  // Project config to primitive deps so a fresh-but-equivalent
+  // config object doesn't trigger thrash. onClick identity changes
+  // are tolerated through a manual ref capture in the bar render.
+  const color = config?.color;
+  const title = config?.title;
+  const onClick = config?.onClick;
+  const pulse = config?.pulse;
+  useEffect(() => {
+    if (color === undefined) {
+      setStatusDot(null);
+      return;
+    }
+    setStatusDot({
+      color,
+      ...(title !== undefined ? { title } : {}),
+      ...(onClick !== undefined ? { onClick } : {}),
+      ...(pulse !== undefined ? { pulse } : {}),
+    });
+    return () => {
+      setStatusDot(null);
+    };
+  }, [setStatusDot, color, title, onClick, pulse]);
+}