@nim.zone/ui 0.6.0

package/src/components/stat.tsx

@@ -0,0 +1,30 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface StatProps extends HTMLAttributes<HTMLDivElement> {
+  /** Signed change, e.g. `+12%`. Direction colours it and picks the arrow. */
+  delta?: string
+  deltaDirection?: 'down' | 'up'
+  label: ReactNode
+  unit?: ReactNode
+  value: ReactNode
+}
+
+export function Stat({ className, delta, deltaDirection = 'up', label, unit, value, ...props }: StatProps) {
+  return (
+    <div className={cn('nim-stat', className)} {...props}>
+      <p className="nim-stat__value">
+        {value}
+        {unit ? <span className="nim-stat__unit">{unit}</span> : null}
+      </p>
+      <p className="nim-label nim-stat__label">{label}</p>
+      {delta ? (
+        <p className="nim-stat__delta" data-direction={deltaDirection}>
+          <Icon name={deltaDirection === 'up' ? 'trend-up' : 'trend-down'} size="xs" />
+          {delta}
+        </p>
+      ) : null}
+    </div>
+  )
+}

package/src/components/stepper.tsx

@@ -0,0 +1,77 @@
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface StepperProps {
+  className?: string
+  decrementLabel?: string
+  incrementLabel?: string
+  label: string
+  max?: number
+  min?: number
+  onChange: (value: number) => void
+  step?: number
+  value: number
+}
+
+/**
+ * A number with two full-size targets. Both buttons are control-height
+ * squares, so the pair clears the touch minimum rather than shrinking into the
+ * cramped ± chevrons this control usually becomes.
+ */
+export function Stepper({
+  className,
+  decrementLabel = 'Decrease',
+  incrementLabel = 'Increase',
+  label,
+  max = Number.MAX_SAFE_INTEGER,
+  min = 0,
+  onChange,
+  step = 1,
+  value,
+}: StepperProps) {
+  const clamp = (next: number) => Math.min(Math.max(next, min), max)
+
+  return (
+    <div
+      aria-label={label}
+      aria-valuemax={max}
+      aria-valuemin={min}
+      aria-valuenow={value}
+      className={cn('nim-stepper', className)}
+      role="spinbutton"
+      tabIndex={0}
+      onKeyDown={(event) => {
+        if (event.key === 'ArrowUp') {
+          event.preventDefault()
+          onChange(clamp(value + step))
+        }
+        if (event.key === 'ArrowDown') {
+          event.preventDefault()
+          onChange(clamp(value - step))
+        }
+      }}
+    >
+      <button
+        aria-label={decrementLabel}
+        className="nim-stepper__button"
+        disabled={value <= min}
+        onClick={() => onChange(clamp(value - step))}
+        tabIndex={-1}
+        type="button"
+      >
+        <Icon name="minus" size="sm" />
+      </button>
+      <span className="nim-stepper__value">{value}</span>
+      <button
+        aria-label={incrementLabel}
+        className="nim-stepper__button"
+        disabled={value >= max}
+        onClick={() => onChange(clamp(value + step))}
+        tabIndex={-1}
+        type="button"
+      >
+        <Icon name="plus" size="sm" />
+      </button>
+    </div>
+  )
+}

package/src/components/tab-bar.tsx

@@ -0,0 +1,82 @@
+import type { CSSProperties, ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface TabBarItem {
+  /** Lifted and filled: the one action the product is for. At most one item
+      should carry it — two centres is no centre. */
+  center?: boolean
+  href?: string
+  icon: IconName
+  /** Full name for assistive tech when `label` is shortened to fit. */
+  fullLabel?: string
+  key: string
+  label: string
+  onSelect?: () => void
+}
+
+export interface TabBarProps {
+  /** Accessible name for the bar itself. */
+  label: string
+  className?: string
+  items: TabBarItem[]
+  /** `key` of the active item. */
+  value: string
+  /** Wrap items in the app's own router link. Given the item and the rendered
+      content, returns the element to use — nim never imports a router. */
+  renderItem?: (item: TabBarItem, content: ReactNode, props: Record<string, unknown>) => ReactNode
+}
+
+/**
+ * The floating bottom navigation of a mobile app: three to five destinations,
+ * one of them optionally lifted into a primary action.
+ *
+ * It renders real links or buttons and marks the active one with
+ * `aria-current="page"`, so the bar is navigable by keyboard and readable by
+ * assistive tech. Routing stays outside: `renderItem` hands the caller the
+ * content and the props to spread onto their own `<Link>`, which is why the
+ * kit ships no router dependency.
+ *
+ * It sits above the safe-area inset rather than under the home indicator, and
+ * the page below owes it `padding-block-end` — a bar that covers the last row
+ * of a list is the most common way this pattern goes wrong.
+ */
+export function TabBar({ className, items, label, renderItem, value }: TabBarProps) {
+  return (
+    <nav aria-label={label} className={cn('nim-tab-bar', className)}>
+      <div className="nim-tab-bar__row" style={{ '--nim-tab-count': items.length } as CSSProperties}>
+        {items.map((item) => {
+          const active = item.key === value
+          const content = (
+            <>
+              <Icon name={item.icon} size={item.center ? 'lg' : 'md'} />
+              <span className="nim-tab-bar__label">{item.label}</span>
+            </>
+          )
+          const props = {
+            'aria-current': active ? ('page' as const) : undefined,
+            'aria-label': item.fullLabel ?? item.label,
+            className: cn('nim-tab-bar__item', item.center && 'nim-tab-bar__item--center'),
+            'data-active': active ? 'true' : undefined,
+          }
+
+          if (renderItem) return (
+              <div className="nim-tab-bar__slot" key={item.key}>
+                {renderItem(item, content, props)}
+              </div>
+            )
+
+          return item.href ? (
+            <a href={item.href} key={item.key} {...props}>
+              {content}
+            </a>
+          ) : (
+            <button key={item.key} onClick={item.onSelect} type="button" {...props}>
+              {content}
+            </button>
+          )
+        })}
+      </div>
+    </nav>
+  )
+}

package/src/components/table.tsx

@@ -0,0 +1,81 @@
+import type { ReactNode } from 'react'
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export type SortDirection = 'ascending' | 'descending'
+
+export interface TableColumn<Row> {
+  /** Aligns to the trailing edge in tabular figures. Use it for money, counts,
+      and dates — anything a reader compares down a column. */
+  numeric?: boolean
+  header: ReactNode
+  key: string
+  render: (row: Row) => ReactNode
+  sortable?: boolean
+  width?: string
+}
+
+export interface TableProps<Row> {
+  caption?: string
+  className?: string
+  columns: TableColumn<Row>[]
+  onSort?: (key: string) => void
+  rowKey: (row: Row) => string
+  rows: Row[]
+  sort?: { direction: SortDirection; key: string }
+}
+
+/**
+ * A table, not a grid of divs: the caller supplies columns and rows and gets
+ * real `<table>` semantics, which is what lets a screen reader announce "row 3
+ * of 84, Amount 4,200".
+ *
+ * Row height follows `--nim-density`, the same multiplier that drives control
+ * heights — the reason density is a token rather than a prop here.
+ */
+export function Table<Row>({ caption, className, columns, onSort, rowKey, rows, sort }: TableProps<Row>) {
+  return (
+    <div className={cn('nim-table-wrap', className)}>
+      <table className="nim-table">
+        {caption ? <caption className="nim-caption">{caption}</caption> : null}
+        <thead>
+          <tr>
+            {columns.map((column) => {
+              const sorted = sort?.key === column.key ? sort.direction : undefined
+
+              return (
+                <th
+                  aria-sort={sorted}
+                  className={cn(column.numeric && 'nim-table__cell--numeric')}
+                  key={column.key}
+                  scope="col"
+                  style={column.width ? { inlineSize: column.width } : undefined}
+                >
+                  {column.sortable && onSort ? (
+                    <button className="nim-table__sort" onClick={() => onSort(column.key)} type="button">
+                      {column.header}
+                      {sorted ? <Icon name={sorted === 'ascending' ? 'chevron-up' : 'chevron-down'} size="xs" /> : null}
+                    </button>
+                  ) : (
+                    column.header
+                  )}
+                </th>
+              )
+            })}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={rowKey(row)}>
+              {columns.map((column) => (
+                <td className={cn(column.numeric && 'nim-table__cell--numeric')} key={column.key}>
+                  {column.render(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}

package/src/components/tabs.tsx

@@ -0,0 +1,72 @@
+import { useRef } from 'react'
+import type { HTMLAttributes } from 'react'
+import { cn } from '@/lib/cn'
+
+export interface TabOption<T extends string> {
+  /** A trailing figure — a count, never a decoration. */
+  count?: number | string
+  disabled?: boolean
+  label: string
+  value: T
+}
+
+export interface TabsProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  label: string
+  onChange: (value: T) => void
+  options: TabOption<T>[]
+  value: T
+}
+
+/**
+ * Tabs switch a region of the page. A Segmented control sets a value. They
+ * look similar and mean different things, and 0.1 had the segmented control
+ * carrying both jobs.
+ *
+ * Arrow keys move between tabs and select as they go — the pattern a tablist
+ * is expected to follow when its panels are cheap to render.
+ */
+export function Tabs<T extends string>({ className, label, onChange, options, value, ...props }: TabsProps<T>) {
+  const listRef = useRef<HTMLDivElement>(null)
+
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0
+    if (step === 0) return
+
+    event.preventDefault()
+    const selectable = options.filter((option) => !option.disabled)
+    const current = selectable.findIndex((option) => option.value === value)
+    const next = selectable[(current + step + selectable.length) % selectable.length]
+    if (!next) return
+
+    onChange(next.value)
+    listRef.current?.querySelector<HTMLButtonElement>(`[data-value="${next.value}"]`)?.focus()
+  }
+
+  return (
+    <div
+      aria-label={label}
+      className={cn('nim-tabs', className)}
+      onKeyDown={onKeyDown}
+      ref={listRef}
+      role="tablist"
+      {...props}
+    >
+      {options.map((option) => (
+        <button
+          aria-selected={option.value === value}
+          className="nim-tab"
+          data-value={option.value}
+          disabled={option.disabled}
+          key={option.value}
+          onClick={() => onChange(option.value)}
+          role="tab"
+          tabIndex={option.value === value ? 0 : -1}
+          type="button"
+        >
+          {option.label}
+          {option.count === undefined ? null : <span className="nim-tab__count">{option.count}</span>}
+        </button>
+      ))}
+    </div>
+  )
+}

package/src/components/task-progress.tsx

@@ -0,0 +1,111 @@
+import type { ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { Progress, Spinner } from '@/components/feedback'
+import { cn } from '@/lib/cn'
+
+export type TaskStepStatus = 'active' | 'done' | 'failed' | 'pending' | 'skipped'
+
+export interface TaskStep {
+  /** What went wrong, or what is happening. Shown under the label — a status
+      word alone leaves a stuck viewer with nothing to act on. */
+  detail?: ReactNode
+  id: string
+  label: ReactNode
+  status: TaskStepStatus
+}
+
+export interface TaskProgressProps {
+  /** Rendered under the steps: a cancel control, a support line. */
+  action?: ReactNode
+  className?: string
+  /** The headline under the ring — what the job is doing right now. */
+  caption?: ReactNode
+  labels?: { of: (done: number, total: number) => string; status: Record<TaskStepStatus, string> }
+  steps: TaskStep[]
+  title?: ReactNode
+  /** 0–100. Omit to derive it from the steps, which is what a job with equal
+      stages wants; pass it when the server knows better. */
+  value?: number
+}
+
+const DEFAULT_LABELS = {
+  of: (done: number, total: number) => `${done} of ${total} steps`,
+  status: {
+    active: 'In progress',
+    done: 'Done',
+    failed: 'Failed',
+    pending: 'Waiting',
+    skipped: 'Skipped',
+  } as Record<TaskStepStatus, string>,
+}
+
+const STATUS_ICON: Record<Exclude<TaskStepStatus, 'active'>, IconName> = {
+  done: 'check',
+  failed: 'close',
+  pending: 'clock',
+  skipped: 'minus',
+}
+
+/**
+ * A long-running job the viewer is waiting on: a scan, an import, a render.
+ *
+ * The steps are the point. A bare percentage tells someone how long to wait;
+ * a named stage tells them what is happening and, when it fails, which part
+ * failed — which is the difference between "try again" and "try again with a
+ * better photo". Failure is a state of a step, not a replacement for the list.
+ *
+ * The region is `aria-live="polite"`, so a stage completing is announced
+ * without the viewer having to keep looking at it.
+ */
+export function TaskProgress({
+  action,
+  caption,
+  className,
+  labels,
+  steps,
+  title,
+  value,
+}: TaskProgressProps) {
+  const text = { ...DEFAULT_LABELS, ...labels }
+  const done = steps.filter((step) => step.status === 'done' || step.status === 'skipped').length
+  const percent = value ?? (steps.length ? Math.round((done / steps.length) * 100) : 0)
+  const failed = steps.some((step) => step.status === 'failed')
+
+  return (
+    <section
+      aria-live="polite"
+      className={cn('nim-task', failed && 'nim-task--failed', className)}
+    >
+      <header className="nim-task__head">
+        {title ? <h2 className="nim-task__title">{title}</h2> : null}
+        {caption ? <p className="nim-task__caption">{caption}</p> : null}
+        {/* The bar takes the danger tone from the section, not from a prop:
+            a failed job is a state of the whole task, and Progress owns one
+            fill in one colour. */}
+        <Progress label={text.of(done, steps.length)} value={percent} />
+      </header>
+
+      <ol className="nim-task__steps">
+        {steps.map((step) => (
+          <li className="nim-task__step" data-status={step.status} key={step.id}>
+            <span className="nim-task__marker">
+              {step.status === 'active' ? (
+                <Spinner size="sm" />
+              ) : (
+                <Icon name={STATUS_ICON[step.status]} size="xs" />
+              )}
+            </span>
+            <span className="nim-task__step-text">
+              <span className="nim-task__step-label">{step.label}</span>
+              <span className="nim-task__step-detail">
+                {step.detail ?? text.status[step.status]}
+              </span>
+            </span>
+          </li>
+        ))}
+      </ol>
+
+      {action ? <div className="nim-task__action">{action}</div> : null}
+    </section>
+  )
+}

package/src/components/theme.tsx

@@ -0,0 +1,112 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react'
+import type { ReactNode } from 'react'
+import { cn } from '@/lib/cn'
+
+/**
+ * nim has two independent appearance axes.
+ *
+ * A STYLE owns how the interface is shaped: radii, elevation geometry, type
+ * voice, press behaviour. A COLOURWAY owns how it is coloured: surfaces, ink,
+ * lines, accent, status. They compose freely — `ledger` + `teal` is a legal
+ * pairing, not a mistake — which is why they are two attributes rather than
+ * one `theme` name multiplying out into a file per combination.
+ */
+export type NimStyle = 'ledger' | 'vlora'
+export type NimColorway = 'coral' | 'oxblood' | 'teal' | 'vermilion'
+
+/** `system` follows the OS and is resolved by CSS, not by JavaScript. */
+export type NimScheme = 'dark' | 'light' | 'system'
+export type NimDirection = 'ltr' | 'rtl'
+
+interface NimContextValue {
+  colorway: NimColorway
+  direction: NimDirection
+  /** BCP 47 tag. Components that format dates or numbers use it; the script
+      corrections in `persian.css` key off the `lang` attribute it writes. */
+  locale: string | undefined
+  scheme: NimScheme
+  setColorway: (colorway: NimColorway) => void
+  setScheme: (scheme: NimScheme) => void
+  setStyle: (style: NimStyle) => void
+  style: NimStyle
+}
+
+const NimContext = createContext<NimContextValue | null>(null)
+
+export interface NimProviderProps {
+  children: ReactNode
+  className?: string
+  defaultColorway?: NimColorway
+  defaultScheme?: NimScheme
+  defaultStyle?: NimStyle
+  direction?: NimDirection
+  /** BCP 47 tag, e.g. `fa-IR`. Written to `lang`, which is what turns on the
+      Persian script corrections and gives Calendar its month and weekday
+      names and its digits. Direction is separate: `dir` says which way the
+      line runs, `lang` says which script is being set. */
+  locale?: string
+  /** Writes the appearance attributes onto <html> as well, so portalled
+      surfaces (sheets, dialogs, menus, toasts) inherit them from outside the
+      React tree. */
+  syncDocument?: boolean
+}
+
+export function NimProvider({
+  children,
+  className,
+  defaultColorway = 'vermilion',
+  defaultScheme = 'light',
+  defaultStyle = 'ledger',
+  direction = 'ltr',
+  locale,
+  syncDocument = true,
+}: NimProviderProps) {
+  const [style, setStyle] = useState<NimStyle>(defaultStyle)
+  const [colorway, setColorway] = useState<NimColorway>(defaultColorway)
+  const [scheme, setScheme] = useState<NimScheme>(defaultScheme)
+
+  useEffect(() => {
+    if (!syncDocument || typeof document === 'undefined') return
+    const root = document.documentElement
+    root.dataset.nimStyle = style
+    root.dataset.nimColorway = colorway
+    // `system` is the absence of a pin: the contract's `color-scheme: light dark`
+    // then lets the OS decide, and every light-dark() pair follows.
+    if (scheme === 'system') delete root.dataset.nimScheme
+    else root.dataset.nimScheme = scheme
+    root.dir = direction
+    if (locale) root.lang = locale
+  }, [colorway, direction, locale, scheme, style, syncDocument])
+
+  const value = useMemo(
+    () => ({ colorway, direction, locale, scheme, setColorway, setScheme, setStyle, style }),
+    [colorway, direction, locale, scheme, style],
+  )
+
+  return (
+    <NimContext.Provider value={value}>
+      <div
+        className={cn('nim-root', className)}
+        data-nim-colorway={colorway}
+        data-nim-scheme={scheme === 'system' ? undefined : scheme}
+        data-nim-style={style}
+        dir={direction}
+        lang={locale}
+      >
+        {children}
+      </div>
+    </NimContext.Provider>
+  )
+}
+
+export function useNim() {
+  const context = useContext(NimContext)
+  if (!context) throw new Error('useNim must be used inside <NimProvider>')
+  return context
+}
+
+/** Convenience for a header toggle: flips light ⇄ dark, leaving `system`. */
+export function useSchemeToggle() {
+  const { scheme, setScheme } = useNim()
+  return useCallback(() => setScheme(scheme === 'dark' ? 'light' : 'dark'), [scheme, setScheme])
+}

package/src/components/toast.tsx

@@ -0,0 +1,87 @@
+import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export type ToastTone = 'accent' | 'danger' | 'neutral' | 'success'
+
+export interface ToastOptions {
+  action?: { label: string; onPress: () => void }
+  /** Milliseconds on screen. Pass 0 to require a manual dismissal. */
+  duration?: number
+  message: string
+  tone?: ToastTone
+}
+
+interface ToastRecord extends ToastOptions {
+  id: number
+}
+
+const ToastContext = createContext<((options: ToastOptions) => void) | null>(null)
+
+const TONE_ICON: Record<ToastTone, IconName> = {
+  accent: 'sparkle',
+  danger: 'danger',
+  neutral: 'info',
+  success: 'check-circle',
+}
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [toasts, setToasts] = useState<ToastRecord[]>([])
+  const nextId = useRef(0)
+
+  const dismiss = useCallback((id: number) => {
+    setToasts((current) => current.filter((toast) => toast.id !== id))
+  }, [])
+
+  const push = useCallback(
+    (options: ToastOptions) => {
+      const id = nextId.current++
+      setToasts((current) => [...current, { ...options, id }])
+      const duration = options.duration ?? 4000
+      if (duration > 0) window.setTimeout(() => dismiss(id), duration)
+    },
+    [dismiss],
+  )
+
+  const value = useMemo(() => push, [push])
+
+  return (
+    <ToastContext.Provider value={value}>
+      {children}
+      {typeof document !== 'undefined'
+        ? createPortal(
+            <div aria-live="polite" className="nim-toast-stack">
+              {toasts.map((toast) => (
+                <div className={cn('nim-toast', `nim-toast--${toast.tone ?? 'neutral'}`)} key={toast.id}>
+                  <Icon className="nim-toast__icon" name={TONE_ICON[toast.tone ?? 'neutral']} size="sm" />
+                  <span className="nim-toast__message">{toast.message}</span>
+                  {toast.action ? (
+                    <button
+                      className="nim-toast__action"
+                      onClick={() => {
+                        toast.action?.onPress()
+                        dismiss(toast.id)
+                      }}
+                      type="button"
+                    >
+                      {toast.action.label}
+                    </button>
+                  ) : null}
+                </div>
+              ))}
+            </div>,
+            document.body,
+          )
+        : null}
+    </ToastContext.Provider>
+  )
+}
+
+/** Throws when used outside the provider — a silent no-op would hide the bug. */
+export function useToast() {
+  const context = useContext(ToastContext)
+  if (!context) throw new Error('useToast must be used inside <ToastProvider>')
+  return context
+}

package/src/components/tooltip.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react'
+import { cn } from '@/lib/cn'
+
+export interface TooltipProps {
+  children: ReactNode
+  className?: string
+  /** The text shown on hover. Never the only place the name lives. */
+  label: string
+}
+
+/**
+ * A name for a control that shows only an icon.
+ *
+ * The bubble is `aria-hidden`: the trigger inside must already carry its own
+ * accessible name (IconButton does), so a screen reader is never read the same
+ * label twice, and a viewer who cannot hover never depends on this.
+ *
+ * Hover waits 200ms; keyboard focus does not, because a viewer who tabbed here
+ * has already asked.
+ */
+export function Tooltip({ children, className, label }: TooltipProps) {
+  return (
+    <span className={cn('nim-tooltip', className)}>
+      {children}
+      <span aria-hidden="true" className="nim-tooltip__bubble" role="tooltip">
+        {label}
+      </span>
+    </span>
+  )
+}