@protolabsai/ui 0.2.0 → 0.4.0

package/src/index.tsx

@@ -3,7 +3,19 @@
  * Every component is className-only over the --pl-* custom properties, so it
  * inherits the locked brand and restyles for free when a token changes.
  */
-import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+import type {
+  ButtonHTMLAttributes,
+  HTMLAttributes,
+  InputHTMLAttributes,
+  ReactNode,
+  RefObject,
+  SelectHTMLAttributes,
+  TableHTMLAttributes,
+  TdHTMLAttributes,
+  TextareaHTMLAttributes,
+  ThHTMLAttributes,
+} from "react";
+import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
 import "./styles.css";
 
 const cx = (...parts: Array<string | false | undefined>) => parts.filter(Boolean).join(" ");
@@ -225,3 +237,537 @@ export function TextLink({
     />
   );
 }
+
+// ── App primitives (cockpit + future studio apps) ────────────────────────────
+
+export type TabItem = { id: string; label: ReactNode; disabled?: boolean; locked?: boolean };
+
+/** A horizontal tab strip with disabled/locked support (gated workflows). */
+export function Tabs({ items, active, onSelect }: { items: TabItem[]; active: string; onSelect: (id: string) => void }) {
+  return (
+    <div className="pl-tabs" role="tablist">
+      {items.map((t) => (
+        <button
+          key={t.id}
+          role="tab"
+          type="button"
+          aria-selected={t.id === active}
+          className={cx("pl-tab", t.id === active && "pl-tab--active")}
+          disabled={t.disabled}
+          onClick={() => onSelect(t.id)}
+        >
+          {t.label}
+          {t.locked ? (
+            <span className="pl-tab__lock" aria-hidden>
+              🔒
+            </span>
+          ) : null}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** A horizontal kanban board. Wrap BoardColumn children. */
+export function Board({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("pl-board", className)} {...rest} />;
+}
+
+export function BoardColumn({ title, count, children }: { title: ReactNode; count?: ReactNode; children: ReactNode }) {
+  return (
+    <div className="pl-board-col">
+      <div className="pl-board-col__head">
+        <span>{title}</span>
+        {count != null ? <span className="pl-board-col__count">{count}</span> : null}
+      </div>
+      <div className="pl-board-col__body">{children}</div>
+    </div>
+  );
+}
+
+export function BoardCard({ className, ...rest }: ButtonHTMLAttributes<HTMLButtonElement>) {
+  return <button type="button" className={cx("pl-board-card", className)} {...rest} />;
+}
+
+/** A labeled input/textarea bound to a string value (form fields, editors). */
+export function Field({
+  label,
+  value,
+  multiline,
+  readOnly,
+  placeholder,
+  onValueChange,
+  className,
+}: {
+  label: ReactNode;
+  value?: string;
+  multiline?: boolean;
+  readOnly?: boolean;
+  placeholder?: string;
+  onValueChange?: (value: string) => void;
+  className?: string;
+}) {
+  const shared = {
+    className: "pl-field__input",
+    value,
+    readOnly,
+    placeholder,
+    onChange: (e: { target: { value: string } }) => onValueChange?.(e.target.value),
+  };
+  return (
+    <label className={cx("pl-field", className)}>
+      <span className="pl-field__label">{label}</span>
+      {multiline ? <textarea {...shared} /> : <input {...shared} />}
+    </label>
+  );
+}
+
+// ── Overlays & feedback ──────────────────────────────────────────────────────
+
+/** Esc-to-close + body scroll-lock while `open`. Shared by Dialog + Drawer. */
+function useOverlayDismiss(open: boolean, onClose?: () => void) {
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose?.();
+    };
+    document.addEventListener("keydown", onKey);
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prev;
+    };
+  }, [open, onClose]);
+}
+
+/** Move focus into `ref` on open and cycle Tab within it (a11y modal trap). */
+function useFocusTrap(ref: RefObject<HTMLElement | null>, open: boolean) {
+  useEffect(() => {
+    const node = ref.current;
+    if (!open || !node) return;
+    const focusables = () =>
+      Array.from(
+        node.querySelectorAll<HTMLElement>(
+          'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])',
+        ),
+      ).filter((el) => el.offsetParent !== null);
+    (focusables()[0] ?? node).focus();
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Tab") return;
+      const items = focusables();
+      if (items.length === 0) return;
+      const first = items[0];
+      const last = items[items.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    node.addEventListener("keydown", onKey);
+    return () => node.removeEventListener("keydown", onKey);
+  }, [ref, open]);
+}
+
+/** Modal dialog — scrim + centered card, Esc / backdrop close, focus trap.
+ *  Controlled: render with `open` and handle `onClose`. */
+export function Dialog({
+  open,
+  onClose,
+  title,
+  children,
+  footer,
+  width,
+  className,
+}: {
+  open: boolean;
+  onClose?: () => void;
+  title?: ReactNode;
+  children?: ReactNode;
+  /** Action row pinned to the dialog foot (e.g. Cancel / Confirm buttons). */
+  footer?: ReactNode;
+  width?: number | string;
+  className?: string;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const labelId = useId();
+  useOverlayDismiss(open, onClose);
+  useFocusTrap(ref, open);
+  if (!open) return null;
+  return (
+    <div
+      className="pl-overlay"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onClose?.();
+      }}
+    >
+      <div
+        ref={ref}
+        className={cx("pl-dialog", className)}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title != null ? labelId : undefined}
+        tabIndex={-1}
+        style={width != null ? { width, maxWidth: "100%" } : undefined}
+      >
+        {title != null && (
+          <div className="pl-dialog__head">
+            <div className="pl-dialog__title" id={labelId}>
+              {title}
+            </div>
+            {onClose && (
+              <button type="button" className="pl-dialog__close" aria-label="Close" onClick={onClose}>
+                ×
+              </button>
+            )}
+          </div>
+        )}
+        {children != null && <div className="pl-dialog__body">{children}</div>}
+        {footer != null && <div className="pl-dialog__foot">{footer}</div>}
+      </div>
+    </div>
+  );
+}
+
+/** Destructive-confirm convenience over Dialog. `destructive` reddens confirm. */
+export function ConfirmDialog({
+  open,
+  title,
+  children,
+  confirmLabel = "Confirm",
+  cancelLabel = "Cancel",
+  destructive,
+  onConfirm,
+  onClose,
+}: {
+  open: boolean;
+  title?: ReactNode;
+  children?: ReactNode;
+  confirmLabel?: ReactNode;
+  cancelLabel?: ReactNode;
+  destructive?: boolean;
+  onConfirm?: () => void;
+  onClose?: () => void;
+}) {
+  return (
+    <Dialog
+      open={open}
+      onClose={onClose}
+      title={title}
+      width={420}
+      footer={
+        <>
+          <Button onClick={onClose}>{cancelLabel}</Button>
+          <Button
+            variant="primary"
+            className={cx(destructive && "pl-btn--danger")}
+            onClick={() => onConfirm?.()}
+          >
+            {confirmLabel}
+          </Button>
+        </>
+      }
+    >
+      {children}
+    </Dialog>
+  );
+}
+
+/** Slide-in side panel / sheet. Esc / backdrop close, focus trap. */
+export function Drawer({
+  open,
+  onClose,
+  side = "right",
+  title,
+  children,
+  footer,
+  width,
+  className,
+}: {
+  open: boolean;
+  onClose?: () => void;
+  side?: "left" | "right";
+  title?: ReactNode;
+  children?: ReactNode;
+  footer?: ReactNode;
+  width?: number | string;
+  className?: string;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const labelId = useId();
+  useOverlayDismiss(open, onClose);
+  useFocusTrap(ref, open);
+  if (!open) return null;
+  return (
+    <div
+      className="pl-overlay pl-overlay--drawer"
+      onMouseDown={(e) => {
+        if (e.target === e.currentTarget) onClose?.();
+      }}
+    >
+      <div
+        ref={ref}
+        className={cx("pl-drawer", `pl-drawer--${side}`, className)}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title != null ? labelId : undefined}
+        tabIndex={-1}
+        style={width != null ? { width, maxWidth: "100%" } : undefined}
+      >
+        {title != null && (
+          <div className="pl-drawer__head">
+            <div className="pl-drawer__title" id={labelId}>
+              {title}
+            </div>
+            {onClose && (
+              <button type="button" className="pl-dialog__close" aria-label="Close" onClick={onClose}>
+                ×
+              </button>
+            )}
+          </div>
+        )}
+        <div className="pl-drawer__body">{children}</div>
+        {footer != null && <div className="pl-drawer__foot">{footer}</div>}
+      </div>
+    </div>
+  );
+}
+
+type ToastOptions = { tone?: Status; title?: ReactNode; message: ReactNode; duration?: number };
+type ToastItem = Required<Pick<ToastOptions, "tone" | "message" | "duration">> & {
+  id: string;
+  title?: ReactNode;
+};
+
+const ToastContext = createContext<((opts: ToastOptions) => string) | null>(null);
+
+/** Wrap the app once. Exposes `useToast()` to push transient notifications. */
+export function ToastProvider({ children, max = 4 }: { children: ReactNode; max?: number }) {
+  const [toasts, setToasts] = useState<ToastItem[]>([]);
+  const seq = useRef(0);
+  const dismiss = useCallback((id: string) => setToasts((ts) => ts.filter((t) => t.id !== id)), []);
+  const toast = useCallback(
+    (opts: ToastOptions) => {
+      const id = `t${(seq.current += 1)}`;
+      const item: ToastItem = {
+        id,
+        tone: opts.tone ?? "neutral",
+        title: opts.title,
+        message: opts.message,
+        duration: opts.duration ?? 4000,
+      };
+      setToasts((ts) => [...ts.slice(-(max - 1)), item]);
+      return id;
+    },
+    [max],
+  );
+  return (
+    <ToastContext.Provider value={toast}>
+      {children}
+      <div className="pl-toast-stack" role="region" aria-label="Notifications">
+        {toasts.map((t) => (
+          <ToastView key={t.id} toast={t} onDismiss={dismiss} />
+        ))}
+      </div>
+    </ToastContext.Provider>
+  );
+}
+
+function ToastView({ toast, onDismiss }: { toast: ToastItem; onDismiss: (id: string) => void }) {
+  useEffect(() => {
+    if (toast.duration <= 0) return;
+    const h = setTimeout(() => onDismiss(toast.id), toast.duration);
+    return () => clearTimeout(h);
+  }, [toast, onDismiss]);
+  return (
+    <div className={cx("pl-toast", toast.tone !== "neutral" && `pl-toast--${toast.tone}`)} role="status">
+      <div className="pl-toast__body">
+        {toast.title != null && <div className="pl-toast__title">{toast.title}</div>}
+        <div className="pl-toast__msg">{toast.message}</div>
+      </div>
+      <button type="button" className="pl-toast__close" aria-label="Dismiss" onClick={() => onDismiss(toast.id)}>
+        ×
+      </button>
+    </div>
+  );
+}
+
+/** Returns `toast(opts)` — call to push a notification. Throws outside provider. */
+export function useToast() {
+  const ctx = useContext(ToastContext);
+  if (!ctx) throw new Error("useToast must be used within a <ToastProvider>");
+  return ctx;
+}
+
+/** CSS-only hover/focus tooltip. Wrap the trigger; `label` is the bubble. */
+export function Tooltip({
+  label,
+  side = "top",
+  children,
+}: {
+  label: ReactNode;
+  side?: "top" | "bottom" | "left" | "right";
+  children: ReactNode;
+}) {
+  return (
+    <span className="pl-tip-wrap">
+      {children}
+      <span className={cx("pl-tip", `pl-tip--${side}`)} role="tooltip">
+        {label}
+      </span>
+    </span>
+  );
+}
+
+// ── Data + status primitives ─────────────────────────────────────────────────
+
+/** Dense data table on the 4px grid. Compose with THead/TBody/Tr/Th/Td. */
+export function Table({ className, ...rest }: TableHTMLAttributes<HTMLTableElement>) {
+  return <table className={cx("pl-table", className)} {...rest} />;
+}
+export function THead(props: HTMLAttributes<HTMLTableSectionElement>) {
+  return <thead {...props} />;
+}
+export function TBody(props: HTMLAttributes<HTMLTableSectionElement>) {
+  return <tbody {...props} />;
+}
+/** Table row. `selected` highlights; an `onClick` makes it hover-interactive. */
+export function Tr({
+  selected,
+  className,
+  ...rest
+}: HTMLAttributes<HTMLTableRowElement> & { selected?: boolean }) {
+  return (
+    <tr
+      className={cx(selected && "pl-tr--selected", rest.onClick && "pl-tr--interactive", className)}
+      {...rest}
+    />
+  );
+}
+export function Th({ className, ...rest }: ThHTMLAttributes<HTMLTableCellElement>) {
+  return <th className={className} {...rest} />;
+}
+export function Td({ className, ...rest }: TdHTMLAttributes<HTMLTableCellElement>) {
+  return <td className={className} {...rest} />;
+}
+
+/** Live/health indicator. `pulse` breathes on the 2s status cadence. */
+export function StatusDot({
+  status = "neutral",
+  pulse,
+  label,
+}: {
+  status?: Status;
+  pulse?: boolean;
+  label?: ReactNode;
+}) {
+  const dot = (
+    <span
+      className={cx("pl-dot", status !== "neutral" && `pl-dot--${status}`, pulse && "pl-dot--pulse")}
+      aria-hidden
+    />
+  );
+  if (label == null) return dot;
+  return (
+    <span className="pl-dot-row">
+      {dot}
+      <span className="pl-dot-row__label">{label}</span>
+    </span>
+  );
+}
+
+/** Indeterminate spinner (1s linear, brand-restrained). */
+export function Spinner({ size = 16, className }: { size?: number; className?: string }) {
+  return (
+    <span
+      className={cx("pl-spinner", className)}
+      style={{ width: size, height: size }}
+      role="status"
+      aria-label="Loading"
+    />
+  );
+}
+
+/** Scroll container with brand-styled thin scrollbars. */
+export function ScrollArea({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("pl-scroll", className)} {...rest} />;
+}
+
+// ── Form controls (compose with Field, or use standalone) ────────────────────
+
+export function Input({ className, ...rest }: InputHTMLAttributes<HTMLInputElement>) {
+  return <input className={cx("pl-input", className)} {...rest} />;
+}
+export function Textarea({ className, ...rest }: TextareaHTMLAttributes<HTMLTextAreaElement>) {
+  return <textarea className={cx("pl-input", "pl-textarea", className)} {...rest} />;
+}
+export function Select({ className, children, ...rest }: SelectHTMLAttributes<HTMLSelectElement>) {
+  return (
+    <select className={cx("pl-input", "pl-select", className)} {...rest}>
+      {children}
+    </select>
+  );
+}
+
+/** Toggle switch. Controlled via `checked` / `onCheckedChange`. */
+export function Switch({
+  checked,
+  onCheckedChange,
+  disabled,
+  label,
+  className,
+}: {
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  label?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <label className={cx("pl-switch", disabled && "pl-switch--disabled", className)}>
+      <input
+        type="checkbox"
+        className="pl-switch__input"
+        checked={checked}
+        disabled={disabled}
+        onChange={(e) => onCheckedChange?.(e.target.checked)}
+      />
+      <span className="pl-switch__track" aria-hidden>
+        <span className="pl-switch__thumb" />
+      </span>
+      {label != null && <span className="pl-switch__label">{label}</span>}
+    </label>
+  );
+}
+
+/** Checkbox. Controlled via `checked` / `onCheckedChange`. */
+export function Checkbox({
+  checked,
+  onCheckedChange,
+  disabled,
+  label,
+  className,
+}: {
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  label?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <label className={cx("pl-checkbox", disabled && "pl-checkbox--disabled", className)}>
+      <input
+        type="checkbox"
+        className="pl-checkbox__input"
+        checked={checked}
+        disabled={disabled}
+        onChange={(e) => onCheckedChange?.(e.target.checked)}
+      />
+      <span className="pl-checkbox__box" aria-hidden />
+      {label != null && <span className="pl-checkbox__label">{label}</span>}
+    </label>
+  );
+}