@cosxai/ui 0.8.4 → 0.10.0

package/package.json

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

package/src/actionbar/ActionBar.tsx

@@ -78,6 +78,25 @@ function loadCollapsed(storageKey: string): boolean {
   }
 }
 
+function loadAdminMode(storageKey: string): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.localStorage.getItem(`${storageKey}:admin`) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function persistAdminMode(storageKey: string, on: boolean) {
+  if (typeof window === "undefined") return;
+  try {
+    if (on) window.localStorage.setItem(`${storageKey}:admin`, "1");
+    else window.localStorage.removeItem(`${storageKey}:admin`);
+  } catch {
+    /* ignore */
+  }
+}
+
 interface BuildEntry {
   kind: "flat" | "group";
   expansionKey: string;
@@ -175,6 +194,26 @@ export function ActionBar({
     return () => window.removeEventListener("resize", reclamp);
   }, []);
 
+  // ----- Admin mode toggle (any registered item with adminOnly=true) -----
+  // Admin items stay hidden by default; a small toggle button (rendered
+  // between the grip and the first item) flips this to reveal them.
+  // Persisted per storageKey so admin users stay in the mode they
+  // last chose across route navigations. When no consumer registers
+  // admin items, the toggle button doesn't render.
+  const [adminMode, setAdminMode] = useState<boolean>(() => loadAdminMode(storageKey));
+  const toggleAdminMode = useCallback(() => {
+    setAdminMode((prev) => {
+      const next = !prev;
+      persistAdminMode(storageKey, next);
+      return next;
+    });
+  }, [storageKey]);
+  const hasAdminItems = useMemo(() => items.some((it) => it.adminOnly === true), [items]);
+  const visibleItems = useMemo(
+    () => (adminMode ? items : items.filter((it) => it.adminOnly !== true)),
+    [items, adminMode],
+  );
+
   // ----- Collapsed state (phone only) -----
   const [collapsed, setCollapsed] = useState<boolean>(() => loadCollapsed(storageKey));
   useEffect(() => {
@@ -241,14 +280,14 @@ export function ActionBar({
   const { leadingEntries, trailingEntries } = useMemo(() => {
     const leading: ActionBarItem[] = [];
     const trailing: ActionBarItem[] = [];
-    for (const it of items) {
+    for (const it of visibleItems) {
       (it.slot === "trailing" ? trailing : leading).push(it);
     }
     return {
       leadingEntries: buildEntries(leading),
       trailingEntries: buildEntries(trailing),
     };
-  }, [items]);
+  }, [visibleItems]);
   const entries = useMemo(
     () => [...leadingEntries, ...trailingEntries],
     [leadingEntries, trailingEntries],
@@ -359,12 +398,21 @@ export function ActionBar({
         alignItems: "center",
         gap: 4,
         zIndex: 80,
-        background: "var(--ck-bg-surface)",
-        border: "1px solid var(--ck-border-subtle)",
+        // Subtle accent tint when admin mode is active so the bar reads
+        // as "elevated privileges on" without a full colour swap.
+        background: adminMode
+          ? "color-mix(in oklab, var(--ck-accent, #4f46e5) 8%, var(--ck-bg-surface))"
+          : "var(--ck-bg-surface)",
+        border: `1px solid ${
+          adminMode
+            ? "var(--ck-accent, #4f46e5)"
+            : "var(--ck-border-subtle)"
+        }`,
         borderRadius: 999,
         boxShadow: "var(--ck-shadow-3)",
         fontFamily: "var(--ck-font-sans)",
         color: "var(--ck-text-primary)",
+        transition: "background 180ms ease-out, border-color 180ms ease-out",
         ...style,
       }}
     >
@@ -411,6 +459,57 @@ export function ActionBar({
         </button>
       ) : null}
 
+      {/* Admin-mode toggle. Only renders when at least one registered
+          item has adminOnly=true. When active: filled accent circle;
+          when inactive: outlined muted circle. Uses a small shield
+          glyph so the affordance reads as "elevated privileges" at a
+          glance, distinct from a normal action button. */}
+      {hasAdminItems && (
+        <button
+          type="button"
+          onClick={toggleAdminMode}
+          aria-label={adminMode ? "Exit admin mode" : "Enter admin mode"}
+          aria-pressed={adminMode}
+          title={adminMode ? "Admin mode · click to exit" : "Enter admin mode"}
+          data-ck-actionbar-admin-toggle
+          data-active={adminMode ? "1" : "0"}
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            justifyContent: "center",
+            width: 28,
+            height: 28,
+            padding: 0,
+            marginLeft: 2,
+            marginRight: 2,
+            borderRadius: 999,
+            background: adminMode ? "var(--ck-accent, #4f46e5)" : "transparent",
+            color: adminMode
+              ? "var(--ck-accent-fg, #fff)"
+              : "var(--ck-text-secondary, #666)",
+            border: adminMode
+              ? "1px solid var(--ck-accent, #4f46e5)"
+              : "1px solid var(--ck-border-subtle, #eee)",
+            cursor: "pointer",
+            transition: "background 160ms ease-out, color 160ms ease-out, border-color 160ms ease-out",
+          }}
+        >
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden
+          >
+            <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+          </svg>
+        </button>
+      )}
+
       {/* Balancing leading spacer — only present when the right side
           holds ONLY a status dot (no trailing items). With a left
           and right spacer of equal flex weight, the leading items

package/src/actionbar/ActionBarModeHandle.tsx

@@ -0,0 +1,171 @@
+import { forwardRef, type CSSProperties } from "react";
+
+// ActionBarModeHandle — the top-edge peek button that lets a user
+// switch the ActionBar between two content sets ("modes"). Sits
+// above the ActionBar's centred bottom position, showing only a
+// slim 6px sliver at rest; grows on hover / focus to a full 28px
+// tappable disc with a tooltip beneath the pointer.
+//
+// Compose with: `useActionBarMode` hook (or your own state) to swap
+// the items registered via useActionBarItems when the handle fires
+// onClick. Gate visibility on a permission bit (e.g.
+// `document.capabilities.manage`) — passing `visible={false}` hides
+// the handle entirely so non-privileged users never see the
+// affordance.
+//
+// Visual: fixed positioning centred at the bottom of the viewport,
+// stacked ABOVE the ActionBar (which lives at `bottom: 24px +
+// tabbar-height`). The handle sits ~6px above the ActionBar's top
+// edge at rest and animates upward on hover.
+//
+// Positioning contract: consumers may pass `bottom` to override the
+// default 66px (24 gutter + 48 bar height - 6 overlap). Otherwise
+// this matches the default ActionBar's centred bottom placement.
+//
+// Forwards ref to the underlying <button>.
+export interface ActionBarModeHandleProps {
+  /**
+   * Called when the handle is clicked / activated. Consumer should
+   * flip the active mode state here (which drives
+   * useActionBarItems(sourceKey, items) with a different sourceKey).
+   */
+  onClick: () => void;
+  /**
+   * Human-readable label describing what the click will do
+   * ("Switch to manage mode"). Used as both aria-label and the
+   * hover tooltip.
+   */
+  label: string;
+  /**
+   * When false, the handle renders nothing. Consumers wire this to
+   * their capability check (e.g. `capabilities.manage === true`)
+   * so principals without the permission never see the affordance.
+   * Default: true.
+   */
+  visible?: boolean | undefined;
+  /**
+   * Optional bottom offset in px (default: matches the ActionBar's
+   * default centred position — 66px = 24 gutter + 48 bar height - 6
+   * overlap, plus the same tabbar + safe-area terms). Override when
+   * the ActionBar is docked non-default.
+   */
+  bottom?: number | string | undefined;
+  /**
+   * Extra className appended to the handle's root class. Handy for
+   * tests + one-off styling. Default className: `ck-actionbar-handle`.
+   */
+  className?: string | undefined;
+  /**
+   * Extra inline styles merged onto the root. Only use for one-off
+   * z-index / offset overrides; the visual language should stay
+   * consistent across surfaces.
+   */
+  style?: CSSProperties | undefined;
+}
+
+const HANDLE_REST_WIDTH = 44;
+const HANDLE_REST_HEIGHT = 6;
+const HANDLE_HOVER_WIDTH = 68;
+const HANDLE_HOVER_HEIGHT = 24;
+// Overlap the ActionBar's top edge by 4px so the handle looks
+// tethered to the bar rather than floating above it.
+const HANDLE_BOTTOM_DEFAULT = "calc(24px + 48px - 4px + var(--ck-tabbar-height, 0px) + env(safe-area-inset-bottom, 0px))";
+
+export const ActionBarModeHandle = forwardRef<HTMLButtonElement, ActionBarModeHandleProps>(
+  function ActionBarModeHandle(
+    {
+      onClick,
+      label,
+      visible = true,
+      bottom,
+      className,
+      style,
+    },
+    ref,
+  ) {
+    if (!visible) return null;
+    const resolvedBottom =
+      typeof bottom === "number"
+        ? `${bottom}px`
+        : typeof bottom === "string"
+          ? bottom
+          : HANDLE_BOTTOM_DEFAULT;
+    return (
+      <button
+        ref={ref}
+        type="button"
+        onClick={onClick}
+        aria-label={label}
+        title={label}
+        className={`ck-actionbar-handle${className ? ` ${className}` : ""}`}
+        style={{
+          position: "fixed",
+          left: "50%",
+          bottom: resolvedBottom,
+          transform: "translateX(-50%)",
+          // Rest state: narrow slim strip at the top edge of the bar.
+          width: `var(--ck-actionbar-handle-w, ${HANDLE_REST_WIDTH}px)`,
+          height: `var(--ck-actionbar-handle-h, ${HANDLE_REST_HEIGHT}px)`,
+          padding: 0,
+          margin: 0,
+          border: 0,
+          borderRadius: 999,
+          background: "var(--ck-accent, #4f46e5)",
+          color: "var(--ck-accent-fg, #fff)",
+          fontSize: 11,
+          fontWeight: 500,
+          letterSpacing: 0.2,
+          lineHeight: 1,
+          overflow: "hidden",
+          whiteSpace: "nowrap",
+          cursor: "pointer",
+          // Sit above the ActionBar (z-index 80 in ActionBar.tsx).
+          zIndex: 85,
+          boxShadow: "0 2px 8px rgba(0,0,0,0.14)",
+          transition:
+            "width 220ms cubic-bezier(0.34, 1.56, 0.64, 1)," +
+            "height 220ms cubic-bezier(0.34, 1.56, 0.64, 1)," +
+            "box-shadow 220ms ease-out",
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          ...style,
+        }}
+        // Inline hover/focus expansion — pure CSS on the same element
+        // via CSSProperties gives us the animation without a global
+        // stylesheet dependency in the kit.
+        onMouseEnter={(e) => {
+          const el = e.currentTarget;
+          el.style.setProperty("--ck-actionbar-handle-w", `${HANDLE_HOVER_WIDTH}px`);
+          el.style.setProperty("--ck-actionbar-handle-h", `${HANDLE_HOVER_HEIGHT}px`);
+          el.style.boxShadow = "0 4px 14px rgba(0,0,0,0.22)";
+        }}
+        onMouseLeave={(e) => {
+          const el = e.currentTarget;
+          el.style.setProperty("--ck-actionbar-handle-w", `${HANDLE_REST_WIDTH}px`);
+          el.style.setProperty("--ck-actionbar-handle-h", `${HANDLE_REST_HEIGHT}px`);
+          el.style.boxShadow = "0 2px 8px rgba(0,0,0,0.14)";
+        }}
+        onFocus={(e) => {
+          const el = e.currentTarget;
+          el.style.setProperty("--ck-actionbar-handle-w", `${HANDLE_HOVER_WIDTH}px`);
+          el.style.setProperty("--ck-actionbar-handle-h", `${HANDLE_HOVER_HEIGHT}px`);
+          el.style.boxShadow = "0 4px 14px rgba(0,0,0,0.22)";
+        }}
+        onBlur={(e) => {
+          const el = e.currentTarget;
+          el.style.setProperty("--ck-actionbar-handle-w", `${HANDLE_REST_WIDTH}px`);
+          el.style.setProperty("--ck-actionbar-handle-h", `${HANDLE_REST_HEIGHT}px`);
+          el.style.boxShadow = "0 2px 8px rgba(0,0,0,0.14)";
+        }}
+      >
+        {/* Only visible when expanded — CSS `overflow: hidden` on the
+            button clips it at rest. Kept as visible text (not aria-
+            hidden) so screen readers can still hear it via title. */}
+        <span aria-hidden style={{ opacity: 0.95 }}>
+          {label}
+        </span>
+      </button>
+    );
+  },
+);

package/src/actionbar/index.ts

@@ -6,6 +6,14 @@ export { ActionBarButton } from "./ActionBarButton";
 export type { ActionBarButtonProps } from "./ActionBarButton";
 export { useActionBarItems, useActionBarItemsContext } from "./useActionBarItems";
 export { useActionBarStatusDot } from "./useActionBarStatusDot";
+export { ActionBarModeHandle } from "./ActionBarModeHandle";
+export type { ActionBarModeHandleProps } from "./ActionBarModeHandle";
+export { useActionBarMode } from "./useActionBarMode";
+export type {
+  ActionBarModeConfig,
+  UseActionBarModeOptions,
+  UseActionBarModeResult,
+} from "./useActionBarMode";
 export type {
   ActionBarItem,
   ActionBarItemVariant,

package/src/actionbar/types.ts

@@ -47,6 +47,19 @@ export interface ActionBarItem {
   // a flex spacer so they pin to the right edge regardless of
   // registration order — system status indicators belong here.
   slot?: ActionBarItemSlot;
+  // Marks this item as admin-only. Hidden until the ActionBar's
+  // admin-mode toggle is switched on. The toggle button auto-appears
+  // on the bar whenever at least one registered item has adminOnly=
+  // true; when no consumer registers such items, the toggle stays
+  // hidden and the bar looks exactly as it always did.
+  //
+  // Use for elevated-privilege actions that would confuse regular
+  // users (version history, retry render, delete forever, etc.).
+  // Consumer decides eligibility upstream — typically by only
+  // registering the item when the caller has `capabilities.manage`
+  // (or an equivalent gate) === true. The kit does not check
+  // permissions; it only handles the toggle UX.
+  adminOnly?: boolean;
 }
 
 // Category definition — declared at the provider level. Drives

package/src/actionbar/useActionBarMode.ts

@@ -0,0 +1,144 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useActionBarItems } from "./useActionBarItems";
+import type { ActionBarItem } from "./types";
+
+// useActionBarMode — one hook that manages a small set of named
+// "modes" (each with its own item list) + registers the active mode's
+// items into the ActionBar registry. Consumer combines this with
+// <ActionBarModeHandle> to give privileged users a peek-out affordance
+// that flips between the modes.
+//
+// Design intent (M4.5 block_doc surface):
+//   - Default mode: standard viewer actions (comment / download / share)
+//   - Manage mode: admin-only shortcuts (preview draft / manage share /
+//     view activity), gated behind `capabilities.manage === true`
+//   - Draft mode (optional third): appears once the user enters draft
+//     preview; distinct action set (publish / discard / raw JSON /
+//     return)
+//
+// The mode name is the ActionBar's source key, so switching modes
+// unregisters the previous set and registers the new set atomically
+// (useActionBarItems handles the cleanup).
+//
+// State persistence: pass `storageKey` for localStorage-backed
+// stickiness across reloads. Nil-safe when window is unavailable
+// (SSR).
+
+export type ActionBarModeConfig<K extends string> = {
+  [key in K]: ActionBarItem[];
+};
+
+export interface UseActionBarModeOptions<K extends string> {
+  /**
+   * Map of mode keys → items. Each mode key becomes the source key
+   * passed to useActionBarItems, so it must be a stable string
+   * (e.g. "viewer", "manage") — mode registrations will not
+   * "cross-contaminate" the item set of another mode.
+   */
+  modes: ActionBarModeConfig<K>;
+  /**
+   * Which mode to start in. Overridden by localStorage when
+   * `storageKey` is set AND localStorage has a valid value.
+   */
+  defaultMode: K;
+  /**
+   * Optional localStorage key. When set, the current mode is
+   * persisted + rehydrated across reloads.
+   */
+  storageKey?: string | undefined;
+}
+
+export interface UseActionBarModeResult<K extends string> {
+  /** The currently active mode key. */
+  mode: K;
+  /** Set the mode explicitly (typically wired to the mode Handle). */
+  setMode: (next: K) => void;
+  /**
+   * Toggle between the FIRST two modes in the config's iteration
+   * order. Convenience for the common two-mode case; a
+   * three-mode consumer uses setMode directly.
+   */
+  toggle: () => void;
+  /**
+   * All configured mode keys in registration order — useful for
+   * building a cycle-through-modes button.
+   */
+  allModes: readonly K[];
+}
+
+function loadPersistedMode<K extends string>(
+  storageKey: string,
+  allModes: readonly K[],
+): K | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (raw && (allModes as readonly string[]).includes(raw)) {
+      return raw as K;
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+function persistMode(storageKey: string, mode: string) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(storageKey, mode);
+  } catch {
+    /* ignore */
+  }
+}
+
+export function useActionBarMode<K extends string>(
+  opts: UseActionBarModeOptions<K>,
+): UseActionBarModeResult<K> {
+  const { modes, defaultMode, storageKey } = opts;
+  const allModes = useMemo(() => Object.keys(modes) as K[], [modes]);
+  const [mode, setModeState] = useState<K>(() => {
+    if (storageKey) {
+      const persisted = loadPersistedMode<K>(storageKey, allModes);
+      if (persisted) return persisted;
+    }
+    return defaultMode;
+  });
+
+  // If the modes config changes (dev / hot reload) so the current
+  // mode key is no longer valid, drop back to the default.
+  useEffect(() => {
+    if (!(allModes as readonly string[]).includes(mode)) {
+      setModeState(defaultMode);
+    }
+  }, [mode, allModes, defaultMode]);
+
+  const setMode = useCallback(
+    (next: K) => {
+      setModeState(next);
+      if (storageKey) persistMode(storageKey, next);
+    },
+    [storageKey],
+  );
+
+  const toggle = useCallback(() => {
+    if (allModes.length < 2) return;
+    const idx = allModes.indexOf(mode);
+    // Cycle to the NEXT mode; wrap-around handles both the "toggle
+    // between 2" and "cycle through 3+" cases.
+    const nextIdx = (idx + 1) % allModes.length;
+    const next = allModes[nextIdx];
+    if (next !== undefined) {
+      setMode(next);
+    }
+  }, [allModes, mode, setMode]);
+
+  // Register the active mode's items with the ActionBar. Uses the
+  // mode key as the source key, so switching modes atomically
+  // unregisters the previous set. Items themselves must be stable
+  // (useMemo'd) — the ActionBar deduplicates by reference, so passing
+  // `modes[mode]` re-uses the caller's memoized array.
+  const activeItems = modes[mode];
+  useActionBarItems(mode, activeItems);
+
+  return { mode, setMode, toggle, allModes };
+}