@cosxai/ui 0.1.0

package/src/layout/MobileTabBar.tsx

@@ -0,0 +1,101 @@
+import { useEffect, type ReactNode, type CSSProperties } from "react";
+
+// Fixed-bottom tab bar for phones. Sits above the home-indicator
+// safe area on iOS, exposes --ck-tabbar-height so the GlobalActionBar
+// and any sticky bottom UI can lift to clear it.
+//
+// Tab list is fully configurable — caller supplies items with an
+// active match function so the bar can highlight the right one for
+// the current pathname. No router coupling.
+
+export interface MobileTab {
+  key: string;
+  label: string;
+  icon: ReactNode;
+  // Called when the tab is tapped. Caller handles navigation.
+  onSelect: () => void;
+  // Whether this tab represents the current route. Caller derives
+  // from their router (e.g. `pathname.startsWith("/shares")`).
+  active: boolean;
+}
+
+export interface MobileTabBarProps {
+  tabs: MobileTab[];
+  // Height of the bar (content area; safe-area inset added on top).
+  // Default 56 px.
+  height?: number;
+  className?: string;
+}
+
+export function MobileTabBar({
+  tabs,
+  height = 56,
+  className,
+}: MobileTabBarProps) {
+  // Stamp --ck-tabbar-height. Includes safe-area inset so consumers
+  // (e.g. floating action bar) can lift cleanly above the home
+  // indicator. iOS env() works in calc() inside :root vars.
+  useEffect(() => {
+    document.documentElement.style.setProperty(
+      "--ck-tabbar-height",
+      `calc(${height}px + env(safe-area-inset-bottom, 0px))`,
+    );
+    return () => {
+      document.documentElement.style.setProperty("--ck-tabbar-height", "0px");
+    };
+  }, [height]);
+
+  return (
+    <nav
+      data-ck-tabbar
+      aria-label="Primary"
+      className={className}
+      style={
+        {
+          position: "fixed",
+          left: 0,
+          right: 0,
+          bottom: 0,
+          height: "var(--ck-tabbar-height)",
+          paddingBottom: "env(safe-area-inset-bottom, 0px)",
+          background: "var(--ck-bg-surface)",
+          borderTop: "1px solid var(--ck-border-subtle)",
+          display: "flex",
+          justifyContent: "space-around",
+          alignItems: "stretch",
+          zIndex: 50,
+          fontFamily: "var(--ck-font-sans)",
+        } as CSSProperties
+      }
+    >
+      {tabs.map((t) => (
+        <button
+          key={t.key}
+          type="button"
+          onClick={t.onSelect}
+          aria-current={t.active ? "page" : undefined}
+          style={{
+            flex: 1,
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "center",
+            gap: 2,
+            padding: "6px 8px",
+            border: "none",
+            background: "transparent",
+            color: t.active ? "var(--ck-accent)" : "var(--ck-text-tertiary)",
+            cursor: "pointer",
+            font: "500 11px/1 var(--ck-font-sans)",
+            transition: "color var(--ck-dur-fast) var(--ck-ease)",
+          }}
+        >
+          <span style={{ fontSize: 18, lineHeight: 1, display: "inline-flex" }}>
+            {t.icon}
+          </span>
+          <span>{t.label}</span>
+        </button>
+      ))}
+    </nav>
+  );
+}

package/src/layout/NavItem.tsx

@@ -0,0 +1,128 @@
+import type { ReactNode, CSSProperties } from "react";
+import { CountBadge } from "../primitives/CountBadge";
+
+// Single nav row inside <LeftNavRail>. Router-agnostic — pass your
+// own router's link primitive via the `as` prop, or fall back to a
+// plain anchor. Collapsed mode renders icon-only with the label as
+// a tooltip.
+//
+// Use with NavLink-style render-prop routers by wrapping NavItem
+// with your router's link and forwarding `active`:
+//
+//   <NavLink to="/x">
+//     {({ isActive }) =>
+//       <NavItem active={isActive} icon={<X/>} label="X" />
+//     }
+//   </NavLink>
+
+export interface NavItemProps {
+  // Visible label (also used as tooltip when collapsed).
+  label: string;
+  icon: ReactNode;
+  active?: boolean;
+  // Optional notification count badge — renders nothing for 0.
+  badge?: number;
+  collapsed?: boolean;
+  onClick?: () => void;
+  // Render as an anchor with this href. When omitted, renders as
+  // a button (use onClick).
+  href?: string;
+  // Optional custom render — escape hatch for router-link wrappers
+  // that need to spread their own props on the element. Receives
+  // the rendered children + the inline style.
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function NavItem({
+  label,
+  icon,
+  active,
+  badge,
+  collapsed,
+  onClick,
+  href,
+  className,
+  style,
+}: NavItemProps) {
+  const showBadge = badge !== undefined && badge > 0;
+  const baseStyle: CSSProperties = {
+    position: "relative",
+    display: "flex",
+    alignItems: "center",
+    borderRadius: "var(--ck-radius-md)",
+    transition: "background var(--ck-dur-fast) var(--ck-ease), color var(--ck-dur-fast) var(--ck-ease)",
+    background: active ? "var(--ck-accent-muted)" : "transparent",
+    color: active ? "var(--ck-accent)" : "var(--ck-text-secondary)",
+    font: "400 13px/1 var(--ck-font-sans)",
+    fontWeight: active ? 500 : 400,
+    cursor: "pointer",
+    textDecoration: "none",
+    border: "none",
+    ...(collapsed
+      ? {
+          justifyContent: "center",
+          width: 40,
+          height: 40,
+        }
+      : {
+          justifyContent: "space-between",
+          padding: "8px 12px",
+        }),
+    ...style,
+  };
+
+  const content = collapsed ? (
+    <>
+      <span style={{ display: "inline-flex" }}>{icon}</span>
+      {showBadge && (
+        <span style={{ position: "absolute", top: 2, right: 2 }}>
+          <CountBadge count={badge} size="sm" tone="critical" />
+        </span>
+      )}
+    </>
+  ) : (
+    <>
+      <span style={{ display: "inline-flex", alignItems: "center", gap: 10 }}>
+        {icon}
+        <span>{label}</span>
+      </span>
+      {showBadge && <CountBadge count={badge} size="sm" tone="critical" />}
+    </>
+  );
+
+  // data-ck-navitem + data-active are escape hatches for chrome
+  // CSS to override the inline visual state (e.g. neobrutalism
+  // wants a fully different chunky look on the active item).
+  const dataAttrs = {
+    "data-ck-navitem": "",
+    "data-active": active ? "true" : undefined,
+  };
+
+  if (href !== undefined) {
+    return (
+      <a
+        href={href}
+        title={collapsed ? label : undefined}
+        className={className}
+        style={baseStyle}
+        {...dataAttrs}
+      >
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      title={collapsed ? label : undefined}
+      className={className}
+      style={baseStyle}
+      {...dataAttrs}
+    >
+      {content}
+    </button>
+  );
+}

package/src/layout/NavSearchTrigger.tsx

@@ -0,0 +1,88 @@
+import { Kbd } from "../primitives/Kbd";
+
+// Search-style command-palette opener for the left rail. Wide
+// click target, search icon on the left, kbd hint on the right.
+// Hidden in collapsed mode — the palette is still reachable via
+// ⌘K, no need for a dedicated trigger when there's no label space.
+
+export interface NavSearchTriggerProps {
+  onClick: () => void;
+  placeholder?: string;
+  hotkey?: string;
+  collapsed?: boolean;
+}
+
+export function NavSearchTrigger({
+  onClick,
+  placeholder = "Search",
+  hotkey = "K",
+  collapsed,
+}: NavSearchTriggerProps) {
+  if (collapsed) return null;
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label="Open command palette"
+      title="Open command palette"
+      data-ck-search-trigger
+      style={{
+        position: "relative",
+        width: "100%",
+        height: 34,
+        padding: "0 8px 0 32px",
+        background: "var(--ck-bg-muted)",
+        border: "1px solid transparent",
+        borderRadius: "var(--ck-radius-sm)",
+        cursor: "pointer",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        textAlign: "left",
+        transition: "background var(--ck-dur-fast) var(--ck-ease), border-color var(--ck-dur-fast) var(--ck-ease)",
+      }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.borderColor = "var(--ck-border-strong)";
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.borderColor = "transparent";
+      }}
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        style={{
+          position: "absolute",
+          left: 10,
+          top: "50%",
+          transform: "translateY(-50%)",
+          color: "var(--ck-text-tertiary)",
+          pointerEvents: "none",
+        }}
+        aria-hidden
+      >
+        <circle cx="11" cy="11" r="7" />
+        <line x1="21" y1="21" x2="16.65" y2="16.65" />
+      </svg>
+      <span
+        style={{
+          flex: 1,
+          font: "400 12px/1 var(--ck-font-sans)",
+          color: "var(--ck-text-tertiary)",
+        }}
+      >
+        {placeholder}
+      </span>
+      <span style={{ display: "inline-flex", gap: 2 }}>
+        <Kbd>Mod</Kbd>
+        <Kbd>{hotkey}</Kbd>
+      </span>
+    </button>
+  );
+}

package/src/layout/NavSection.tsx

@@ -0,0 +1,40 @@
+import type { ReactNode } from "react";
+
+// Section header inside <LeftNavRail>. Mono uppercase eyebrow above
+// a group of <NavItem>s. Hides its own label in collapsed mode —
+// icons are self-explanatory at 56 px and the cluster delimiters
+// become visual noise.
+
+export interface NavSectionProps {
+  label: string;
+  collapsed?: boolean;
+  children: ReactNode;
+}
+
+export function NavSection({ label, collapsed, children }: NavSectionProps) {
+  return (
+    <div style={{ marginBottom: 16 }}>
+      {!collapsed && (
+        <div
+          className="ck-tag"
+          style={{
+            padding: "0 12px",
+            marginBottom: 6,
+          }}
+        >
+          {label}
+        </div>
+      )}
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: collapsed ? 4 : 1,
+          alignItems: collapsed ? "center" : "stretch",
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/layout/RightSidebarPanel.tsx

@@ -0,0 +1,111 @@
+import type { ReactNode, CSSProperties } from "react";
+
+// Floating right-side panel. Used for ephemeral side surfaces —
+// comments, signing management, review-link list, etc. Unlike the
+// always-on AgentRail-style right rail, this is summoned by user
+// action and dismissed via the close button or Esc.
+//
+// Sticks below the topbar (reads --ck-breadcrumb-height), max-height
+// leaves room for any bottom-fixed UI (--ck-tabbar-height).
+// Caller owns the open/close state.
+
+export interface RightSidebarPanelProps {
+  open: boolean;
+  onClose: () => void;
+  // Required — small uppercase eyebrow above the title slot.
+  eyebrow: string;
+  title?: ReactNode;
+  // Right-side header slot (e.g. filter dropdown). Sits beside the
+  // close button.
+  headerExtras?: ReactNode;
+  children: ReactNode;
+  // px. Default 320.
+  width?: number;
+  // px offset from viewport edges. Default 12.
+  edgeOffset?: number;
+  className?: string;
+}
+
+export function RightSidebarPanel({
+  open,
+  onClose,
+  eyebrow,
+  title,
+  headerExtras,
+  children,
+  width = 320,
+  edgeOffset = 12,
+  className,
+}: RightSidebarPanelProps) {
+  if (!open) return null;
+  const topOffset = `calc(var(--ck-breadcrumb-height, 64px) + ${edgeOffset}px)`;
+  const bottomOffset = `calc(var(--ck-tabbar-height, 0px) + ${edgeOffset}px)`;
+  return (
+    <aside
+      role="complementary"
+      className={className}
+      style={
+        {
+          position: "fixed",
+          top: topOffset,
+          right: edgeOffset,
+          width,
+          maxHeight: `calc(100vh - ${topOffset} - ${bottomOffset})`,
+          background: "var(--ck-bg-surface)",
+          border: "1px solid var(--ck-border-subtle)",
+          borderRadius: "var(--ck-radius-md)",
+          boxShadow: "var(--ck-shadow-2)",
+          display: "flex",
+          flexDirection: "column",
+          zIndex: 60,
+          fontFamily: "var(--ck-font-sans)",
+        } as CSSProperties
+      }
+    >
+      <div
+        style={{
+          padding: "14px 16px",
+          borderBottom: "1px solid var(--ck-border-subtle)",
+          display: "flex",
+          alignItems: "flex-start",
+          gap: 8,
+        }}
+      >
+        <div style={{ flex: 1, minWidth: 0 }}>
+          <div className="ck-eyebrow" style={{ marginBottom: title ? 4 : 0 }}>
+            {eyebrow}
+          </div>
+          {title && (
+            <div
+              style={{
+                font: "500 14px/1.3 var(--ck-font-sans)",
+                color: "var(--ck-text-primary)",
+              }}
+            >
+              {title}
+            </div>
+          )}
+        </div>
+        {headerExtras}
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close"
+          style={{
+            border: "none",
+            background: "transparent",
+            color: "var(--ck-text-tertiary)",
+            cursor: "pointer",
+            fontSize: 18,
+            lineHeight: 1,
+            padding: 2,
+            marginLeft: 4,
+          }}
+        >
+          ×
+        </button>
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflowY: "auto" }}>{children}</div>
+    </aside>
+  );
+}

package/src/layout/Shell.tsx

@@ -0,0 +1,91 @@
+import type { ReactNode, CSSProperties } from "react";
+
+// Layout shell. The kit is unopinionated about WHICH navigation
+// primitives sit in each slot — pass <LeftNavRail>, <Topbar>,
+// <MobileTabBar> etc. (or your own equivalents) and Shell composes
+// them into the standard layout:
+//
+//   ┌──────────────────────────────────────────┐
+//   │ topbar (full width, fixed)               │
+//   ├────────┬─────────────────────────┬───────┤
+//   │        │                         │       │
+//   │  left  │ main (children)         │ right │
+//   │   nav  │                         │  rail │
+//   │  (fix) │ insets via CSS vars     │ (fix) │
+//   │        │                         │       │
+//   └────────┴─────────────────────────┴───────┘
+//
+// All three rails are position:fixed and stamp their widths/heights
+// as CSS vars (--ck-leftnav-width, --ck-rightrail-width,
+// --ck-tabbar-height). Shell reads those vars to inset the main
+// region. No prop drilling.
+
+export interface ShellProps {
+  // Drop <LeftNavRail> here. Shell renders it as-is; the rail itself
+  // handles fixed positioning.
+  leftRail?: ReactNode;
+  // <Topbar>. Sticky at the top of the main column.
+  topbar?: ReactNode;
+  // Page body.
+  children: ReactNode;
+  // Right rail (e.g. agent panel, comments panel) — rendered as-is.
+  rightRail?: ReactNode;
+  // Mobile bottom tab bar — rendered as-is.
+  tabBar?: ReactNode;
+  // Inline style overrides for the main region (useful for setting
+  // background per route).
+  mainStyle?: CSSProperties;
+  className?: string;
+}
+
+export function Shell({
+  leftRail,
+  topbar,
+  children,
+  rightRail,
+  tabBar,
+  mainStyle,
+  className,
+}: ShellProps) {
+  return (
+    <div
+      data-ck-shell
+      className={className}
+      style={{
+        minHeight: "100vh",
+        background: "var(--ck-bg-canvas)",
+        color: "var(--ck-text-primary)",
+      }}
+    >
+      {leftRail}
+      {rightRail}
+      {tabBar}
+      <div
+        style={
+          {
+            marginLeft: "var(--ck-leftnav-width, 0px)",
+            marginRight: "var(--ck-rightrail-width, 0px)",
+            paddingBottom: "var(--ck-tabbar-height, 0px)",
+            minHeight: "100vh",
+            display: "flex",
+            flexDirection: "column",
+            transition: "margin var(--ck-dur-fast) var(--ck-ease)",
+          } as CSSProperties
+        }
+      >
+        {topbar && (
+          <div
+            style={{
+              position: "sticky",
+              top: 0,
+              zIndex: 20,
+            }}
+          >
+            {topbar}
+          </div>
+        )}
+        <main style={{ flex: 1, minHeight: 0, ...mainStyle }}>{children}</main>
+      </div>
+    </div>
+  );
+}

package/src/layout/StickyBanner.tsx

@@ -0,0 +1,83 @@
+import type { ReactNode, CSSProperties } from "react";
+
+// Eyebrow + title + optional right-slot, sticky at top of a page
+// region (NOT the topbar — this is for an in-page sticky like
+// "Reviewing as <name>" or "Document signed · view audit log").
+// Caller controls when it shows. Visual mass matches a topbar
+// (64 px) so it can sit directly underneath one cleanly.
+
+export interface StickyBannerProps {
+  eyebrow?: string;
+  title: ReactNode;
+  // Right-aligned action cluster.
+  actions?: ReactNode;
+  // Sticky top offset in px. Default 64 (below topbar).
+  topOffset?: number;
+  height?: number;
+  className?: string;
+  // Visual tone — adjusts background. Default 'info'.
+  tone?: "info" | "warning" | "success" | "critical";
+}
+
+const TONE_BG: Record<NonNullable<StickyBannerProps["tone"]>, string> = {
+  info: "var(--ck-info-muted)",
+  warning: "var(--ck-warning-muted)",
+  success: "var(--ck-success-muted)",
+  critical: "var(--ck-critical-muted)",
+};
+const TONE_BORDER: Record<NonNullable<StickyBannerProps["tone"]>, string> = {
+  info: "var(--ck-accent-border)",
+  warning: "var(--ck-warning)",
+  success: "var(--ck-success)",
+  critical: "var(--ck-critical)",
+};
+
+export function StickyBanner({
+  eyebrow,
+  title,
+  actions,
+  topOffset = 64,
+  height = 64,
+  className,
+  tone = "info",
+}: StickyBannerProps) {
+  return (
+    <div
+      className={className}
+      style={
+        {
+          position: "sticky",
+          top: topOffset,
+          height,
+          padding: "0 24px",
+          display: "flex",
+          alignItems: "center",
+          gap: 16,
+          background: TONE_BG[tone],
+          borderBottom: `1px solid ${TONE_BORDER[tone]}`,
+          zIndex: 10,
+          fontFamily: "var(--ck-font-sans)",
+        } as CSSProperties
+      }
+    >
+      <div style={{ flex: 1, minWidth: 0 }}>
+        {eyebrow && (
+          <div className="ck-eyebrow" style={{ marginBottom: 2 }}>
+            {eyebrow}
+          </div>
+        )}
+        <div
+          style={{
+            font: "500 14px/1.3 var(--ck-font-sans)",
+            color: "var(--ck-text-primary)",
+          }}
+        >
+          {title}
+        </div>
+      </div>
+      {actions && (
+        <div style={{ display: "flex", gap: 8, flex: "none" }}>{actions}</div>
+      )}
+    </div>
+  );
+}