@polderlabs/bizar 7.0.4 → 8.1.0

package/bizar-dash/src/web/v8/ui/feedback/Dialog.tsx

@@ -0,0 +1,149 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import * as RxDialog from '@radix-ui/react-dialog';
+import { X } from 'lucide-react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Dialog — modal panel.
+ *
+ * Built on Radix Dialog for focus trap + escape handling.
+ *
+ * Sizing:
+ *   - sm  : 360px  (confirmations)
+ *   - md  : 560px  (forms, kanban detail)
+ *   - lg  : 800px  (rich content)
+ *   - full: 100%   (rare; long-running tasks)
+ *
+ * No nested modals per DESIGN.md §10 (banned trope).
+ */
+
+export type DialogSize = 'sm' | 'md' | 'lg' | 'full';
+
+export interface DialogProps extends ComponentPropsWithoutRef<typeof RxDialog.Root> {
+  children: ReactNode;
+}
+
+export const Dialog = ({ children, ...rest }: DialogProps) => (
+  <RxDialog.Root {...rest}>{children}</RxDialog.Root>
+);
+
+export const DialogTrigger = RxDialog.Trigger;
+export const DialogClose = RxDialog.Close;
+export const DialogPortal = RxDialog.Portal;
+
+export interface DialogContentProps extends ComponentPropsWithoutRef<typeof RxDialog.Content> {
+  size?: DialogSize;
+  /** Title used for the screen-reader announcement. Prefer visible title via `title` prop. */
+  title: string;
+  /** Optional description; paired with title for a11y. */
+  description?: string;
+  /** Hide the explicit close button. Useful for AlertDialog (only OK/Cancel). */
+  hideClose?: boolean;
+}
+
+const WIDTH: Record<DialogSize, string> = {
+  sm: '420px',
+  md: '560px',
+  lg: '800px',
+  full: '100%',
+};
+
+export const DialogContent = forwardRef<HTMLDivElement, DialogContentProps>(function DialogContent(
+  props,
+  ref,
+) {
+  const { className, size = 'md', title, description, hideClose, children, ...rest } = props;
+  return (
+    <RxDialog.Portal>
+      <RxDialog.Overlay
+        className="v8-dialog-overlay"
+        style={{
+          position: 'fixed',
+          inset: 0,
+          background: 'oklch(0 0 0 / 0.4)',
+          backdropFilter: 'none',
+          zIndex: 'var(--z-modal)',
+          animation: 'v8-dialog-overlay-in var(--motion-base) var(--ease-out)',
+        }}
+      />
+      <RxDialog.Content
+        ref={ref}
+        className={cx('v8-dialog-content', className)}
+        style={{
+          position: 'fixed',
+          top: '50%',
+          left: '50%',
+          transform: 'translate(-50%, -50%)',
+          width: WIDTH[size],
+          maxWidth: 'calc(100vw - 32px)',
+          maxHeight: 'calc(100vh - 64px)',
+          background: 'var(--surface-popover)',
+          border: '1px solid var(--border)',
+          borderRadius: 'var(--radius-lg)',
+          boxShadow: 'var(--shadow-4)',
+          padding: 'var(--space-6)',
+          overflow: 'auto',
+          zIndex: 'calc(var(--z-modal) + 1)',
+          animation: 'v8-dialog-content-in var(--motion-base) var(--ease-out)',
+        }}
+        {...rest}
+      >
+        <RxDialog.Title
+          style={{
+            fontSize: 'var(--fs-18)',
+            fontWeight: 600,
+            marginBottom: description !== undefined ? 'var(--space-1)' : 'var(--space-4)',
+          }}
+        >
+          {title}
+        </RxDialog.Title>
+        {description !== undefined && (
+          <RxDialog.Description
+            style={{
+              fontSize: 'var(--fs-13)',
+              color: 'var(--fg-muted)',
+              marginBottom: 'var(--space-4)',
+            }}
+          >
+            {description}
+          </RxDialog.Description>
+        )}
+        {children}
+        {hideClose !== true && (
+          <RxDialog.Close
+            aria-label="Close"
+            style={{
+              position: 'absolute',
+              top: 12,
+              right: 12,
+              width: 28,
+              height: 28,
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              background: 'transparent',
+              border: 0,
+              borderRadius: 'var(--radius-sm)',
+              color: 'var(--fg-muted)',
+              cursor: 'pointer',
+            }}
+          >
+            <X size={16} aria-hidden="true" />
+          </RxDialog.Close>
+        )}
+      </RxDialog.Content>
+    </RxDialog.Portal>
+  );
+});
+
+/**
+ * AlertDialog — a confirmation dialog (always has at least one Cancel-style action).
+ *
+ * Built on top of Dialog. The semantic difference matters for screen readers:
+ * <AlertDialog> announces "alert" while <Dialog> doesn't.
+ */
+export const AlertDialog = RxDialog.Root;
+export const AlertDialogTrigger = RxDialog.Trigger;
+export const AlertDialogAction = RxDialog.Close;
+export const AlertDialogCancel = RxDialog.Close;
+export const AlertDialogContent = DialogContent;

package/bizar-dash/src/web/v8/ui/feedback/Drawer.tsx

@@ -0,0 +1,8 @@
+/**
+ * Drawer — alias for the right-side Sheet. The semantic distinction exists
+ * because in v8 a Drawer is task / agent detail (right side, fixed width)
+ * while a Sheet is more general (4 sides).
+ *
+ * Use this component name when you want a detail panel.
+ */
+export { Sheet as Drawer, SheetContent as DrawerContent, SheetTrigger as DrawerTrigger, SheetClose as DrawerClose } from './Sheet.js';

package/bizar-dash/src/web/v8/ui/feedback/DropdownMenu.tsx

@@ -0,0 +1,231 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import * as RxMenu from '@radix-ui/react-dropdown-menu';
+import { Check, ChevronRight } from 'lucide-react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * DropdownMenu — a menu attached to a trigger (button click).
+ *
+ * For right-click menus use ContextMenu. For menus inside a Card
+ * (without a trigger) use Menu directly.
+ */
+
+export type DropdownMenuProps = ComponentPropsWithoutRef<typeof RxMenu.Root>;
+
+export const DropdownMenu = ({ children, ...rest }: DropdownMenuProps) => (
+  <RxMenu.Root {...rest}>{children}</RxMenu.Root>
+);
+
+export const DropdownMenuTrigger = RxMenu.Trigger;
+export const DropdownMenuGroup = RxMenu.Group;
+export const DropdownMenuPortal = RxMenu.Portal;
+export const DropdownMenuSub = RxMenu.Sub;
+export const DropdownMenuRadioGroup = RxMenu.RadioGroup;
+
+export interface DropdownMenuContentProps extends ComponentPropsWithoutRef<typeof RxMenu.Content> {
+  children: ReactNode;
+}
+
+export const DropdownMenuContent = forwardRef<HTMLDivElement, DropdownMenuContentProps>(
+  function DropdownMenuContent(props, ref) {
+    const { className, children, sideOffset = 4, ...rest } = props;
+    return (
+      <RxMenu.Portal>
+        <RxMenu.Content
+          ref={ref}
+          sideOffset={sideOffset}
+          className={cx('v8-dropdown-menu', className)}
+          style={{
+            minWidth: 180,
+            background: 'var(--surface-popover)',
+            border: '1px solid var(--border)',
+            borderRadius: 'var(--radius)',
+            boxShadow: 'var(--shadow-3)',
+            padding: 'var(--space-1)',
+            zIndex: 'var(--z-popover)',
+          }}
+          {...rest}
+        >
+          {children}
+        </RxMenu.Content>
+      </RxMenu.Portal>
+    );
+  },
+);
+
+export interface DropdownMenuItemProps extends ComponentPropsWithoutRef<typeof RxMenu.Item> {
+  /** Shortcut shown on the right (e.g. "⌘ K"). */
+  shortcut?: string;
+  /** When true, render a left-aligned danger color (used for delete actions). */
+  danger?: boolean;
+  leftIcon?: ReactNode;
+}
+
+export const DropdownMenuItem = forwardRef<HTMLDivElement, DropdownMenuItemProps>(
+  function DropdownMenuItem(props, ref) {
+    const { className, children, shortcut, danger, leftIcon, disabled, ...rest } = props;
+    return (
+      <RxMenu.Item
+        ref={ref}
+        disabled={disabled}
+        className={cx('v8-dropdown-menu__item', danger && 'is-danger', className)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--space-2)',
+          height: 28,
+          padding: '0 var(--space-2) 0 var(--space-3)',
+          borderRadius: 'var(--radius-sm)',
+          fontSize: 'var(--fs-13)',
+          color: danger === true ? 'var(--danger)' : 'var(--fg)',
+          cursor: disabled === true ? 'not-allowed' : 'pointer',
+          outline: 0,
+          userSelect: 'none',
+        }}
+        {...rest}
+      >
+        {leftIcon !== undefined && (
+          <span style={{ width: 14, display: 'inline-flex', color: 'var(--fg-muted)' }}>{leftIcon}</span>
+        )}
+        <span style={{ flex: 1, minWidth: 0 }}>{children}</span>
+        {shortcut !== undefined && (
+          <span
+            style={{
+              fontFamily: 'var(--font-mono)',
+              fontSize: 'var(--fs-12)',
+              color: 'var(--fg-muted)',
+              marginLeft: 'var(--space-2)',
+            }}
+          >
+            {shortcut}
+          </span>
+        )}
+      </RxMenu.Item>
+    );
+  },
+);
+
+export const DropdownMenuCheckboxItem = forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<typeof RxMenu.CheckboxItem> & { children: ReactNode }
+>(function DropdownMenuCheckboxItem(props, ref) {
+  const { className, children, ...rest } = props;
+  return (
+    <RxMenu.CheckboxItem
+      ref={ref}
+      className={cx('v8-dropdown-menu__checkbox', className)}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--space-2)',
+        height: 28,
+        padding: '0 var(--space-3)',
+        borderRadius: 'var(--radius-sm)',
+        fontSize: 'var(--fs-13)',
+        cursor: 'pointer',
+        outline: 0,
+      }}
+      {...rest}
+    >
+      <RxMenu.ItemIndicator style={{ display: 'inline-flex', color: 'var(--accent)' }}>
+        <Check size={14} aria-hidden="true" />
+      </RxMenu.ItemIndicator>
+      <span>{children}</span>
+    </RxMenu.CheckboxItem>
+  );
+});
+
+export const DropdownMenuLabel = forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<typeof RxMenu.Label>
+>(function DropdownMenuLabel(props, ref) {
+  return (
+    <RxMenu.Label
+      ref={ref}
+      style={{
+        padding: 'var(--space-2) var(--space-3) var(--space-1)',
+        fontSize: 'var(--fs-12)',
+        fontWeight: 600,
+        color: 'var(--fg-subtle)',
+        textTransform: 'uppercase',
+        letterSpacing: 'var(--tracking-wide)',
+      }}
+      {...props}
+    />
+  );
+});
+
+export const DropdownMenuSeparator = forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<typeof RxMenu.Separator>
+>(function DropdownMenuSeparator(props, ref) {
+  return (
+    <RxMenu.Separator
+      ref={ref}
+      style={{
+        height: 1,
+        margin: 'var(--space-1) 0',
+        background: 'var(--border)',
+      }}
+      {...props}
+    />
+  );
+});
+
+export interface DropdownMenuSubTriggerProps
+  extends ComponentPropsWithoutRef<typeof RxMenu.SubTrigger> {
+  children: ReactNode;
+}
+
+export const DropdownMenuSubTrigger = forwardRef<HTMLDivElement, DropdownMenuSubTriggerProps>(
+  function DropdownMenuSubTrigger(props, ref) {
+    const { className, children, ...rest } = props;
+    return (
+      <RxMenu.SubTrigger
+        ref={ref}
+        className={cx('v8-dropdown-menu__sub-trigger', className)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--space-2)',
+          height: 28,
+          padding: '0 var(--space-2) 0 var(--space-3)',
+          borderRadius: 'var(--radius-sm)',
+          fontSize: 'var(--fs-13)',
+          cursor: 'pointer',
+          outline: 0,
+        }}
+        {...rest}
+      >
+        <span style={{ flex: 1 }}>{children}</span>
+        <ChevronRight size={14} aria-hidden="true" style={{ color: 'var(--fg-muted)' }} />
+      </RxMenu.SubTrigger>
+    );
+  },
+);
+
+export const DropdownMenuSubContent = forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithoutRef<typeof RxMenu.SubContent>
+>(function DropdownMenuSubContent(props, ref) {
+  const { className, ...rest } = props;
+  return (
+    <RxMenu.Portal>
+      <RxMenu.SubContent
+        ref={ref}
+        sideOffset={2}
+        className={cx('v8-dropdown-menu__sub-content', className)}
+        style={{
+          minWidth: 180,
+          background: 'var(--surface-popover)',
+          border: '1px solid var(--border)',
+          borderRadius: 'var(--radius)',
+          boxShadow: 'var(--shadow-3)',
+          padding: 'var(--space-1)',
+          zIndex: 'var(--z-popover)',
+        }}
+        {...rest}
+      />
+    </RxMenu.Portal>
+  );
+});

package/bizar-dash/src/web/v8/ui/feedback/EmptyState.tsx

@@ -0,0 +1,48 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * EmptyState — placeholder for empty lists / zero-data views.
+ *
+ * Use when a view has no rows. Never use a spinner; the data is
+ * genuinely empty.
+ */
+export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  icon?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+  action?: ReactNode;
+}
+
+export const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(function EmptyState(
+  props,
+  ref,
+) {
+  const { icon, title, description, action, className, ...rest } = props;
+  return (
+    <div
+      ref={ref}
+      className={cx('v8-empty-state', className)}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 'var(--space-3)',
+        padding: 'var(--space-12) var(--space-6)',
+        textAlign: 'center',
+        color: 'var(--fg-muted)',
+      }}
+      {...rest}
+    >
+      {icon !== undefined && (
+        <div style={{ color: 'var(--fg-subtle)', display: 'inline-flex' }}>{icon}</div>
+      )}
+      <div style={{ fontSize: 'var(--fs-16)', fontWeight: 600, color: 'var(--fg)' }}>{title}</div>
+      {description !== undefined && (
+        <div style={{ fontSize: 'var(--fs-13)', maxWidth: 480 }}>{description}</div>
+      )}
+      {action !== undefined && <div style={{ marginTop: 'var(--space-2)' }}>{action}</div>}
+    </div>
+  );
+});

package/bizar-dash/src/web/v8/ui/feedback/Popover.tsx

@@ -0,0 +1,56 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import * as RxPopover from '@radix-ui/react-popover';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Popover — a small floating panel anchored to a trigger.
+ *
+ * Use for: kanban filter dropdowns, date pickers, color pickers, info panels.
+ * For menus (a list of actions) use DropdownMenu. For right-click use ContextMenu.
+ */
+
+export interface PopoverProps extends Omit<ComponentPropsWithoutRef<typeof RxPopover.Root>, 'children'> {
+  children: ReactNode;
+}
+
+export const Popover = ({ children, ...rest }: PopoverProps) => (
+  <RxPopover.Root {...rest}>{children}</RxPopover.Root>
+);
+
+export const PopoverTrigger = RxPopover.Trigger;
+export const PopoverAnchor = RxPopover.Anchor;
+export const PopoverClose = RxPopover.Close;
+
+export interface PopoverContentProps extends ComponentPropsWithoutRef<typeof RxPopover.Content> {
+  children: ReactNode;
+}
+
+export const PopoverContent = forwardRef<HTMLDivElement, PopoverContentProps>(function PopoverContent(
+  props,
+  ref,
+) {
+  const { className, children, sideOffset = 6, ...rest } = props;
+  return (
+    <RxPopover.Portal>
+      <RxPopover.Content
+        ref={ref}
+        sideOffset={sideOffset}
+        className={cx('v8-popover', className)}
+        style={{
+          background: 'var(--surface-popover)',
+          border: '1px solid var(--border)',
+          borderRadius: 'var(--radius)',
+          boxShadow: 'var(--shadow-3)',
+          padding: 'var(--space-3)',
+          minWidth: 200,
+          maxWidth: 360,
+          zIndex: 'var(--z-popover)',
+        }}
+        {...rest}
+      >
+        {children}
+        <RxPopover.Arrow style={{ fill: 'var(--surface-popover)' }} />
+      </RxPopover.Content>
+    </RxPopover.Portal>
+  );
+});

package/bizar-dash/src/web/v8/ui/feedback/Sheet.tsx

@@ -0,0 +1,103 @@
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import * as RxDialog from '@radix-ui/react-dialog';
+import { X } from 'lucide-react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Sheet — a side-anchored panel.
+ *
+ * Use for: task detail, agent detail, settings panels (mobile), kanban card
+ * expanded. Use a Dialog when the content is best presented centered.
+ */
+
+export type SheetSide = 'top' | 'right' | 'bottom' | 'left';
+
+export interface SheetProps extends Omit<ComponentPropsWithoutRef<typeof RxDialog.Root>, 'children'> {
+  children: ReactNode;
+}
+
+export const Sheet = ({ children, ...rest }: SheetProps) => (
+  <RxDialog.Root {...rest}>{children}</RxDialog.Root>
+);
+
+export const SheetTrigger = RxDialog.Trigger;
+export const SheetClose = RxDialog.Close;
+
+export interface SheetContentProps extends ComponentPropsWithoutRef<typeof RxDialog.Content> {
+  side?: SheetSide;
+  title: string;
+  description?: string;
+  children: ReactNode;
+}
+
+const SIDE_STYLE: Record<SheetSide, React.CSSProperties> = {
+  top: { top: 0, left: 0, right: 0, height: '60vh', borderBottom: '1px solid var(--border)', borderRadius: '0 0 var(--radius-lg) var(--radius-lg)' },
+  right: { top: 0, right: 0, bottom: 0, width: 'min(560px, 100vw)', borderLeft: '1px solid var(--border)' },
+  bottom: { bottom: 0, left: 0, right: 0, height: '60vh', borderTop: '1px solid var(--border)', borderRadius: 'var(--radius-lg) var(--radius-lg) 0 0' },
+  left: { top: 0, left: 0, bottom: 0, width: 'min(560px, 100vw)', borderRight: '1px solid var(--border)' },
+};
+
+export const SheetContent = forwardRef<HTMLDivElement, SheetContentProps>(function SheetContent(
+  props,
+  ref,
+) {
+  const { className, side = 'right', title, description, children, ...rest } = props;
+  return (
+    <RxDialog.Portal>
+      <RxDialog.Overlay
+        style={{
+          position: 'fixed',
+          inset: 0,
+          background: 'oklch(0 0 0 / 0.4)',
+          zIndex: 'var(--z-modal)',
+        }}
+      />
+      <RxDialog.Content
+        ref={ref}
+        data-side={side}
+        className={cx('v8-sheet', className)}
+        style={{
+          position: 'fixed',
+          background: 'var(--surface-popover)',
+          padding: 'var(--space-6)',
+          overflow: 'auto',
+          boxShadow: 'var(--shadow-4)',
+          zIndex: 'calc(var(--z-modal) + 1)',
+          ...SIDE_STYLE[side],
+        }}
+        {...rest}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 'var(--space-4)' }}>
+          <div>
+            <RxDialog.Title style={{ fontSize: 'var(--fs-18)', fontWeight: 600 }}>{title}</RxDialog.Title>
+            {description !== undefined && (
+              <RxDialog.Description
+                style={{ fontSize: 'var(--fs-13)', color: 'var(--fg-muted)', marginTop: 'var(--space-1)' }}
+              >
+                {description}
+              </RxDialog.Description>
+            )}
+          </div>
+          <RxDialog.Close
+            aria-label="Close"
+            style={{
+              width: 28,
+              height: 28,
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              background: 'transparent',
+              border: 0,
+              borderRadius: 'var(--radius-sm)',
+              color: 'var(--fg-muted)',
+              cursor: 'pointer',
+            }}
+          >
+            <X size={16} aria-hidden="true" />
+          </RxDialog.Close>
+        </div>
+        {children}
+      </RxDialog.Content>
+    </RxDialog.Portal>
+  );
+});

package/bizar-dash/src/web/v8/ui/feedback/Skeleton.tsx

@@ -0,0 +1,67 @@
+import { type HTMLAttributes } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Skeleton — a placeholder that pulses while content loads.
+ *
+ * Per DESIGN.md §10: NEVER use a spinner labelled "Loading…". Use
+ * skeleton shapes that mirror the final content (text widths, card
+ * outlines, chart frames).
+ */
+export interface SkeletonProps extends HTMLAttributes<HTMLDivElement> {
+  width?: number | string;
+  height?: number | string;
+  radius?: 'sm' | 'md' | 'pill';
+}
+
+export function Skeleton({
+  width = '100%',
+  height = 16,
+  radius = 'sm',
+  className,
+  style,
+  ...rest
+}: SkeletonProps): JSX.Element {
+  const radiusValue = radius === 'sm' ? 'var(--radius-sm)' : radius === 'pill' ? 'var(--radius-pill)' : 'var(--radius)';
+  return (
+    <div
+      className={cx('v8-skeleton', className)}
+      style={{
+        display: 'inline-block',
+        width: typeof width === 'number' ? `${width}px` : width,
+        height: typeof height === 'number' ? `${height}px` : height,
+        background:
+          'linear-gradient(90deg, var(--surface-1) 0%, var(--surface-2) 50%, var(--surface-1) 100%)',
+        backgroundSize: '200% 100%',
+        borderRadius: radiusValue,
+        animation: 'v8-skeleton-pulse 1.4s ease-in-out infinite',
+        ...style,
+      }}
+      aria-hidden="true"
+      {...rest}
+    />
+  );
+}
+
+/**
+ * SkeletonText — multi-line text placeholder.
+ */
+export interface SkeletonTextProps {
+  lines?: number;
+  /** Width of the last line (defaults to 60%). */
+  lastLineWidth?: string;
+}
+
+export function SkeletonText({ lines = 3, lastLineWidth = '60%' }: SkeletonTextProps): JSX.Element {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-2)' }} aria-hidden="true">
+      {Array.from({ length: lines }, (_, i) => (
+        <Skeleton
+          key={i}
+          width={i === lines - 1 ? lastLineWidth : '100%'}
+          height={12}
+        />
+      ))}
+    </div>
+  );
+}

package/bizar-dash/src/web/v8/ui/feedback/Spinner.tsx

@@ -0,0 +1,30 @@
+import { Loader2 } from 'lucide-react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Spinner — animated loading indicator.
+ *
+ * Per DESIGN.md §10 the v8 dashboard discourages standalone spinners —
+ * prefer <Skeleton> shapes. Use Spinner only inside small controls
+ * (Button loading state) or as an inline status indicator.
+ */
+export interface SpinnerProps {
+  size?: number;
+  className?: string;
+  label?: string;
+}
+
+export function Spinner({ size = 16, className, label }: SpinnerProps): JSX.Element {
+  return (
+    <Loader2
+      size={size}
+      aria-label={label ?? 'Loading'}
+      role="status"
+      className={cx('v8-spinner', className)}
+      style={{
+        color: 'var(--fg-muted)',
+        animation: 'v8-spin 0.8s linear infinite',
+      }}
+    />
+  );
+}