@cosxai/ui 0.8.4 → 0.9.0

package/package.json

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

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/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 };
+}