@cosxai/ui 0.1.0

package/src/actionbar/ActionBarProvider.tsx

@@ -0,0 +1,76 @@
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import { ActionBarContext } from "./actionbar-context";
+import type { ActionBarItem, ActionBarCategories } from "./types";
+
+// Provider for the action-bar registry + expansion state +
+// category catalog. Mount once near the app root, inside the
+// router so consumer hooks (useNavigate etc.) work but outside
+// any per-route boundary.
+
+export interface ActionBarProviderProps {
+  children: ReactNode;
+  // Declare the categories your app uses, keyed by category id.
+  // Items with `category: "create"` look up { label, icon } here
+  // for the group head. If you don't declare a category that an
+  // item references, that item still renders — it just falls
+  // back to its own label as the group head.
+  categories?: ActionBarCategories;
+}
+
+export function ActionBarProvider({
+  children,
+  categories = {},
+}: ActionBarProviderProps) {
+  const [sources, setSources] = useState<Record<string, ActionBarItem[]>>({});
+  const [expandedKey, setExpandedKey] = useState<string | null>(null);
+
+  const register = useCallback((sourceKey: string, items: ActionBarItem[]) => {
+    setSources((prev) => {
+      const cur = prev[sourceKey];
+      if (cur && cur.length === items.length && cur.every((it, i) => it === items[i])) {
+        return prev;
+      }
+      return { ...prev, [sourceKey]: items };
+    });
+  }, []);
+
+  const unregister = useCallback((sourceKey: string) => {
+    setSources((prev) => {
+      if (!(sourceKey in prev)) return prev;
+      const next = { ...prev };
+      delete next[sourceKey];
+      return next;
+    });
+  }, []);
+
+  // `__builtins__` pinned to front. Convention used by consumers
+  // that want a stable "Create" group regardless of which page
+  // registered first.
+  const items = useMemo(() => {
+    const all: ActionBarItem[] = [];
+    if (sources["__builtins__"]) all.push(...sources["__builtins__"]);
+    for (const [key, list] of Object.entries(sources)) {
+      if (key === "__builtins__") continue;
+      all.push(...list);
+    }
+    return all;
+  }, [sources]);
+
+  const value = useMemo(
+    () => ({
+      register,
+      unregister,
+      items,
+      categories,
+      expandedKey,
+      setExpandedKey,
+    }),
+    [register, unregister, items, categories, expandedKey],
+  );
+
+  return (
+    <ActionBarContext.Provider value={value}>
+      {children}
+    </ActionBarContext.Provider>
+  );
+}

package/src/actionbar/actionbar-context.ts

@@ -0,0 +1,23 @@
+import { createContext } from "react";
+import type { ActionBarItem, ActionBarCategories } from "./types";
+
+// Registry + expansion + category catalog. Items are pushed by
+// pages through useActionBarItems(); categories are declared at
+// the provider level (passed as a prop). expandedKey tracks which
+// group is currently open (one at a time).
+
+export interface ActionBarContextValue {
+  register: (sourceKey: string, items: ActionBarItem[]) => void;
+  unregister: (sourceKey: string) => void;
+  // Flat list assembled from all sources, with `__builtins__`
+  // pinned to the front (so consumer-declared "Create" items
+  // always land before page contributions).
+  items: ActionBarItem[];
+  // Static category catalog from the provider — `{ create: {label, icon}, ... }`.
+  categories: ActionBarCategories;
+  // Which group head is currently expanded. null = none.
+  expandedKey: string | null;
+  setExpandedKey: (key: string | null) => void;
+}
+
+export const ActionBarContext = createContext<ActionBarContextValue | null>(null);

package/src/actionbar/index.ts

@@ -0,0 +1,13 @@
+export { ActionBarProvider } from "./ActionBarProvider";
+export type { ActionBarProviderProps } from "./ActionBarProvider";
+export { ActionBar } from "./ActionBar";
+export type { ActionBarProps } from "./ActionBar";
+export { ActionBarButton } from "./ActionBarButton";
+export type { ActionBarButtonProps } from "./ActionBarButton";
+export { useActionBarItems, useActionBarItemsContext } from "./useActionBarItems";
+export type {
+  ActionBarItem,
+  ActionBarItemVariant,
+  ActionBarCategory,
+  ActionBarCategories,
+} from "./types";

package/src/actionbar/types.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "react";
+
+// Single item in the action bar. Pages register items via
+// useActionBarItems() — the bar itself reads from the registry
+// and renders them grouped by category. Categories with 2+ items
+// fold into one inline-expandable group head.
+
+export type ActionBarItemVariant = "ghost" | "primary" | "soft";
+
+export interface ActionBarItem {
+  // React key for the rendered button. Stable across rerenders.
+  key: string;
+  label: string;
+  icon?: ReactNode;
+  onClick: () => void;
+  // State indicator — active items render with the accent tone.
+  active?: boolean;
+  // Tooltip / aria-label. Falls back to label.
+  title?: string;
+  // Disable without removing.
+  disabled?: boolean;
+  // Group key — items sharing a category collapse into one
+  // expandable group head when 2+ are present. Single items
+  // render inline. Categories are declared at the provider level.
+  category?: string;
+  // Visual mode. Default ghost.
+  variant?: ActionBarItemVariant;
+  // Optional kbd hint shown beside the label (just visual — the
+  // shortcut is wired by the caller via useKeyboardHotkey).
+  hint?: string;
+  // When inside an expanded group, clicking this item normally
+  // collapses the group afterward. Set true to keep it open
+  // (e.g. for items whose post-click state changes the label
+  // and should stay visible).
+  keepGroupOpenOnClick?: boolean;
+}
+
+// Category definition — declared at the provider level. Drives
+// the group head's label + icon.
+export interface ActionBarCategory {
+  label: string;
+  icon?: ReactNode;
+}
+
+export type ActionBarCategories = Record<string, ActionBarCategory>;
+
+export interface ActionBarSource {
+  sourceKey: string;
+  items: ActionBarItem[];
+}

package/src/actionbar/useActionBarItems.ts

@@ -0,0 +1,47 @@
+import { useContext, useEffect, useMemo } from "react";
+import { ActionBarContext } from "./actionbar-context";
+import type { ActionBarItem } from "./types";
+
+// Register a set of items into the global action-bar registry.
+// Auto-unregisters on unmount + on sourceKey change.
+//
+// `items` is the live array — pass a useMemo'd array to avoid
+// re-registration thrash. The provider's register() does shallow
+// equality, so passing a NEW array with identical refs is fine,
+// but a NEW array with all-new item objects (from inline JSX
+// blocks) will re-register every render.
+//
+// **Important**: the useEffect deps below intentionally do NOT
+// include the ctx object itself — only its stable function refs
+// (register/unregister are useCallback'd in the provider).
+// Including ctx would cause an infinite render loop: register
+// mutates provider state → provider's value memo recomputes →
+// ctx ref changes → effect re-runs → cleanup unregisters →
+// state mutates again → ctx changes → loop. Manifests as the
+// main thread saturating and event clicks never reaching the
+// router. Same fix applies in useCommandSource.
+
+export function useActionBarItems(sourceKey: string, items: ActionBarItem[]) {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("useActionBarItems must be used within <ActionBarProvider>");
+  }
+  const { register, unregister } = ctx;
+  const memo = useMemo(
+    () => items,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [items.length, items.map((i) => i.key).join("|")],
+  );
+  useEffect(() => {
+    register(sourceKey, memo);
+    return () => unregister(sourceKey);
+  }, [register, unregister, sourceKey, memo]);
+}
+
+export function useActionBarItemsContext() {
+  const ctx = useContext(ActionBarContext);
+  if (!ctx) {
+    throw new Error("Action bar context not found");
+  }
+  return ctx;
+}

package/src/ambient/AmbientBackdrop.tsx

@@ -0,0 +1,74 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// Standalone ambient-mesh backdrop primitive. The ambient chrome
+// applies its mesh on `body` automatically, so consumers don't
+// usually need this. Use it when you want an ambient look INSIDE
+// a single section (a hero banner, a preview region) without
+// flipping the whole app's chrome.
+
+export interface AmbientBackdropProps {
+  children?: ReactNode;
+  // Use light variant tints instead of dark. Default auto-detects
+  // via prefers-color-scheme.
+  variant?: "dark" | "light";
+  // Hide the noise overlay. Default false.
+  noise?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const DARK_BG = `
+  radial-gradient(ellipse at 18% 22%, #3A2A66 0%, transparent 55%),
+  radial-gradient(ellipse at 82% 70%, #2A1E50 0%, transparent 52%),
+  radial-gradient(ellipse at 50% 110%, #4A2870 0%, transparent 50%),
+  #1A1525
+`;
+
+const LIGHT_BG = `
+  radial-gradient(ellipse at 20% 24%, #FCEFE5 0%, transparent 55%),
+  radial-gradient(ellipse at 78% 70%, #EFEAF8 0%, transparent 52%),
+  radial-gradient(ellipse at 50% 110%, #FFE8DC 0%, transparent 50%),
+  #F6F4F0
+`;
+
+export function AmbientBackdrop({
+  children,
+  variant,
+  noise,
+  className,
+  style,
+}: AmbientBackdropProps) {
+  // Auto-pick from prefers-color-scheme when not explicit. SSR-
+  // safe: defaults to dark, the canonical Superlist look.
+  const isDark =
+    variant === "dark" ||
+    (variant === undefined &&
+      (typeof window === "undefined" ||
+        window.matchMedia?.("(prefers-color-scheme: dark)").matches));
+  return (
+    <div
+      className={className}
+      style={{
+        position: "relative",
+        background: isDark ? DARK_BG : LIGHT_BG,
+        ...style,
+      }}
+    >
+      {noise && (
+        <div
+          aria-hidden
+          style={{
+            position: "absolute",
+            inset: 0,
+            pointerEvents: "none",
+            opacity: 0.025,
+            backgroundImage:
+              "url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='0.9'/></filter><rect width='100%25' height='100%25' filter='url(%23n)'/></svg>\")",
+            mixBlendMode: "overlay",
+          }}
+        />
+      )}
+      {children}
+    </div>
+  );
+}

package/src/ambient/CommandInput.tsx

@@ -0,0 +1,107 @@
+import { useState, type CSSProperties, type FormEvent } from "react";
+
+// The signature ambient component — floating AI / command pill
+// at the bottom of the main content. Heavily blurred glass
+// backdrop, gradient avatar on the left (signals "AI / live"),
+// and a thin Superbar gradient line above it that doubles as a
+// section divider. The most distinctive moment in the design
+// language.
+//
+// Works under any chrome — only really "reads" under
+// ambient because the glass + Superbar accent are the defining
+// gestures. Under other chromes the pill is just a styled
+// input + divider.
+
+export interface CommandInputProps {
+  placeholder?: string;
+  onSubmit?: (value: string) => void;
+  // Width cap on the pill itself. Default 520 px (Superlist-ish).
+  maxWidth?: number;
+  // Hide the Superbar divider above. Default false.
+  hideDivider?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function CommandInput({
+  placeholder = "Ask anything…",
+  onSubmit,
+  maxWidth = 520,
+  hideDivider = false,
+  className,
+  style,
+}: CommandInputProps) {
+  const [value, setValue] = useState("");
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    if (!value.trim()) return;
+    onSubmit?.(value.trim());
+    setValue("");
+  };
+
+  return (
+    <div className={className} style={{ width: "100%", ...style }}>
+      {!hideDivider && (
+        <div
+          aria-hidden
+          style={{
+            height: 1,
+            background: "var(--ck-superbar)",
+            opacity: 0.7,
+            margin: "0 auto 20px",
+            maxWidth,
+          }}
+        />
+      )}
+      <form
+        onSubmit={submit}
+        style={{
+          maxWidth,
+          margin: "0 auto",
+          display: "flex",
+          alignItems: "center",
+          gap: 10,
+          padding: "8px 12px",
+          background: "var(--ck-bg-sidebar, rgba(20,20,28,0.55))",
+          border: "1px solid var(--ck-border-subtle, rgba(255,255,255,0.08))",
+          borderRadius: 999,
+          backdropFilter: "var(--ck-blur-overlay, blur(40px) saturate(180%))",
+          WebkitBackdropFilter: "var(--ck-blur-overlay, blur(40px) saturate(180%))",
+          boxShadow: "var(--ck-shadow-2)",
+        }}
+      >
+        {/* Gradient avatar — coral → violet → blue. Marks the
+            pill as "AI / live", regardless of the consumer's
+            brand accent. */}
+        <span
+          aria-hidden
+          style={{
+            width: 24,
+            height: 24,
+            borderRadius: "50%",
+            background: "var(--ck-superbar)",
+            flexShrink: 0,
+            boxShadow: "0 0 12px color-mix(in srgb, #B66EFF 40%, transparent)",
+          }}
+        />
+        <input
+          type="text"
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          placeholder={placeholder}
+          style={{
+            flex: 1,
+            minWidth: 0,
+            height: 32,
+            padding: 0,
+            border: "none",
+            outline: "none",
+            background: "transparent",
+            color: "var(--ck-text-primary)",
+            font: "400 14px/1 var(--ck-font-sans)",
+          }}
+        />
+      </form>
+    </div>
+  );
+}

package/src/ambient/SuperbarStrip.tsx

@@ -0,0 +1,36 @@
+import type { CSSProperties } from "react";
+
+// Thin gradient strip — the Superbar pattern reusable as a
+// horizontal divider, a tab underline, or a progress bar fill.
+// 1-2 px tall by default; override via `thickness`.
+
+export interface SuperbarStripProps {
+  // px height. Default 1 (hairline divider).
+  thickness?: number;
+  // CSS width — defaults to 100%.
+  width?: string | number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function SuperbarStrip({
+  thickness = 1,
+  width = "100%",
+  className,
+  style,
+}: SuperbarStripProps) {
+  return (
+    <div
+      aria-hidden
+      className={className}
+      style={{
+        width,
+        height: thickness,
+        background: "var(--ck-superbar)",
+        borderRadius: thickness >= 2 ? thickness / 2 : 0,
+        opacity: 0.85,
+        ...style,
+      }}
+    />
+  );
+}

package/src/ambient/index.ts

@@ -0,0 +1,6 @@
+export { CommandInput } from "./CommandInput";
+export type { CommandInputProps } from "./CommandInput";
+export { SuperbarStrip } from "./SuperbarStrip";
+export type { SuperbarStripProps } from "./SuperbarStrip";
+export { AmbientBackdrop } from "./AmbientBackdrop";
+export type { AmbientBackdropProps } from "./AmbientBackdrop";

package/src/bento/BentoCell.tsx

@@ -0,0 +1,66 @@
+import type { CSSProperties, MouseEventHandler, ReactNode } from "react";
+
+// One cell inside a <BentoGrid>. Spans configurable column + row
+// counts; surface styling matches the chrome (22px radius +
+// soft multi-layer shadow under bento). `interactive` enables the
+// hover-lift signature animation defined in chrome-bento.css.
+
+export interface BentoCellProps {
+  children?: ReactNode;
+  colSpan?: number;
+  rowSpan?: number;
+  // Override the cell's background. Useful for media + gradient
+  // cells. Defaults to var(--ck-bg-surface).
+  background?: string;
+  // Override text color (for high-contrast gradient cells).
+  color?: string;
+  // Padding inside the cell. Defaults to 20px.
+  padding?: number | string;
+  // Apply the hover-lift effect. Defaults to false.
+  interactive?: boolean;
+  onClick?: MouseEventHandler<HTMLDivElement>;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function BentoCell({
+  children,
+  colSpan = 1,
+  rowSpan = 1,
+  background,
+  color,
+  padding = 20,
+  interactive = false,
+  onClick,
+  className,
+  style,
+}: BentoCellProps) {
+  return (
+    <div
+      data-ck-bento-cell=""
+      data-interactive={interactive ? "true" : undefined}
+      onClick={onClick}
+      className={className}
+      role={onClick ? "button" : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      style={{
+        gridColumn: `span ${colSpan} / span ${colSpan}`,
+        gridRow: `span ${rowSpan} / span ${rowSpan}`,
+        background: background ?? "var(--ck-bg-surface)",
+        color,
+        border: "1px solid var(--ck-border-subtle)",
+        borderRadius: "var(--ck-radius-lg, 22px)",
+        boxShadow: "var(--ck-shadow-2)",
+        padding,
+        overflow: "hidden",
+        position: "relative",
+        cursor: onClick ? "pointer" : undefined,
+        display: "flex",
+        flexDirection: "column",
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/bento/BentoGrid.tsx

@@ -0,0 +1,42 @@
+import type { CSSProperties, ReactNode } from "react";
+
+// 12-column CSS grid wrapper. Cells set their own colSpan/rowSpan
+// via <BentoCell>. The grid clamps span values to the column count
+// so a 4-wide cell inside an 8-col grid won't overflow.
+
+export interface BentoGridProps {
+  children?: ReactNode;
+  // Column count. Defaults to 12. Pass 6 / 8 for tighter sections.
+  cols?: number;
+  // Gap between cells. Defaults to 16px.
+  gap?: number;
+  // Minimum row height. Cells span discrete rows of this height.
+  rowMinHeight?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function BentoGrid({
+  children,
+  cols = 12,
+  gap = 16,
+  rowMinHeight = 120,
+  className,
+  style,
+}: BentoGridProps) {
+  return (
+    <div
+      data-ck-bento-grid=""
+      className={className}
+      style={{
+        display: "grid",
+        gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
+        gridAutoRows: `minmax(${rowMinHeight}px, auto)`,
+        gap,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/bento/index.ts

@@ -0,0 +1,2 @@
+export * from "./BentoGrid";
+export * from "./BentoCell";