@cosxai/ui 0.1.0

package/src/primitives/Input.tsx

@@ -0,0 +1,71 @@
+import { forwardRef, useId, type InputHTMLAttributes, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// Styled text input with optional label + error + helper text.
+// Three states: idle / focused / invalid. Focus ring + invalid border
+// both via :focus-visible / aria-invalid CSS — no JS branching.
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+  label?: ReactNode;
+  helper?: ReactNode;
+  // Validation error message. When set, the input renders an
+  // invalid border + colour and the helper slot is replaced by
+  // the error text.
+  error?: string | null;
+  // Width preset — full, fixed, or auto (default full).
+  fit?: "full" | "auto";
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  { label, helper, error, fit = "full", className, id, ...rest },
+  ref,
+) {
+  const autoId = useId();
+  const inputId = id ?? autoId;
+  return (
+    <div
+      className={cn("ck-input-field", className)}
+      style={{ display: "flex", flexDirection: "column", gap: 6, width: fit === "full" ? "100%" : undefined }}
+    >
+      {label && (
+        <label
+          htmlFor={inputId}
+          className="ck-eyebrow"
+          style={{ color: "var(--ck-text-secondary)" }}
+        >
+          {label}
+        </label>
+      )}
+      <input
+        ref={ref}
+        id={inputId}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={(helper || error) ? `${inputId}-helper` : undefined}
+        {...rest}
+        className="ck-input"
+        style={{
+          height: 34,
+          padding: "0 12px",
+          font: "400 13px/1 var(--ck-font-sans)",
+          background: "var(--ck-bg-surface)",
+          color: "var(--ck-text-primary)",
+          border: `1px solid ${error ? "var(--ck-critical)" : "var(--ck-border-strong)"}`,
+          borderRadius: "var(--ck-radius-sm)",
+          outline: "none",
+          transition: "border-color var(--ck-dur-fast) var(--ck-ease)",
+        }}
+      />
+      {(helper || error) && (
+        <div
+          id={`${inputId}-helper`}
+          style={{
+            font: "400 11px/1.4 var(--ck-font-sans)",
+            color: error ? "var(--ck-critical)" : "var(--ck-text-tertiary)",
+          }}
+        >
+          {error ?? helper}
+        </div>
+      )}
+    </div>
+  );
+});

package/src/primitives/Kbd.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// Keyboard hint pill — ⌘K, ⌃K, Shift, etc. Auto-translates "Mod"
+// to ⌘ on Mac and Ctrl elsewhere so docs strings can stay portable.
+
+export interface KbdProps {
+  // "Mod" is replaced by ⌘ on Mac, Ctrl elsewhere. Otherwise rendered
+  // verbatim — pass "Shift", "Enter", "↑", "K", etc.
+  children: ReactNode;
+  className?: string;
+}
+
+const isMac =
+  typeof navigator !== "undefined" &&
+  /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+
+function renderChild(c: ReactNode): ReactNode {
+  if (typeof c !== "string") return c;
+  if (c === "Mod") return isMac ? "⌘" : "Ctrl";
+  return c;
+}
+
+export function Kbd({ children, className }: KbdProps) {
+  return (
+    <kbd
+      className={cn("ck-kbd", className)}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        minWidth: 18,
+        height: 18,
+        padding: "0 5px",
+        background: "var(--ck-bg-muted)",
+        border: "1px solid var(--ck-border-subtle)",
+        color: "var(--ck-text-secondary)",
+        font: "500 11px/1 var(--ck-font-mono)",
+        borderRadius: "var(--ck-radius-xs)",
+      }}
+    >
+      {renderChild(children)}
+    </kbd>
+  );
+}

package/src/primitives/PageHeader.tsx

@@ -0,0 +1,77 @@
+import type { ReactNode, CSSProperties } from "react";
+
+// Standard list-page header — eyebrow + title + optional
+// description + right-aligned action cluster. Wrap the top of
+// list / overview pages so visual rhythm stays consistent across
+// the app.
+
+export interface PageHeaderProps {
+  // Small uppercase mono cap above the title — "ACCESS · SHARES".
+  eyebrow?: string;
+  // Main heading (typically a sentence: "Bundles you've sent.").
+  title: ReactNode;
+  // Optional one-or-two-line caption under the title.
+  description?: ReactNode;
+  // Right-aligned cluster of buttons / chips / status items.
+  actions?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function PageHeader({
+  eyebrow,
+  title,
+  description,
+  actions,
+  className,
+  style,
+}: PageHeaderProps) {
+  return (
+    <header
+      className={className}
+      style={{
+        display: "flex",
+        alignItems: "flex-end",
+        gap: 16,
+        marginBottom: 24,
+        paddingBottom: 16,
+        borderBottom: "1px solid var(--ck-border-subtle)",
+        fontFamily: "var(--ck-font-sans)",
+        ...style,
+      }}
+    >
+      <div style={{ flex: 1, minWidth: 0 }}>
+        {eyebrow && (
+          <div className="ck-eyebrow" style={{ marginBottom: 6 }}>
+            {eyebrow}
+          </div>
+        )}
+        <h1
+          style={{
+            font: "500 22px/1.3 var(--ck-font-sans)",
+            letterSpacing: "-0.005em",
+            color: "var(--ck-text-primary)",
+            margin: 0,
+          }}
+        >
+          {title}
+        </h1>
+        {description && (
+          <p
+            style={{
+              font: "400 13px/1.55 var(--ck-font-sans)",
+              color: "var(--ck-text-tertiary)",
+              margin: "6px 0 0",
+              maxWidth: "44rem",
+            }}
+          >
+            {description}
+          </p>
+        )}
+      </div>
+      {actions && (
+        <div style={{ display: "flex", gap: 8, flex: "none" }}>{actions}</div>
+      )}
+    </header>
+  );
+}

package/src/primitives/Tag.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// Small uppercase-mono pill — "PENDING", "LIVE", "Accepted", "3 docs".
+// Same vocabulary as ck-tag in base.css but with explicit tone variants
+// instead of inline color overrides. Use this when the tag is a status
+// indicator; use the bare .ck-tag class when it's just a caption.
+
+export type TagTone = "neutral" | "accent" | "success" | "warning" | "critical";
+
+export interface TagProps {
+  tone?: TagTone;
+  // Renders as a filled pill (background tinted) instead of a bare
+  // colored label. Default false.
+  filled?: boolean;
+  children: ReactNode;
+  className?: string;
+}
+
+const TONE_COLOR: Record<TagTone, string> = {
+  neutral: "var(--ck-text-tertiary)",
+  accent: "var(--ck-accent)",
+  success: "var(--ck-success)",
+  warning: "var(--ck-warning)",
+  critical: "var(--ck-critical)",
+};
+const TONE_BG: Record<TagTone, string> = {
+  neutral: "var(--ck-bg-muted)",
+  accent: "var(--ck-accent-muted)",
+  success: "var(--ck-success-muted)",
+  warning: "var(--ck-warning-muted)",
+  critical: "var(--ck-critical-muted)",
+};
+
+export function Tag({ tone = "neutral", filled = false, children, className }: TagProps) {
+  return (
+    <span
+      className={cn("ck-tag", className)}
+      data-ck-tag
+      data-tone={tone}
+      data-filled={filled ? "true" : undefined}
+      style={
+        filled
+          ? {
+              color: TONE_COLOR[tone],
+              background: TONE_BG[tone],
+              padding: "3px 8px",
+              borderRadius: "var(--ck-radius-sm)",
+            }
+          : { color: TONE_COLOR[tone] }
+      }
+    >
+      {children}
+    </span>
+  );
+}

package/src/primitives/Textarea.tsx

@@ -0,0 +1,62 @@
+import { forwardRef, useId, type TextareaHTMLAttributes, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+
+// Same shape as Input — label + helper + error — for multiline.
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  label?: ReactNode;
+  helper?: ReactNode;
+  error?: string | null;
+}
+
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(
+  function Textarea({ label, helper, error, className, id, ...rest }, ref) {
+    const autoId = useId();
+    const tid = id ?? autoId;
+    return (
+      <div
+        className={cn("ck-textarea-field", className)}
+        style={{ display: "flex", flexDirection: "column", gap: 6 }}
+      >
+        {label && (
+          <label
+            htmlFor={tid}
+            className="ck-eyebrow"
+            style={{ color: "var(--ck-text-secondary)" }}
+          >
+            {label}
+          </label>
+        )}
+        <textarea
+          ref={ref}
+          id={tid}
+          aria-invalid={error ? true : undefined}
+          {...rest}
+          className="ck-textarea"
+          style={{
+            minHeight: 80,
+            padding: "8px 12px",
+            font: "400 13px/1.5 var(--ck-font-sans)",
+            background: "var(--ck-bg-surface)",
+            color: "var(--ck-text-primary)",
+            border: `1px solid ${error ? "var(--ck-critical)" : "var(--ck-border-strong)"}`,
+            borderRadius: "var(--ck-radius-sm)",
+            outline: "none",
+            resize: "vertical",
+            transition: "border-color var(--ck-dur-fast) var(--ck-ease)",
+          }}
+        />
+        {(helper || error) && (
+          <div
+            style={{
+              font: "400 11px/1.4 var(--ck-font-sans)",
+              color: error ? "var(--ck-critical)" : "var(--ck-text-tertiary)",
+            }}
+          >
+            {error ?? helper}
+          </div>
+        )}
+      </div>
+    );
+  },
+);

package/src/primitives/ToggleSwitch.tsx

@@ -0,0 +1,79 @@
+import { cn } from "../lib/cn";
+
+// iOS-style track + knob toggle. Off-state track uses
+// --ck-text-secondary (not --ck-border-subtle which is near-invisible
+// on dark backgrounds — same lesson learned in the parent project).
+// Knob is fixed white so it reads on either accent or gray track.
+
+export interface ToggleSwitchProps {
+  checked: boolean;
+  onChange: (next: boolean) => void;
+  label?: React.ReactNode;
+  suffix?: React.ReactNode;
+  disabled?: boolean;
+  className?: string;
+}
+
+export function ToggleSwitch({
+  checked,
+  onChange,
+  label,
+  suffix,
+  disabled,
+  className,
+}: ToggleSwitchProps) {
+  return (
+    <label
+      className={cn("ck-toggle", 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="switch"
+        aria-checked={checked}
+        disabled={disabled}
+        onClick={() => !disabled && onChange(!checked)}
+        style={{
+          position: "relative",
+          width: 34,
+          height: 20,
+          borderRadius: 999,
+          border: "1px solid var(--ck-text-tertiary)",
+          background: checked ? "var(--ck-accent)" : "var(--ck-text-secondary)",
+          padding: 0,
+          cursor: disabled ? "not-allowed" : "pointer",
+          flexShrink: 0,
+          transition: "background var(--ck-dur-fast) var(--ck-ease)",
+        }}
+      >
+        <span
+          aria-hidden
+          style={{
+            position: "absolute",
+            top: 2,
+            left: checked ? 16 : 2,
+            width: 14,
+            height: 14,
+            background: "#FFFFFF",
+            borderRadius: "50%",
+            boxShadow: "0 1px 3px rgba(0,0,0,0.35)",
+            transition: "left var(--ck-dur-fast) var(--ck-ease)",
+          }}
+        />
+      </button>
+      {label}
+      {suffix && (
+        <span style={{ color: "var(--ck-text-tertiary)" }}>{suffix}</span>
+      )}
+    </label>
+  );
+}

package/src/primitives/Tooltip.tsx

@@ -0,0 +1,171 @@
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+
+// Lightweight tooltip — replaces the native `title=` attribute when
+// you want a short reveal delay (default 120 ms vs the OS' ~500 ms)
+// and styling that matches the kit's chrome. Portals to body so it
+// floats above transformed parents / fixed bars.
+//
+// Wraps a single React element child; mouse + focus listeners are
+// attached via clone so the trigger keeps its own handlers.
+
+export interface TooltipProps {
+  content: ReactNode;
+  children: ReactElement<{
+    onMouseEnter?: React.MouseEventHandler;
+    onMouseLeave?: React.MouseEventHandler;
+    onFocus?: React.FocusEventHandler;
+    onBlur?: React.FocusEventHandler;
+  }>;
+  // ms before showing. Default 120.
+  delay?: number;
+  // "top" hovers above the trigger, "bottom" below. Default "top".
+  placement?: "top" | "bottom";
+  // Render even if `content` is falsy. Default false — callers can
+  // wrap unconditionally without branching JSX.
+  alwaysRender?: boolean;
+}
+
+export function Tooltip({
+  content,
+  children,
+  delay = 120,
+  placement = "top",
+  alwaysRender = false,
+}: TooltipProps) {
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const [open, setOpen] = useState(false);
+  const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+  const timerRef = useRef<number | null>(null);
+
+  const cancelTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const computePos = useCallback(() => {
+    const el = triggerRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    setPos({
+      x: r.left + r.width / 2,
+      y: placement === "top" ? r.top : r.bottom,
+    });
+  }, [placement]);
+
+  const show = useCallback(() => {
+    cancelTimer();
+    timerRef.current = window.setTimeout(() => {
+      computePos();
+      setOpen(true);
+      timerRef.current = null;
+    }, delay);
+  }, [cancelTimer, computePos, delay]);
+
+  const hide = useCallback(() => {
+    cancelTimer();
+    setOpen(false);
+  }, [cancelTimer]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onScrollResize = () => computePos();
+    window.addEventListener("scroll", onScrollResize, { passive: true, capture: true });
+    window.addEventListener("resize", onScrollResize);
+    return () => {
+      window.removeEventListener("scroll", onScrollResize, { capture: true });
+      window.removeEventListener("resize", onScrollResize);
+    };
+  }, [open, computePos]);
+
+  useEffect(() => cancelTimer, [cancelTimer]);
+
+  if (!isValidElement(children)) return children;
+  if (!content && !alwaysRender) return children;
+
+  const child = children;
+  // cloneElement's `Partial<P>` signature isn't compatible with the
+  // `T | undefined` event-handler types in HTMLAttributes once
+  // `exactOptionalPropertyTypes: true` is on. The runtime behaviour is fine —
+  // React happily accepts these props on any host element. We narrow via
+  // unknown to silence the type system on a known React-types limitation.
+  const clonedProps = {
+    ref: (el: HTMLElement | null) => {
+      triggerRef.current = el;
+      const childRef = (child as unknown as { ref?: React.Ref<HTMLElement> }).ref;
+      if (typeof childRef === "function") childRef(el);
+      else if (childRef && typeof childRef === "object") {
+        (childRef as { current: HTMLElement | null }).current = el;
+      }
+    },
+    onMouseEnter: (e: React.MouseEvent) => {
+      child.props.onMouseEnter?.(e);
+      show();
+    },
+    onMouseLeave: (e: React.MouseEvent) => {
+      child.props.onMouseLeave?.(e);
+      hide();
+    },
+    onFocus: (e: React.FocusEvent) => {
+      child.props.onFocus?.(e);
+      show();
+    },
+    onBlur: (e: React.FocusEvent) => {
+      child.props.onBlur?.(e);
+      hide();
+    },
+  };
+  const clonedTrigger = cloneElement(
+    child,
+    clonedProps as unknown as Parameters<typeof cloneElement>[1],
+  );
+
+  const tooltipStyle: CSSProperties = {
+    position: "fixed",
+    left: pos?.x ?? -9999,
+    top: pos?.y ?? -9999,
+    transform:
+      placement === "top"
+        ? "translate(-50%, calc(-100% - 8px))"
+        : "translate(-50%, 8px)",
+    background: "var(--ck-bg-surface)",
+    color: "var(--ck-text-primary)",
+    border: "1px solid var(--ck-border-strong)",
+    borderRadius: "var(--ck-radius-sm)",
+    boxShadow: "var(--ck-shadow-2)",
+    padding: "6px 10px",
+    fontSize: 11,
+    fontFamily: "var(--ck-font-mono)",
+    lineHeight: 1.45,
+    letterSpacing: "0.02em",
+    pointerEvents: "none",
+    zIndex: 9999,
+    maxWidth: 320,
+    whiteSpace: "nowrap",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    opacity: open && pos ? 1 : 0,
+    transition: "opacity 120ms ease",
+  };
+
+  return (
+    <>
+      {clonedTrigger}
+      {(open || alwaysRender) &&
+        pos &&
+        createPortal(<div style={tooltipStyle}>{content}</div>, document.body)}
+    </>
+  );
+}

package/src/primitives/index.ts

@@ -0,0 +1,24 @@
+export { Button } from "./Button";
+export type { ButtonProps, ButtonVariant } from "./Button";
+export { Card } from "./Card";
+export type { CardProps } from "./Card";
+export { Tag } from "./Tag";
+export type { TagProps, TagTone } from "./Tag";
+export { CountBadge } from "./CountBadge";
+export type { CountBadgeProps } from "./CountBadge";
+export { Kbd } from "./Kbd";
+export type { KbdProps } from "./Kbd";
+export { Avatar } from "./Avatar";
+export type { AvatarProps } from "./Avatar";
+export { Input } from "./Input";
+export type { InputProps } from "./Input";
+export { Textarea } from "./Textarea";
+export type { TextareaProps } from "./Textarea";
+export { Checkbox } from "./Checkbox";
+export type { CheckboxProps } from "./Checkbox";
+export { ToggleSwitch } from "./ToggleSwitch";
+export type { ToggleSwitchProps } from "./ToggleSwitch";
+export { Tooltip } from "./Tooltip";
+export type { TooltipProps } from "./Tooltip";
+export { PageHeader } from "./PageHeader";
+export type { PageHeaderProps } from "./PageHeader";