@protolabsai/ui 0.7.0 → 0.8.1

package/src/overlays.tsx

@@ -0,0 +1,299 @@
+import type { ReactNode, RefObject } from "react";
+import { createContext, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
+import { cx } from "./internal";
+import type { Status } from "./internal";
+import { Button } from "./primitives";
+
+/** 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={destructive ? "danger" : "primary"} 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>
+  );
+}

package/src/primitives.tsx

@@ -0,0 +1,90 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from "react";
+import { cx } from "./internal";
+import type { Status } from "./internal";
+
+/** The shared status tone, re-exported here as its canonical public home. */
+export type { Status } from "./internal";
+
+export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  /** "primary"/"danger" read as a stronger border, not a fill (brand restraint);
+   *  "ghost" is transparent until hover. */
+  variant?: "default" | "primary" | "ghost" | "danger";
+  size?: "sm" | "md";
+  /** Icon-only: square, centered glyph. Pass `aria-label` for a11y. */
+  icon?: boolean;
+};
+export function Button({ variant = "default", size = "md", icon, className, ...rest }: ButtonProps) {
+  return (
+    <button
+      className={cx(
+        "pl-btn",
+        variant !== "default" && `pl-btn--${variant}`,
+        size === "sm" && "pl-btn--sm",
+        icon && "pl-btn--icon",
+        className,
+      )}
+      {...rest}
+    />
+  );
+}
+
+export function Badge({ status = "neutral", children }: { status?: Status; children: ReactNode }) {
+  return <span className={cx("pl-badge", status !== "neutral" && `pl-badge--${status}`)}>{children}</span>;
+}
+
+export function Card({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("pl-card", className)} {...rest} />;
+}
+
+export function Eyebrow({ children }: { children: ReactNode }) {
+  return <div className="pl-eyebrow">{children}</div>;
+}
+
+/** Mono empty-state line. */
+export function Empty({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("pl-empty", className)} {...rest} />;
+}
+
+/** Hairline rule. */
+export function Divider({ className, ...rest }: HTMLAttributes<HTMLHRElement>) {
+  return <hr className={cx("pl-divider", className)} {...rest} />;
+}
+
+/** Bordered note block — left-accent keyed to the status tone. */
+export function Callout({
+  tone = "neutral",
+  title,
+  children,
+}: {
+  tone?: Status;
+  title?: ReactNode;
+  children: ReactNode;
+}) {
+  return (
+    <div className={cx("pl-callout", tone !== "neutral" && `pl-callout--${tone}`)}>
+      {title != null && <div className="pl-callout__title">{title}</div>}
+      <div className="pl-callout__body">{children}</div>
+    </div>
+  );
+}
+
+/** Keyboard / inline-token chip. */
+export function Kbd({ children }: { children: ReactNode }) {
+  return <kbd className="pl-kbd">{children}</kbd>;
+}
+
+/** Standalone styled link (underline-offset treatment). Use the app's router
+ *  Link for internal navigation; this is for plain anchors. */
+export function TextLink({
+  className,
+  external,
+  ...rest
+}: HTMLAttributes<HTMLAnchorElement> & { href?: string; external?: boolean }) {
+  return (
+    <a
+      className={cx("pl-link", className)}
+      {...(external ? { target: "_blank", rel: "noreferrer noopener" } : {})}
+      {...rest}
+    />
+  );
+}

package/src/styles/app-shell.css

@@ -0,0 +1,212 @@
+/* @protolabsai/ui — app-shell styles (over @protolabsai/design --pl-* tokens). */
+
+/* ── SurfaceRail (icon rail) ─────────────────────────────────────────────────── */
+.pl-rail {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 2px;
+  width: 64px;
+  flex-shrink: 0;
+  padding: 6px;
+  background: var(--pl-color-bg-raised);
+  border-right: var(--pl-border-width) solid var(--pl-color-border);
+}
+
+.pl-rail--right {
+  border-right: none;
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+
+.pl-rail__btn {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+  padding: 8px 2px;
+  background: none;
+  border: none;
+  border-radius: var(--pl-radius);
+  color: var(--pl-color-fg-muted);
+  cursor: pointer;
+  font: inherit;
+  transition:
+    background var(--pl-motion-fast) var(--pl-motion-ease),
+    color var(--pl-motion-fast) var(--pl-motion-ease);
+}
+
+.pl-rail__btn:hover {
+  background: var(--pl-color-bg-hover);
+  color: var(--pl-color-fg);
+}
+
+.pl-rail__btn--active {
+  background: var(--pl-color-bg-subtle);
+  color: var(--pl-color-fg);
+}
+
+.pl-rail__icon {
+  display: inline-flex;
+}
+
+.pl-rail__icon svg {
+  width: 18px;
+  height: 18px;
+}
+
+.pl-rail__label {
+  max-width: 100%;
+  overflow: hidden;
+  font-size: 9px;
+  line-height: 1.1;
+  text-align: center;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.pl-rail__badge {
+  position: absolute;
+  top: 4px;
+  right: 9px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 15px;
+  height: 15px;
+  padding: 0 4px;
+  font-family: var(--pl-font-mono);
+  font-size: 9px;
+  color: var(--pl-color-fg);
+  background: var(--pl-color-bg-subtle);
+  border: var(--pl-border-width) solid var(--pl-color-border-strong);
+  border-radius: 999px;
+}
+
+.pl-rail__dot {
+  position: absolute;
+  top: 6px;
+  right: 14px;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--pl-color-status-info);
+  animation: pl-dot-pulse var(--pl-motion-status) var(--pl-motion-ease-in-out) infinite;
+}
+
+/* ── MobileNav (bottom bar + drawer list) ────────────────────────────────────── */
+.pl-mobilenav {
+  display: flex;
+  align-items: stretch;
+  background: var(--pl-color-bg-raised);
+  border-top: var(--pl-border-width) solid var(--pl-color-border);
+}
+
+.pl-mobilenav__tab {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+  padding: 8px 2px;
+  background: none;
+  border: none;
+  color: var(--pl-color-fg-muted);
+  font: inherit;
+  font-size: 10px;
+  cursor: pointer;
+}
+
+.pl-mobilenav__tab--active {
+  color: var(--pl-color-fg);
+}
+
+.pl-mobilenav__icon {
+  display: inline-flex;
+}
+
+.pl-mobilenav__icon svg {
+  width: 18px;
+  height: 18px;
+}
+
+.pl-mobilenav__list {
+  display: grid;
+  gap: 2px;
+}
+
+.pl-mobilenav__list-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 10px 8px;
+  background: none;
+  border: none;
+  border-radius: var(--pl-radius);
+  color: var(--pl-color-fg);
+  font: inherit;
+  font-size: 14px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.pl-mobilenav__list-item:hover {
+  background: var(--pl-color-bg-hover);
+}
+
+.pl-mobilenav__list-item--active {
+  background: var(--pl-color-bg-subtle);
+}
+
+/* ── AppShell (dual-rail + 3-column) ─────────────────────────────────────────── */
+.pl-appshell {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+  min-height: 0;
+  background: var(--pl-color-bg);
+  color: var(--pl-color-fg);
+}
+
+.pl-appshell__col {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.pl-appshell__col--left {
+  flex: 1 1 auto;
+}
+
+.pl-appshell__col--right {
+  flex: 0 0 auto;
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+
+.pl-appshell__handle {
+  flex: 0 0 auto;
+  width: 5px;
+  cursor: col-resize;
+  background: transparent;
+  touch-action: none;
+  transition: background var(--pl-motion-fast) var(--pl-motion-ease);
+}
+
+.pl-appshell__handle:hover,
+.pl-appshell__handle:focus-visible {
+  background: var(--pl-color-border-strong);
+  outline: none;
+}
+
+.pl-appshell--mobile {
+  flex-direction: column;
+}
+
+.pl-appshell__mobile-stage {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+}