@cosxai/ui 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@cosxai/ui",
+  "version": "0.1.0",
+  "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles/index.css"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosxai/product-design.git",
+    "directory": "packages/ui"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actionbar/ActionBar.tsx

@@ -0,0 +1,436 @@
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+} from "react";
+import { ActionBarContext } from "./actionbar-context";
+import { ActionBarButton } from "./ActionBarButton";
+import { ActionBarMenuGroup } from "./ActionBarMenuGroup";
+import { useViewport } from "../hooks/useViewport";
+import type { ActionBarItem } from "./types";
+
+// Floating action bar. Reads items from the registry, groups items
+// sharing a category (2+) into inline-expandable menus, supports:
+//   - drag-to-reposition on desktop (left grip; double-click resets)
+//   - phone-only collapsed handle (left-edge peek tab)
+//   - localStorage persistence of position + collapsed state
+//   - spring entry animation at the default centred position
+//   - ESC + outside-click dismissal of expanded groups
+//   - label hiding below md breakpoint (icons + tooltips only)
+//
+// Bar is purely a renderer. Pages register items via useActionBarItems().
+
+const BAR_HEIGHT = 48;
+const BAR_WIDTH_FALLBACK = 440;
+const VIEWPORT_MARGIN = 8;
+const DEFAULT_BOTTOM_GUTTER = 24;
+const COLLAPSED_HANDLE_W = 22;
+const COLLAPSED_HANDLE_H = 56;
+
+type Pos = { type: "default" } | { type: "custom"; left: number; bottom: number };
+
+function clampCustom(
+  p: { left: number; bottom: number },
+  barWidth: number,
+): { left: number; bottom: number } {
+  if (typeof window === "undefined") return p;
+  return {
+    left: Math.max(
+      VIEWPORT_MARGIN,
+      Math.min(window.innerWidth - VIEWPORT_MARGIN - barWidth, p.left),
+    ),
+    bottom: Math.max(
+      VIEWPORT_MARGIN,
+      Math.min(window.innerHeight - VIEWPORT_MARGIN - BAR_HEIGHT, p.bottom),
+    ),
+  };
+}
+
+function loadPos(storageKey: string): Pos {
+  if (typeof window === "undefined") return { type: "default" };
+  try {
+    const raw = window.localStorage.getItem(`${storageKey}:pos`);
+    if (!raw) return { type: "default" };
+    const parsed = JSON.parse(raw);
+    if (parsed?.type === "default") return { type: "default" };
+    if (
+      parsed?.type === "custom" &&
+      typeof parsed.left === "number" &&
+      typeof parsed.bottom === "number"
+    ) {
+      return { type: "custom", left: parsed.left, bottom: parsed.bottom };
+    }
+  } catch {}
+  return { type: "default" };
+}
+
+function loadCollapsed(storageKey: string): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.localStorage.getItem(`${storageKey}:collapsed`) === "1";
+  } catch {
+    return false;
+  }
+}
+
+interface BuildEntry {
+  kind: "flat" | "group";
+  expansionKey: string;
+  item?: ActionBarItem;
+  category?: string;
+  groupItems?: ActionBarItem[];
+}
+
+// Build render entries: a category with 2+ items collapses into one
+// group head at the position of its first item; later items in that
+// category are folded into the group, not re-emitted. A category
+// with one item just renders flat in place. No-category items always
+// render flat.
+function buildEntries(items: ActionBarItem[]): BuildEntry[] {
+  const countByCat: Record<string, number> = {};
+  for (const it of items) {
+    if (it.category) countByCat[it.category] = (countByCat[it.category] ?? 0) + 1;
+  }
+  const result: BuildEntry[] = [];
+  const consumed = new Set<string>();
+  for (let i = 0; i < items.length; i++) {
+    const it = items[i]!;
+    const cat = it.category;
+    if (cat && (countByCat[cat] ?? 0) >= 2) {
+      if (consumed.has(cat)) continue;
+      const groupItems = items.filter((x) => x.category === cat);
+      result.push({
+        kind: "group",
+        expansionKey: `group:${cat}`,
+        category: cat,
+        groupItems,
+      });
+      consumed.add(cat);
+      continue;
+    }
+    result.push({
+      kind: "flat",
+      expansionKey: it.key ?? `flat-${i}`,
+      item: it,
+    });
+  }
+  return result;
+}
+
+export interface ActionBarProps {
+  // localStorage namespace for position + collapsed state.
+  // Override per-app so multiple bars don't collide.
+  storageKey?: string;
+  // Enable desktop drag-to-reposition + double-click-to-reset.
+  // Default true.
+  draggable?: boolean;
+  // Enable phone-only collapsed handle. Default true.
+  collapsibleOnPhone?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function ActionBar({
+  storageKey = "ck-actionbar",
+  draggable = true,
+  collapsibleOnPhone = true,
+  className,
+  style,
+}: ActionBarProps) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("<ActionBar> must be inside <ActionBarProvider>");
+  }
+  const { items, categories, expandedKey, setExpandedKey } = ctx;
+  const vp = useViewport();
+  const isPhone = vp.isPhone;
+
+  // ----- Position state -----
+  const [pos, setPos] = useState<Pos>(() => loadPos(storageKey));
+  const barRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    try {
+      window.localStorage.setItem(`${storageKey}:pos`, JSON.stringify(pos));
+    } catch {}
+  }, [pos, storageKey]);
+
+  // Re-clamp on width resize so the bar tracks the viewport as
+  // the window resizes. Initial clamp also runs after first paint
+  // to handle saved positions from a wider window.
+  useEffect(() => {
+    const reclamp = () => {
+      setPos((p) => {
+        if (p.type !== "custom") return p;
+        const w = barRef.current?.offsetWidth ?? BAR_WIDTH_FALLBACK;
+        return { type: "custom", ...clampCustom(p, w) };
+      });
+    };
+    reclamp();
+    window.addEventListener("resize", reclamp);
+    return () => window.removeEventListener("resize", reclamp);
+  }, []);
+
+  // ----- Collapsed state (phone only) -----
+  const [collapsed, setCollapsed] = useState<boolean>(() => loadCollapsed(storageKey));
+  useEffect(() => {
+    try {
+      window.localStorage.setItem(
+        `${storageKey}:collapsed`,
+        collapsed ? "1" : "0",
+      );
+    } catch {}
+  }, [collapsed, storageKey]);
+
+  // ----- Drag handlers (desktop) -----
+  const dragRef = useRef<{ active: boolean; offsetX: number; offsetY: number }>({
+    active: false,
+    offsetX: 0,
+    offsetY: 0,
+  });
+  const onGripDown = useCallback((e: React.MouseEvent) => {
+    const rect = barRef.current?.getBoundingClientRect();
+    if (!rect) return;
+    const currentLeft = rect.left;
+    const currentBottom = window.innerHeight - rect.bottom;
+    dragRef.current = {
+      active: true,
+      offsetX: e.clientX - currentLeft,
+      offsetY: e.clientY - (window.innerHeight - currentBottom - BAR_HEIGHT),
+    };
+    e.preventDefault();
+  }, []);
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      if (!dragRef.current.active) return;
+      const w = barRef.current?.offsetWidth ?? BAR_WIDTH_FALLBACK;
+      const left = e.clientX - dragRef.current.offsetX;
+      const topY = e.clientY - dragRef.current.offsetY;
+      const bottom = window.innerHeight - topY - BAR_HEIGHT;
+      setPos({ type: "custom", ...clampCustom({ left, bottom }, w) });
+    };
+    const onUp = () => {
+      dragRef.current.active = false;
+    };
+    window.addEventListener("mousemove", onMove);
+    window.addEventListener("mouseup", onUp);
+    return () => {
+      window.removeEventListener("mousemove", onMove);
+      window.removeEventListener("mouseup", onUp);
+    };
+  }, []);
+  const onGripDoubleClick = useCallback(() => {
+    try {
+      window.localStorage.removeItem(`${storageKey}:pos`);
+    } catch {}
+    setPos({ type: "default" });
+  }, [storageKey]);
+
+  // ----- Entries (flat vs group) -----
+  const entries = useMemo(() => buildEntries(items), [items]);
+
+  // Cleanup stale expansion if the corresponding group disappears.
+  useEffect(() => {
+    if (expandedKey === null) return;
+    if (!entries.some((e) => e.kind === "group" && e.expansionKey === expandedKey)) {
+      setExpandedKey(null);
+    }
+  }, [expandedKey, entries, setExpandedKey]);
+
+  // ESC closes any open group.
+  useEffect(() => {
+    if (expandedKey === null) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        setExpandedKey(null);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [expandedKey, setExpandedKey]);
+
+  // ----- Empty state -----
+  if (items.length === 0) return null;
+
+  // ----- Collapsed handle (phone only) -----
+  if (isPhone && collapsibleOnPhone && collapsed) {
+    return (
+      <button
+        type="button"
+        onClick={() => setCollapsed(false)}
+        aria-label="Expand action bar"
+        title="Tap to expand"
+        className="ck-action-handle-enter"
+        style={{
+          position: "fixed",
+          left: 0,
+          bottom: `calc(${DEFAULT_BOTTOM_GUTTER}px + var(--ck-tabbar-height, 0px) + env(safe-area-inset-bottom, 0px))`,
+          width: COLLAPSED_HANDLE_W,
+          height: COLLAPSED_HANDLE_H,
+          padding: 0,
+          paddingLeft: 4,
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          zIndex: 80,
+          background: "var(--ck-bg-surface)",
+          border: "1px solid var(--ck-border-subtle)",
+          borderLeft: 0,
+          borderTopLeftRadius: 0,
+          borderBottomLeftRadius: 0,
+          borderTopRightRadius: 999,
+          borderBottomRightRadius: 999,
+          boxShadow: "3px 0 12px rgba(0,0,0,0.18)",
+          cursor: "pointer",
+          color: "var(--ck-text-secondary)",
+        }}
+      >
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden>
+          <path d="M12 2 L13.6 8.4 L20 10 L13.6 11.6 L12 18 L10.4 11.6 L4 10 L10.4 8.4 Z" />
+          <path
+            d="M19 16 L19.6 18.4 L22 19 L19.6 19.6 L19 22 L18.4 19.6 L16 19 L18.4 18.4 Z"
+            opacity="0.55"
+          />
+        </svg>
+      </button>
+    );
+  }
+
+  // ----- Full bar -----
+  const isDefault = pos.type === "default";
+  return (
+    <div
+      ref={barRef}
+      data-ck-actionbar
+      className={`ck-actionbar${isDefault ? " ck-actionbar-enter" : ""}${className ? ` ${className}` : ""}`}
+      style={{
+        position: "fixed",
+        ...(isDefault
+          ? {
+              left: "50%",
+              transform: "translateX(-50%)",
+              bottom: `calc(${DEFAULT_BOTTOM_GUTTER}px + var(--ck-tabbar-height, 0px) + env(safe-area-inset-bottom, 0px))`,
+            }
+          : {
+              left: pos.left,
+              bottom: pos.bottom,
+            }),
+        height: BAR_HEIGHT,
+        padding: "0 6px 0 0",
+        display: "flex",
+        alignItems: "center",
+        gap: 4,
+        zIndex: 80,
+        background: "var(--ck-bg-surface)",
+        border: "1px solid var(--ck-border-subtle)",
+        borderRadius: 999,
+        boxShadow: "var(--ck-shadow-3)",
+        fontFamily: "var(--ck-font-sans)",
+        color: "var(--ck-text-primary)",
+        ...style,
+      }}
+    >
+      {/* Left-edge button. Phone = collapse; desktop = drag grip. */}
+      {isPhone && collapsibleOnPhone ? (
+        <button
+          type="button"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse action bar"
+          title="Collapse"
+          style={leftEdgeButtonStyle}
+        >
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.8"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden
+          >
+            <polyline points="15 18 9 12 15 6" />
+          </svg>
+        </button>
+      ) : draggable ? (
+        <button
+          type="button"
+          onMouseDown={onGripDown}
+          onDoubleClick={onGripDoubleClick}
+          aria-label="Drag action bar (double-click to reset)"
+          title="Drag · double-click to reset"
+          style={{ ...leftEdgeButtonStyle, cursor: "grab" }}
+        >
+          <svg width="10" height="14" viewBox="0 0 10 14" fill="currentColor" aria-hidden>
+            <circle cx="2" cy="2" r="1" />
+            <circle cx="2" cy="7" r="1" />
+            <circle cx="2" cy="12" r="1" />
+            <circle cx="8" cy="2" r="1" />
+            <circle cx="8" cy="7" r="1" />
+            <circle cx="8" cy="12" r="1" />
+          </svg>
+        </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);
+              }
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+const leftEdgeButtonStyle: CSSProperties = {
+  width: 28,
+  height: BAR_HEIGHT,
+  padding: 0,
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  border: "none",
+  background: "transparent",
+  color: "var(--ck-text-tertiary)",
+  borderRadius: 0,
+};

package/src/actionbar/ActionBarButton.tsx

@@ -0,0 +1,110 @@
+import type { ReactNode, CSSProperties } from "react";
+import { cn } from "../lib/cn";
+
+// Single button inside the action bar — used both for top-level
+// items and for entries inside expanded group menus.
+//
+// Three visual variants:
+//   - ghost   → default. Transparent bg, neutral text. Active
+//               state promotes to accent muted bg.
+//   - primary → solid accent fill, white text. For items whose
+//               "this mode is on" signal should beat the "this
+//               group is open" signal (e.g. an editing-mode toggle
+//               nested in a Manage group, while Manage is open).
+//   - soft    → transparent bg, accent-coloured text. Used for
+//               open group HEADS where the wrapper supplies a
+//               muted-accent bg; the head just needs the
+//               foreground to read as accent.
+
+// Optional props use `| undefined` (rather than bare `T?`) so that callers
+// can forward potentially-undefined values from upstream optional sources
+// (e.g. `ActionBarItem.active`, which is itself optional). Compatible with
+// `exactOptionalPropertyTypes: true` consumers.
+export interface ActionBarButtonProps {
+  icon?: ReactNode | undefined;
+  label: string;
+  onClick: () => void;
+  active?: boolean | undefined;
+  title?: string | undefined;
+  variant?: "ghost" | "primary" | "soft" | undefined;
+  disabled?: boolean | undefined;
+  hint?: string | undefined;
+  // Optional chevron — used by group heads to signal disclosure.
+  chevron?: "right" | undefined;
+  // 180° rotation when true (▸ becomes ◂ — reads as "close").
+  chevronRotated?: boolean | undefined;
+  // Hide label below md viewport (768 px). Default true.
+  responsiveLabel?: boolean | undefined;
+  style?: CSSProperties | undefined;
+}
+
+export function ActionBarButton({
+  icon,
+  label,
+  onClick,
+  active,
+  title,
+  variant = "ghost",
+  disabled,
+  hint,
+  chevron,
+  chevronRotated,
+  responsiveLabel = true,
+  style,
+}: ActionBarButtonProps) {
+  const isPrimary = active || variant === "primary";
+  const isSoft = !isPrimary && variant === "soft";
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      title={title ?? label}
+      className={cn(
+        "ck-actionbar-btn",
+        isPrimary && "ck-actionbar-btn--primary",
+        !isPrimary && "ck-actionbar-btn--ghost",
+      )}
+      style={{
+        ...(isSoft ? { color: "var(--ck-accent)" } : undefined),
+        ...style,
+      }}
+    >
+      {icon}
+      <span className={responsiveLabel ? "ck-actionbar-label" : undefined}>
+        {label}
+      </span>
+      {hint && (
+        <span
+          style={{
+            color: isPrimary ? "rgba(255,255,255,0.7)" : "var(--ck-text-tertiary)",
+            font: "500 11px/1 var(--ck-font-mono)",
+            marginLeft: 4,
+          }}
+        >
+          {hint}
+        </span>
+      )}
+      {chevron && (
+        <svg
+          width="10"
+          height="10"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2.2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          style={{
+            flexShrink: 0,
+            opacity: 0.7,
+            transform: chevronRotated ? "rotate(180deg)" : "rotate(0deg)",
+            transition: "transform 220ms cubic-bezier(0.4, 0, 0.2, 1)",
+          }}
+        >
+          <polyline points="9 6 15 12 9 18" />
+        </svg>
+      )}
+    </button>
+  );
+}

package/src/actionbar/ActionBarMenuGroup.tsx

@@ -0,0 +1,106 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { ActionBarButton } from "./ActionBarButton";
+import type { ActionBarItem } from "./types";
+
+// Inline-expandable group inside the action bar. Head button +
+// disclosure region of child items. When open:
+//   - head gets a "soft" foreground (or "primary" if a child is
+//     active), wrapped in a muted-accent pill that extends across
+//     the children too
+//   - children animate in via max-width + opacity transition
+//     (no mount/unmount so the open/close has motion)
+//   - ESC + outside-click both close
+
+export interface ActionBarMenuGroupProps {
+  label: string;
+  icon?: ReactNode;
+  hasActiveChild: boolean;
+  isOpen: boolean;
+  onToggle: () => void;
+  items: ActionBarItem[];
+  onItemClicked: (item: ActionBarItem) => void;
+}
+
+export function ActionBarMenuGroup({
+  label,
+  icon,
+  hasActiveChild,
+  isOpen,
+  onToggle,
+  items,
+  onItemClicked,
+}: ActionBarMenuGroupProps) {
+  const headVariant: "ghost" | "primary" | "soft" = hasActiveChild
+    ? "primary"
+    : isOpen
+      ? "soft"
+      : "ghost";
+
+  // Outside-click closes the group via a capture-phase listener so
+  // the menu dismisses before the click reaches any other handler.
+  const wrapperRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!isOpen) return;
+    const onMouseDown = (e: MouseEvent) => {
+      if (!wrapperRef.current) return;
+      if (wrapperRef.current.contains(e.target as Node)) return;
+      onToggle();
+    };
+    document.addEventListener("mousedown", onMouseDown, true);
+    return () => document.removeEventListener("mousedown", onMouseDown, true);
+  }, [isOpen, onToggle]);
+
+  return (
+    <div
+      ref={wrapperRef}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        background: isOpen ? "var(--ck-accent-muted)" : "transparent",
+        borderRadius: 999,
+        transition: "background 200ms ease",
+      }}
+    >
+      <ActionBarButton
+        icon={icon}
+        label={label}
+        title={isOpen ? `Close ${label}` : label}
+        variant={headVariant}
+        chevron="right"
+        chevronRotated={isOpen}
+        onClick={onToggle}
+      />
+      <div
+        aria-hidden={!isOpen}
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 6,
+          overflow: "hidden",
+          maxWidth: isOpen ? 1000 : 0,
+          opacity: isOpen ? 1 : 0,
+          marginLeft: isOpen ? 0 : -6,
+          paddingRight: isOpen ? 4 : 0,
+          pointerEvents: isOpen ? "auto" : "none",
+          transition:
+            "max-width 240ms cubic-bezier(0.4, 0, 0.2, 1), opacity 180ms ease, margin-left 240ms cubic-bezier(0.4, 0, 0.2, 1), padding-right 240ms cubic-bezier(0.4, 0, 0.2, 1)",
+        }}
+      >
+        {items.map((it) => (
+          <ActionBarButton
+            key={it.key}
+            icon={it.icon}
+            label={it.label}
+            title={it.title}
+            active={it.active}
+            disabled={it.disabled || !isOpen}
+            variant={it.variant}
+            hint={it.hint}
+            onClick={() => onItemClicked(it)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}