@cosxai/ui 0.1.0

package/src/layout/Topbar.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from "react";
+
+// Top chrome strip. Three slots — left (crumbs / brand / back arrow),
+// center (page-specific affordance like a tab switcher), right
+// (actions). Height is exposed as --ck-breadcrumb-height (default
+// 64 px) so the right-side panel, command palette, and other fixed-
+// position UI can offset themselves correctly.
+
+export interface TopbarProps {
+  // Usually <Breadcrumb /> on desktop, page title on mobile.
+  left?: ReactNode;
+  // Optional centred slot. Hidden if not supplied.
+  center?: ReactNode;
+  // Right cluster — theme toggle, profile chip, etc.
+  right?: ReactNode;
+  // Height in px. Default 64. Stamps --ck-breadcrumb-height so
+  // sticky elements below can align.
+  height?: number;
+  className?: string;
+}
+
+export function Topbar({
+  left,
+  center,
+  right,
+  height = 64,
+  className,
+}: TopbarProps) {
+  return (
+    <header
+      data-ck-topbar
+      className={className}
+      style={
+        {
+          height,
+          padding: "0 24px",
+          display: "flex",
+          alignItems: "center",
+          gap: 16,
+          background: "var(--ck-bg-surface)",
+          borderBottom: "1px solid var(--ck-border-subtle)",
+          ["--ck-breadcrumb-height" as string]: `${height}px`,
+        } as React.CSSProperties
+      }
+    >
+      <div style={{ flex: "1 1 auto", minWidth: 0 }}>{left}</div>
+      {center && (
+        <div
+          style={{
+            position: "absolute",
+            left: "50%",
+            transform: "translateX(-50%)",
+            display: "flex",
+            alignItems: "center",
+            gap: 8,
+          }}
+        >
+          {center}
+        </div>
+      )}
+      {right && (
+        <div style={{ display: "flex", alignItems: "center", gap: 8, flex: "none" }}>
+          {right}
+        </div>
+      )}
+    </header>
+  );
+}

package/src/layout/index.ts

@@ -0,0 +1,22 @@
+export { Shell } from "./Shell";
+export type { ShellProps } from "./Shell";
+export { Topbar } from "./Topbar";
+export type { TopbarProps } from "./Topbar";
+export { Breadcrumb } from "./Breadcrumb";
+export type { BreadcrumbProps, CrumbItem } from "./Breadcrumb";
+export { LeftNavRail } from "./LeftNavRail";
+export type { LeftNavRailProps } from "./LeftNavRail";
+export { useNavRailState } from "./useNavRailState";
+export type { NavRailState, UseNavRailStateOpts } from "./useNavRailState";
+export { MobileTabBar } from "./MobileTabBar";
+export type { MobileTabBarProps, MobileTab } from "./MobileTabBar";
+export { RightSidebarPanel } from "./RightSidebarPanel";
+export type { RightSidebarPanelProps } from "./RightSidebarPanel";
+export { StickyBanner } from "./StickyBanner";
+export type { StickyBannerProps } from "./StickyBanner";
+export { NavSection } from "./NavSection";
+export type { NavSectionProps } from "./NavSection";
+export { NavItem } from "./NavItem";
+export type { NavItemProps } from "./NavItem";
+export { NavSearchTrigger } from "./NavSearchTrigger";
+export type { NavSearchTriggerProps } from "./NavSearchTrigger";

package/src/layout/useNavRailState.ts

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useState } from "react";
+import { useViewport } from "../hooks/useViewport";
+
+// Manages the collapse state of <LeftNavRail>. Two layers:
+//
+//   1. User preference — persisted in localStorage under
+//      `storageKey`. The user toggles via a button in the rail.
+//   2. Viewport rule — below `forceCollapseBelow` the rail is
+//      always collapsed regardless of user preference.
+//
+// The hook returns the EFFECTIVE collapsed state (combining the
+// two) plus a setter that only mutates the user preference (the
+// viewport rule continues to apply on top).
+
+export interface UseNavRailStateOpts {
+  storageKey?: string;
+  // Viewport width below which the rail force-collapses, ignoring
+  // user preference. Default 1100 px.
+  forceCollapseBelow?: number;
+  // Initial preference if nothing is in localStorage. Default false
+  // (expanded).
+  defaultCollapsed?: boolean;
+}
+
+export interface NavRailState {
+  collapsed: boolean;
+  // The viewport is currently overriding the user preference.
+  // Toggle button should be disabled when this is true.
+  forcedByViewport: boolean;
+  toggle: () => void;
+  setCollapsed: (next: boolean) => void;
+}
+
+const DEFAULT_KEY = "ck-leftnav-collapsed";
+
+export function useNavRailState({
+  storageKey = DEFAULT_KEY,
+  forceCollapseBelow = 1100,
+  defaultCollapsed = false,
+}: UseNavRailStateOpts = {}): NavRailState {
+  const [userPref, setUserPref] = useState<boolean>(() => {
+    if (typeof window === "undefined") return defaultCollapsed;
+    const stored = window.localStorage.getItem(storageKey);
+    if (stored === "1") return true;
+    if (stored === "0") return false;
+    return defaultCollapsed;
+  });
+  const vp = useViewport({ narrow: forceCollapseBelow });
+  const forcedByViewport = vp.isNarrow;
+  const collapsed = forcedByViewport || userPref;
+
+  const setCollapsed = useCallback(
+    (next: boolean) => {
+      setUserPref(next);
+    },
+    [],
+  );
+
+  useEffect(() => {
+    window.localStorage.setItem(storageKey, userPref ? "1" : "0");
+  }, [userPref, storageKey]);
+
+  const toggle = useCallback(() => {
+    if (forcedByViewport) return; // no-op — viewport rules
+    setUserPref((v) => !v);
+  }, [forcedByViewport]);
+
+  return { collapsed, forcedByViewport, toggle, setCollapsed };
+}

package/src/lib/cn.ts

@@ -0,0 +1,7 @@
+// Lightweight className merge. Filters falsy values and joins with a
+// single space. Sufficient for component composition; if a consumer
+// needs tailwind-merge / clsx semantics they can swap implementations
+// without touching call sites.
+export function cn(...inputs: Array<string | false | null | undefined>): string {
+  return inputs.filter(Boolean).join(" ");
+}

package/src/lib/time-utils.ts

@@ -0,0 +1,44 @@
+// Time formatting helpers.
+
+// "3m ago" / "2h ago" / "5d ago", falls back to a locale date past
+// 30 days. Use for activity rows, comment timestamps, anywhere a
+// short relative cue beats a full timestamp.
+export function relativeTime(ts: number): string {
+  const diff = Date.now() - ts;
+  const sec = Math.round(diff / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.round(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.round(hr / 24);
+  if (day < 30) return `${day}d ago`;
+  return new Date(ts).toLocaleDateString();
+}
+
+// Null-safe locale date formatter — accepts ms timestamps, ISO
+// strings, null, undefined, or non-finite values. Empty inputs
+// render as an em-dash placeholder ("—"), which most list rows
+// were doing inline with a ternary before.
+export function formatDate(ms: number | string | null | undefined): string {
+  const n = coerceMs(ms);
+  if (n === null) return "—";
+  return new Date(n).toLocaleDateString();
+}
+
+// Full date + time formatter with the same null-safe semantics.
+export function formatTimestamp(
+  ms: number | string | null | undefined,
+  opts?: Intl.DateTimeFormatOptions,
+): string {
+  const n = coerceMs(ms);
+  if (n === null) return "—";
+  return opts ? new Date(n).toLocaleString(undefined, opts) : new Date(n).toLocaleString();
+}
+
+function coerceMs(ms: number | string | null | undefined): number | null {
+  if (ms == null) return null;
+  const n = typeof ms === "string" ? Number(ms) : ms;
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n;
+}

package/src/neobrutalism/Marquee.tsx

@@ -0,0 +1,81 @@
+import type { CSSProperties } from "react";
+
+// Looping marquee strip — the signature neobrutalism section
+// divider. "NEOBRUTALISM · NEOBRUTALISM · NEOBRUTALISM…" in
+// chunky 800-weight type, scrolling horizontally. Decoration,
+// not nav.
+//
+// Pure CSS animation — no rAF loops, no JS. The repeated text
+// inside is doubled so when the first set scrolls past the edge,
+// the second is already in position to seamlessly continue.
+
+export interface MarqueeProps {
+  text: string;
+  // Pixels per second. Default 60 — comfortable reading speed.
+  speed?: number;
+  // Visual variant. "default" = accent background; "inverted" =
+  // pure black background with white text.
+  variant?: "default" | "inverted";
+  // px height. Default 56.
+  height?: number;
+  // Slight skew angle (deg). Default 0; try -2 for a punk feel.
+  skew?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Marquee({
+  text,
+  speed = 60,
+  variant = "default",
+  height = 56,
+  skew = 0,
+  className,
+  style,
+}: MarqueeProps) {
+  // Each phrase is ~80 px wide for a typical 20-char fragment;
+  // 10 copies gives ~800 px content — wide enough that the loop
+  // is always seamless on any viewport. Real measurement happens
+  // visually; for now the count + duration combo just need to be
+  // multiples that produce a continuous loop.
+  const phrases = new Array(10).fill(text).join("  •  ");
+  const duration = `${(phrases.length * 8) / speed}s`;
+
+  return (
+    <div
+      className={className}
+      style={{
+        overflow: "hidden",
+        height,
+        background:
+          variant === "inverted" ? "#000000" : "var(--ck-accent, #88AAEE)",
+        color: variant === "inverted" ? "#FFFFFF" : "#000000",
+        border: "2px solid var(--neobrut-ink, #000)",
+        borderRadius: 4,
+        transform: skew ? `skewY(${skew}deg)` : undefined,
+        position: "relative",
+        ...style,
+      }}
+    >
+      <div
+        style={{
+          position: "absolute",
+          inset: 0,
+          display: "flex",
+          alignItems: "center",
+          gap: 40,
+          whiteSpace: "nowrap",
+          font: "800 22px/1 var(--ck-font-display, var(--ck-font-sans))",
+          letterSpacing: "0.04em",
+          animation: `ck-neobrut-marquee ${duration} linear infinite`,
+          willChange: "transform",
+        }}
+      >
+        {/* Doubled for seamless loop. CSS animation translates by
+            -50% so the second copy moves into the first's position. */}
+        <span>{phrases}</span>
+        <span aria-hidden>{phrases}</span>
+      </div>
+    </div>
+  );
+}

package/src/neobrutalism/Sticker.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode, CSSProperties } from "react";
+
+// Rotated badge — "NEW!", "FREE!", "v2.0!" style. Sits in the
+// corner of featured cards or banners. Filled with an accent
+// colour, thick border, hard shadow, slight tilt to read as a
+// physical sticker pinned on the page.
+
+export interface StickerProps {
+  children: ReactNode;
+  // Tilt angle in degrees. Default -8 (slight left lean —
+  // pleasing eye-tilt without going crazy).
+  rotate?: number;
+  // Fill tone. "accent" / "warning" / "success" / "critical"
+  // pick from token palette; pass a hex string to override.
+  tone?: "accent" | "warning" | "success" | "critical" | string;
+  // px diameter — sticker is square so width == height.
+  size?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+function toneToBg(tone: NonNullable<StickerProps["tone"]>) {
+  switch (tone) {
+    case "accent":
+      return "var(--ck-accent, #88AAEE)";
+    case "warning":
+      return "var(--ck-warning, #FFD23F)";
+    case "success":
+      return "var(--ck-success, #A3E636)";
+    case "critical":
+      return "var(--ck-critical, #FF6B6B)";
+    default:
+      return tone;
+  }
+}
+
+export function Sticker({
+  children,
+  rotate = -8,
+  tone = "warning",
+  size = 80,
+  className,
+  style,
+}: StickerProps) {
+  return (
+    <span
+      className={className}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        textAlign: "center",
+        width: size,
+        height: size,
+        padding: 6,
+        background: toneToBg(tone),
+        color: "#000",
+        border: "2px solid var(--neobrut-ink, #000)",
+        borderRadius: "50%",
+        boxShadow: "3px 3px 0 0 var(--neobrut-ink, #000)",
+        transform: `rotate(${rotate}deg)`,
+        font: "800 14px/1.1 var(--ck-font-display, var(--ck-font-sans))",
+        letterSpacing: "0.02em",
+        textTransform: "uppercase",
+        ...style,
+      }}
+    >
+      {children}
+    </span>
+  );
+}

package/src/neobrutalism/index.ts

@@ -0,0 +1,4 @@
+export { Marquee } from "./Marquee";
+export type { MarqueeProps } from "./Marquee";
+export { Sticker } from "./Sticker";
+export type { StickerProps } from "./Sticker";

package/src/primitives/Avatar.tsx

@@ -0,0 +1,53 @@
+import { cn } from "../lib/cn";
+
+// Circular avatar — image with initials fallback. Use the `name`
+// prop to derive initials (first letter of first two whitespace-
+// separated tokens). Size scales the whole thing including font.
+
+export interface AvatarProps {
+  // Display name — used for initials fallback and as alt text.
+  name: string;
+  // Image src. If omitted or fails to load, falls back to initials.
+  src?: string | null;
+  size?: number; // px, default 32
+  className?: string;
+}
+
+function initials(name: string): string {
+  const parts = name.trim().split(/\s+/).slice(0, 2);
+  return parts.map((p) => p[0]?.toUpperCase() ?? "").join("") || "?";
+}
+
+export function Avatar({ name, src, size = 32, className }: AvatarProps) {
+  return (
+    <span
+      className={cn("ck-avatar", className)}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: size,
+        height: size,
+        borderRadius: "50%",
+        background: "var(--ck-bg-muted)",
+        color: "var(--ck-text-secondary)",
+        font: `500 ${Math.round(size * 0.4)}px/1 var(--ck-font-sans)`,
+        overflow: "hidden",
+        flexShrink: 0,
+      }}
+      aria-label={name}
+    >
+      {src ? (
+        <img
+          src={src}
+          alt={name}
+          width={size}
+          height={size}
+          style={{ width: "100%", height: "100%", objectFit: "cover" }}
+        />
+      ) : (
+        initials(name)
+      )}
+    </span>
+  );
+}

package/src/primitives/Button.tsx

@@ -0,0 +1,30 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// Minimal Phase-0 stub so the docs app has something concrete to
+// import — proves the workspace bridge + hot-reload. Phase 3
+// replaces this with the full variant + size + loading-state
+// implementation backed by the .rd-btn styles.
+
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "icon";
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  children?: ReactNode;
+}
+
+export function Button({
+  variant = "primary",
+  className,
+  children,
+  ...rest
+}: ButtonProps) {
+  return (
+    <button
+      {...rest}
+      className={cn("ck-btn", `ck-btn--${variant}`, className)}
+    >
+      {children}
+    </button>
+  );
+}

package/src/primitives/Card.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode, CSSProperties } from "react";
+import { cn } from "../lib/cn";
+
+export interface CardProps {
+  // Eyebrow + title bar at the top. Pass any nodes; common pattern
+  // is <span className="ck-eyebrow">...</span> + <h3>...</h3>.
+  header?: ReactNode;
+  // Right-aligned actions next to the header (e.g. action buttons).
+  headerActions?: ReactNode;
+  // Bottom strip (typically buttons or meta info).
+  footer?: ReactNode;
+  children?: ReactNode;
+  // Disable the default body padding (when the children manage
+  // their own — e.g. a list with full-bleed rows).
+  noPad?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Card({
+  header,
+  headerActions,
+  footer,
+  children,
+  noPad,
+  className,
+  style,
+}: CardProps) {
+  return (
+    <section className={cn("ck-card", className)} style={style}>
+      {(header || headerActions) && (
+        <header className="ck-card__head">
+          <div style={{ flex: 1, minWidth: 0 }}>{header}</div>
+          {headerActions}
+        </header>
+      )}
+      <div className={noPad ? undefined : "ck-card__body"}>{children}</div>
+      {footer && <footer className="ck-card__foot">{footer}</footer>}
+    </section>
+  );
+}

package/src/primitives/Checkbox.tsx

@@ -0,0 +1,78 @@
+import { cn } from "../lib/cn";
+
+// Custom-styled checkbox — accent-bordered square that becomes filled
+// accent + white tick when checked. The native <input type="checkbox">
+// renders as a giant white card on dark backgrounds in most browsers,
+// which is exactly the bug that prompted this primitive in the parent
+// project. Use this anywhere you'd reach for a checkbox.
+
+export interface CheckboxProps {
+  checked: boolean;
+  onChange: (next: boolean) => void;
+  label?: React.ReactNode;
+  suffix?: React.ReactNode;
+  disabled?: boolean;
+  className?: string;
+}
+
+export function Checkbox({
+  checked,
+  onChange,
+  label,
+  suffix,
+  disabled,
+  className,
+}: CheckboxProps) {
+  return (
+    <label
+      className={cn("ck-checkbox", className)}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 8,
+        font: "400 13px/1 var(--ck-font-sans)",
+        color: "var(--ck-text-secondary)",
+        cursor: disabled ? "not-allowed" : "pointer",
+        opacity: disabled ? 0.5 : 1,
+        userSelect: "none",
+      }}
+    >
+      <button
+        type="button"
+        role="checkbox"
+        aria-checked={checked}
+        disabled={disabled}
+        onClick={() => !disabled && onChange(!checked)}
+        style={{
+          width: 16,
+          height: 16,
+          borderRadius: 4,
+          border: "1.5px solid var(--ck-accent)",
+          background: checked ? "var(--ck-accent)" : "transparent",
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          padding: 0,
+          cursor: disabled ? "not-allowed" : "pointer",
+          flexShrink: 0,
+        }}
+      >
+        {checked && (
+          <svg width="10" height="10" viewBox="0 0 12 12" fill="none" aria-hidden>
+            <path
+              d="M2.5 6.5L5 9L9.5 3.5"
+              stroke="#FFFFFF"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        )}
+      </button>
+      {label}
+      {suffix && (
+        <span style={{ color: "var(--ck-text-tertiary)" }}>{suffix}</span>
+      )}
+    </label>
+  );
+}

package/src/primitives/CountBadge.tsx

@@ -0,0 +1,50 @@
+import { cn } from "../lib/cn";
+
+// Small filled pill showing an integer count. Caps at 99+ to keep
+// the visual mass tight. Returns null at 0 — call sites can
+// unconditionally render it inside a label without an `if (n > 0)`.
+
+export interface CountBadgeProps {
+  count: number;
+  size?: "sm" | "md";
+  // Tone — default accent. Use "critical" for notifications.
+  tone?: "accent" | "critical" | "neutral";
+  className?: string;
+}
+
+const TONE_BG: Record<NonNullable<CountBadgeProps["tone"]>, string> = {
+  accent: "var(--ck-accent)",
+  critical: "var(--ck-critical)",
+  neutral: "var(--ck-text-tertiary)",
+};
+
+export function CountBadge({
+  count,
+  size = "md",
+  tone = "accent",
+  className,
+}: CountBadgeProps) {
+  if (count <= 0) return null;
+  const display = count > 99 ? "99+" : String(count);
+  const isSm = size === "sm";
+  return (
+    <span
+      className={cn("ck-count-badge", className)}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        minWidth: isSm ? 14 : 18,
+        height: isSm ? 14 : 18,
+        padding: "0 5px",
+        background: TONE_BG[tone],
+        color: "var(--ck-text-inverse)",
+        font: `500 ${isSm ? 10 : 11}px/1 var(--ck-font-mono)`,
+        borderRadius: 999,
+        fontVariantNumeric: "tabular-nums",
+      }}
+    >
+      {display}
+    </span>
+  );
+}