@cosxai/ui 0.2.10 → 0.3.1

package/package.json

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

package/src/actionbar/ActionBar.tsx

@@ -6,6 +6,7 @@ import {
   useRef,
   useState,
   type CSSProperties,
+  type ReactNode,
 } from "react";
 import { ActionBarContext } from "./actionbar-context";
 import { ActionBarButton } from "./ActionBarButton";
@@ -145,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;
 
@@ -229,8 +230,29 @@ export function ActionBar({
     setPos({ type: "default" });
   }, [storageKey]);
 
-  // ----- Entries (flat vs group) -----
-  const entries = useMemo(() => buildEntries(items), [items]);
+  // ----- Entries (flat vs group), partitioned by slot -----
+  // Items default to the leading slot. Trailing items render after a
+  // flex spacer so they pin to the right edge regardless of
+  // registration order — system status indicators (sync, identity,
+  // connection) belong here, where page items registering later
+  // can't shuffle them. buildEntries runs per slot so category
+  // grouping stays slot-local (a category split across slots is an
+  // edge case we intentionally don't fold across the spacer).
+  const { leadingEntries, trailingEntries } = useMemo(() => {
+    const leading: ActionBarItem[] = [];
+    const trailing: ActionBarItem[] = [];
+    for (const it of items) {
+      (it.slot === "trailing" ? trailing : leading).push(it);
+    }
+    return {
+      leadingEntries: buildEntries(leading),
+      trailingEntries: buildEntries(trailing),
+    };
+  }, [items]);
+  const entries = useMemo(
+    () => [...leadingEntries, ...trailingEntries],
+    [leadingEntries, trailingEntries],
+  );
 
   // Cleanup stale expansion if the corresponding group disappears.
   useEffect(() => {
@@ -377,49 +399,94 @@ export function ActionBar({
         </button>
       ) : null}
 
-      {/* Entries: flat items + group heads with disclosure regions. */}
-      {entries.map((entry) => {
-        if (entry.kind === "flat" && entry.item) {
-          return (
-            <ActionBarButton
-              key={entry.expansionKey}
-              icon={entry.item.icon}
-              label={entry.item.label}
-              title={entry.item.title}
-              active={entry.item.active}
-              disabled={entry.item.disabled}
-              variant={entry.item.variant}
-              hint={entry.item.hint}
-              onClick={entry.item.onClick}
-            />
-          );
-        }
-        const cat = entry.category!;
-        const catDef = categories[cat];
-        const hasActiveChild = entry.groupItems!.some((it) => it.active);
-        const isOpen = expandedKey === entry.expansionKey;
-        return (
-          <ActionBarMenuGroup
-            key={entry.expansionKey}
-            label={catDef?.label ?? cat}
-            icon={catDef?.icon}
-            hasActiveChild={hasActiveChild}
-            isOpen={isOpen}
-            onToggle={() =>
-              setExpandedKey(isOpen ? null : entry.expansionKey)
-            }
-            items={entry.groupItems!}
-            onItemClicked={(it) => {
-              it.onClick();
-              if (!it.keepGroupOpenOnClick) {
-                setExpandedKey(null);
-              }
-            }}
-          />
-        );
-      })}
+      {/* Leading entries — flat items + group heads with disclosure regions. */}
+      {leadingEntries.map(renderEntry)}
+
+      {/* 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
+          style={{ flex: "1 1 auto", minWidth: 12 }}
+        />
+      )}
+
+      {/* 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>
   );
+
+  function renderEntry(entry: BuildEntry): ReactNode {
+    if (entry.kind === "flat" && entry.item) {
+      return (
+        <ActionBarButton
+          key={entry.expansionKey}
+          icon={entry.item.icon}
+          label={entry.item.label}
+          title={entry.item.title}
+          active={entry.item.active}
+          disabled={entry.item.disabled}
+          variant={entry.item.variant}
+          hint={entry.item.hint}
+          onClick={entry.item.onClick}
+        />
+      );
+    }
+    const cat = entry.category!;
+    const catDef = categories[cat];
+    const hasActiveChild = entry.groupItems!.some((it) => it.active);
+    const isOpen = expandedKey === entry.expansionKey;
+    return (
+      <ActionBarMenuGroup
+        key={entry.expansionKey}
+        label={catDef?.label ?? cat}
+        icon={catDef?.icon}
+        hasActiveChild={hasActiveChild}
+        isOpen={isOpen}
+        onToggle={() => setExpandedKey(isOpen ? null : entry.expansionKey)}
+        items={entry.groupItems!}
+        onItemClicked={(it) => {
+          it.onClick();
+          if (!it.keepGroupOpenOnClick) {
+            setExpandedKey(null);
+          }
+        }}
+      />
+    );
+  }
 }
 
 const leftEdgeButtonStyle: CSSProperties = {
@@ -434,3 +501,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,9 +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

@@ -7,6 +7,16 @@ import type { ReactNode } from "react";
 
 export type ActionBarItemVariant = "ghost" | "primary" | "soft";
 
+// Slot anchor — which edge of the bar the item gravitates toward.
+// `leading` (default) keeps existing behavior: items pack from the
+// drag grip outward in registration order. `trailing` pins the item
+// to the right edge with a flex spacer separating it from the
+// leading group, regardless of registration order. Use trailing for
+// system status indicators (sync, connection, identity) that need a
+// stable visual home and shouldn't be shuffled by page items
+// registering after them.
+export type ActionBarItemSlot = "leading" | "trailing";
+
 export interface ActionBarItem {
   // React key for the rendered button. Stable across rerenders.
   key: string;
@@ -33,6 +43,10 @@ export interface ActionBarItem {
   // (e.g. for items whose post-click state changes the label
   // and should stay visible).
   keepGroupOpenOnClick?: boolean;
+  // Slot anchor. Defaults to `leading`. Trailing items render after
+  // a flex spacer so they pin to the right edge regardless of
+  // registration order — system status indicators belong here.
+  slot?: ActionBarItemSlot;
 }
 
 // Category definition — declared at the provider level. Drives
@@ -48,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]);
+}