@nim.zone/ui 0.6.0

package/src/components/menu.tsx

@@ -0,0 +1,172 @@
+import { useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { ReactElement, ReactNode, Ref, RefObject } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+import { useAnchor } from '@/lib/use-anchor'
+
+export interface MenuAction {
+  danger?: boolean
+  disabled?: boolean
+  icon?: IconName
+  kind?: 'action'
+  label: string
+  onSelect: () => void
+  /** Rendered in the mono, on the trailing edge — a hint, never a binding. */
+  shortcut?: string
+}
+
+export interface MenuHeading {
+  kind: 'heading'
+  label: string
+}
+
+export interface MenuSeparator {
+  kind: 'separator'
+}
+
+export type MenuItem = MenuAction | MenuHeading | MenuSeparator
+
+export interface MenuProps {
+  /** The trigger is the caller's, so the menu has no opinion about what opens
+      it — it only needs the ref to anchor against. */
+  children: (props: { open: boolean; ref: Ref<HTMLButtonElement>; toggle: () => void }) => ReactElement
+  className?: string
+  items: MenuItem[]
+  label: string
+}
+
+const isAction = (item: MenuItem): item is MenuAction => item.kind === undefined || item.kind === 'action'
+
+/**
+ * A list of actions, dismissed by choosing one. A menu holds actions and never
+ * inputs — something the viewer types into is a Popover.
+ *
+ * The trigger is supplied by the caller as a render prop so the menu never has
+ * an opinion about what opens it; it only needs the ref to anchor against.
+ * Arrow keys move a roving active item, Enter and Space choose it, Escape and
+ * an outside click dismiss, and focus returns to the trigger either way.
+ */
+export function Menu({ children, className, items, label }: MenuProps) {
+  const [open, setOpen] = useState(false)
+  const [active, setActive] = useState(0)
+  const triggerRef = useRef<HTMLButtonElement>(null)
+  const panelRef = useRef<HTMLDivElement>(null)
+  const position = useAnchor(triggerRef, panelRef, { onDismiss: () => setOpen(false), open })
+
+  const actions = items.filter(isAction)
+  const enabled = actions.filter((item) => !item.disabled)
+
+  const toggle = () => {
+    setActive(0)
+    setOpen((value) => !value)
+  }
+
+  const choose = (item: MenuAction) => {
+    setOpen(false)
+    item.onSelect()
+  }
+
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    if (enabled.length === 0) return
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      const step = event.key === 'ArrowDown' ? 1 : -1
+      setActive((index) => (index + step + enabled.length) % enabled.length)
+    }
+    if (event.key === 'Home') {
+      event.preventDefault()
+      setActive(0)
+    }
+    if (event.key === 'End') {
+      event.preventDefault()
+      setActive(enabled.length - 1)
+    }
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault()
+      const item = enabled[active]
+      if (item) choose(item)
+    }
+  }
+
+  return (
+    <>
+      {children({ open, ref: triggerRef, toggle })}
+      {open && typeof document !== 'undefined'
+        ? createPortal(
+            <div
+              aria-label={label}
+              className={cn('nim-menu', className)}
+              onKeyDown={onKeyDown}
+              ref={panelRef}
+              role="menu"
+              style={{ insetBlockStart: position.top, insetInlineStart: position.left }}
+              tabIndex={-1}
+            >
+              {items.map((item, index) => {
+                if (item.kind === 'separator') return <hr className="nim-menu__separator" key={`sep-${index}`} />
+                if (item.kind === 'heading')
+                  return (
+                    <p className="nim-menu__label" key={`head-${index}`}>
+                      {item.label}
+                    </p>
+                  )
+
+                return (
+                  <button
+                    className={cn('nim-menu__item', item.danger && 'nim-menu__item--danger')}
+                    data-active={enabled.indexOf(item) === active ? 'true' : undefined}
+                    disabled={item.disabled}
+                    key={item.label}
+                    onClick={() => choose(item)}
+                    onPointerEnter={() => setActive(enabled.indexOf(item))}
+                    role="menuitem"
+                    type="button"
+                  >
+                    {item.icon ? <Icon className="nim-menu__icon" name={item.icon} size="sm" /> : null}
+                    <span>{item.label}</span>
+                    {item.shortcut ? <span className="nim-menu__shortcut">{item.shortcut}</span> : null}
+                  </button>
+                )
+              })}
+            </div>,
+            document.body,
+          )
+        : null}
+    </>
+  )
+}
+
+export interface PopoverProps {
+  children: ReactNode
+  className?: string
+  label: string
+  onClose: () => void
+  open: boolean
+  /** The element the panel is placed against. */
+  triggerRef: RefObject<HTMLElement | null>
+}
+
+/**
+ * A menu's geometry with a form's contents. Unlike a menu it does not close on
+ * a click inside, because the thing inside is what the viewer came for.
+ */
+export function Popover({ children, className, label, onClose, open, triggerRef }: PopoverProps) {
+  const panelRef = useRef<HTMLDivElement>(null)
+  const position = useAnchor(triggerRef, panelRef, { onDismiss: onClose, open })
+
+  if (!open || typeof document === 'undefined') return null
+
+  return createPortal(
+    <div
+      aria-label={label}
+      className={cn('nim-popover', className)}
+      ref={panelRef}
+      role="dialog"
+      style={{ insetBlockStart: position.top, insetInlineStart: position.left }}
+    >
+      {children}
+    </div>,
+    document.body,
+  )
+}

package/src/components/onboarding.tsx

@@ -0,0 +1,157 @@
+import { useCallback, useState } from 'react'
+import type { ReactNode } from 'react'
+import { Button } from '@/components/button'
+import { IconButton } from '@/components/icon-button'
+import { cn } from '@/lib/cn'
+
+export interface OnboardingSlide {
+  /** Illustration, video, or anything else. Sized by the caller. */
+  art?: ReactNode
+  body?: ReactNode
+  id: string
+  /** The chip above the title — the promise, in three or four words. */
+  label?: string
+  /** A caption card under the art: a headline and its supporting points. */
+  proof?: { icon?: ReactNode; points?: string[]; title: ReactNode }
+  title: ReactNode
+}
+
+export interface OnboardingProps {
+  className?: string
+  /** Label for the button on the last slide. */
+  finishLabel: string
+  /** Label for the button on every other slide. */
+  nextLabel: string
+  /** Reached from the finish button, or from skip. */
+  onDone: () => void
+  onSkip?: () => void
+  /** Notified on every slide change, including from a dot. */
+  onStep?: (index: number) => void
+  slides: OnboardingSlide[]
+  skipLabel?: string
+  /** Version string, support line — whatever sits under the CTA. */
+  footnote?: ReactNode
+  /** Brand mark in the top bar. */
+  brand?: ReactNode
+  /** Accessible names for the controls. */
+  labels?: { back: string; dot: (index: number) => string }
+}
+
+const DEFAULT_LABELS = {
+  back: 'Back',
+  dot: (index: number) => `Slide ${index + 1}`,
+}
+
+/**
+ * The three-screen intro a product opens with: art, a promise, a body, and one
+ * CTA that advances.
+ *
+ * State is the component's, because a first-run carousel is never resumed from
+ * a URL — `onStep` reports it for analytics and `onDone` fires when the viewer
+ * either finishes or skips, so the caller routes in one place instead of two.
+ * Slides are announced through a live region rather than by moving focus,
+ * which would yank a screen reader out of the CTA it is already on.
+ */
+export function Onboarding({
+  brand,
+  className,
+  finishLabel,
+  footnote,
+  labels,
+  nextLabel,
+  onDone,
+  onSkip,
+  onStep,
+  skipLabel,
+  slides,
+}: OnboardingProps) {
+  const [index, setIndex] = useState(0)
+  const text = { ...DEFAULT_LABELS, ...labels }
+  const slide = slides[Math.min(index, slides.length - 1)]
+  const last = index === slides.length - 1
+
+  const goTo = useCallback(
+    (next: number) => {
+      setIndex(next)
+      onStep?.(next)
+    },
+    [onStep],
+  )
+
+  return (
+    <section className={cn('nim-onboarding', className)}>
+      <header className="nim-onboarding__bar">
+        <span className="nim-onboarding__brand">{brand}</span>
+        {skipLabel ? (
+          <Button
+            iconEnd="chevron-forward"
+            onClick={onSkip ?? onDone}
+            size="sm"
+            variant="ghost"
+          >
+            {skipLabel}
+          </Button>
+        ) : null}
+      </header>
+
+      <div aria-live="polite" className="nim-onboarding__stage">
+        {slide.art ? <div className="nim-onboarding__art">{slide.art}</div> : null}
+        {slide.proof ? (
+          <div className="nim-onboarding__proof">
+            {slide.proof.icon ? (
+              <span className="nim-onboarding__proof-icon">{slide.proof.icon}</span>
+            ) : null}
+            <span className="nim-onboarding__proof-text">
+              <span className="nim-onboarding__proof-title">{slide.proof.title}</span>
+              {slide.proof.points?.length ? (
+                <span className="nim-onboarding__proof-points">{slide.proof.points.join(' · ')}</span>
+              ) : null}
+            </span>
+          </div>
+        ) : null}
+      </div>
+
+      <div className="nim-onboarding__copy">
+        {slide.label ? <span className="nim-onboarding__chip">{slide.label}</span> : null}
+        <h1 className="nim-onboarding__title">{slide.title}</h1>
+        {slide.body ? <p className="nim-onboarding__body">{slide.body}</p> : null}
+      </div>
+
+      <footer className="nim-onboarding__controls">
+        <div className="nim-onboarding__dots">
+          {slides.map((item, dot) => (
+            <button
+              aria-current={dot === index ? 'step' : undefined}
+              aria-label={text.dot(dot)}
+              className="nim-onboarding__dot"
+              key={item.id}
+              onClick={() => goTo(dot)}
+              type="button"
+            />
+          ))}
+        </div>
+        <div className="nim-onboarding__cta">
+          {index > 0 ? (
+            <IconButton
+              label={text.back}
+              name="chevron-back"
+              onClick={() => goTo(index - 1)}
+              size="lg"
+              variant="outline"
+            />
+          ) : null}
+          <Button
+            fullWidth
+            iconEnd={last ? 'arrow-forward' : undefined}
+            onClick={() => (last ? onDone() : goTo(index + 1))}
+            size="lg"
+            variant="accent"
+          >
+            {last ? finishLabel : nextLabel}
+          </Button>
+        </div>
+        {footnote ? <p className="nim-onboarding__footnote">{footnote}</p> : null}
+      </footer>
+    </section>
+  )
+}

package/src/components/otp-input.tsx

@@ -0,0 +1,144 @@
+import { useCallback, useEffect, useRef } from 'react'
+import type { ClipboardEvent, KeyboardEvent } from 'react'
+import { cn } from '@/lib/cn'
+import { toAsciiDigits } from '@/lib/countries'
+
+export interface OtpInputProps {
+  /** Fires as soon as the last box is filled — by typing, pasting, or SMS
+      autofill. The caller does not need to watch `value.length` itself. */
+  autoFocus?: boolean
+  className?: string
+  error?: string
+  label: string
+  length?: number
+  onChange: (value: string) => void
+  onComplete?: (value: string) => void
+  /** Per-box accessible name, e.g. `(i) => `Digit ${i + 1}``. */
+  digitLabel?: (index: number) => string
+  /** The code so far, ASCII digits only, shorter than `length` while typing. */
+  value: string
+}
+
+/**
+ * The boxed one-time code.
+ *
+ * One `<input>` per digit, but the string is the caller's: the component never
+ * holds a per-box array, so a paste, an SMS autofill, and a keystroke all take
+ * the same path and cannot disagree. The row is pinned `dir="ltr"` even inside
+ * a Persian page — a code is a number, and the first digit belongs on the left
+ * in every script. Input is normalised through `toAsciiDigits`, so ۱۲۳۴۵ typed
+ * on a Persian keyboard arrives as `12345`.
+ *
+ * `autocomplete="one-time-code"` on the first box is what lets iOS and Android
+ * offer the code from the SMS itself.
+ */
+export function OtpInput({
+  autoFocus = false,
+  className,
+  digitLabel,
+  error,
+  label,
+  length = 5,
+  onChange,
+  onComplete,
+  value,
+}: OtpInputProps) {
+  const root = useRef<HTMLDivElement>(null)
+  const digits = value.slice(0, length).split('')
+
+  const focusBox = useCallback((index: number) => {
+    const boxes = root.current?.querySelectorAll<HTMLInputElement>('input')
+    boxes?.[Math.max(0, Math.min(index, boxes.length - 1))]?.focus()
+  }, [])
+
+  useEffect(() => {
+    if (autoFocus) focusBox(0)
+  }, [autoFocus, focusBox])
+
+  const commit = useCallback(
+    (next: string, caret: number) => {
+      const trimmed = next.slice(0, length)
+      onChange(trimmed)
+      if (trimmed.length === length) onComplete?.(trimmed)
+      else focusBox(caret)
+    },
+    [focusBox, length, onChange, onComplete],
+  )
+
+  const handleInput = useCallback(
+    (index: number, raw: string) => {
+      const typed = toAsciiDigits(raw)
+      if (!typed) return
+      // A box can receive more than one digit — a paste into the middle, or a
+      // keyboard suggestion. Write from here and let the rest overflow right.
+      const next = (value.slice(0, index) + typed).slice(0, length)
+      commit(next, next.length)
+    },
+    [commit, length, value],
+  )
+
+  const handleKeyDown = useCallback(
+    (index: number, event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Backspace') {
+        event.preventDefault()
+        // Backspace on an empty box deletes the digit before it, which is the
+        // behaviour a viewer expects from what looks like one field.
+        const target = value[index] ? index : index - 1
+        if (target < 0) return
+        onChange(value.slice(0, target) + value.slice(target + 1))
+        focusBox(target)
+      } else if (event.key === 'ArrowLeft') {
+        focusBox(index - 1)
+      } else if (event.key === 'ArrowRight') {
+        focusBox(index + 1)
+      }
+    },
+    [focusBox, onChange, value],
+  )
+
+  const handlePaste = useCallback(
+    (event: ClipboardEvent<HTMLDivElement>) => {
+      const pasted = toAsciiDigits(event.clipboardData.getData('text'))
+      if (!pasted) return
+      event.preventDefault()
+      commit(pasted.slice(0, length), pasted.length)
+    },
+    [commit, length],
+  )
+
+  return (
+    <div className={cn('nim-otp', error && 'nim-otp--invalid', className)}>
+      <div
+        aria-label={label}
+        className="nim-otp__boxes"
+        dir="ltr"
+        onPaste={handlePaste}
+        ref={root}
+        role="group"
+      >
+        {Array.from({ length }, (_, index) => (
+          <input
+            aria-invalid={error ? true : undefined}
+            aria-label={digitLabel ? digitLabel(index) : `${label} ${index + 1}`}
+            autoComplete={index === 0 ? 'one-time-code' : 'off'}
+            className="nim-otp__box"
+            data-filled={digits[index] ? 'true' : undefined}
+            enterKeyHint="done"
+            inputMode="numeric"
+            key={index}
+            onChange={(event) => handleInput(index, event.target.value)}
+            onFocus={(event) => event.currentTarget.select()}
+            onKeyDown={(event) => handleKeyDown(index, event)}
+            type="text"
+            value={digits[index] ?? ''}
+          />
+        ))}
+      </div>
+      {error ? (
+        <p className="nim-otp__error" role="alert">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  )
+}

package/src/components/pagination.tsx

@@ -0,0 +1,86 @@
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface PaginationProps {
+  className?: string
+  label?: string
+  nextLabel?: string
+  onChange: (page: number) => void
+  page: number
+  pageCount: number
+  previousLabel?: string
+  /** Free text on the leading edge — "Showing 1–6 of 84". */
+  summary?: string
+}
+
+/**
+ * Renders at most seven slots: first, last, the current page and its
+ * neighbours, and an ellipsis wherever the run breaks. The window never
+ * changes width as the viewer moves through it, so the control does not
+ * reflow under the pointer.
+ */
+const windowFor = (page: number, pageCount: number): (number | 'gap')[] => {
+  if (pageCount <= 7) return Array.from({ length: pageCount }, (_, index) => index + 1)
+
+  const pages = new Set([1, pageCount, page, page - 1, page + 1])
+  if (page <= 3) [2, 3, 4].forEach((value) => pages.add(value))
+  if (page >= pageCount - 2) [pageCount - 3, pageCount - 2, pageCount - 1].forEach((value) => pages.add(value))
+
+  const sorted = [...pages].filter((value) => value >= 1 && value <= pageCount).sort((a, b) => a - b)
+
+  return sorted.flatMap((value, index) => (index > 0 && value - sorted[index - 1]! > 1 ? ['gap' as const, value] : [value]))
+}
+
+export function Pagination({
+  className,
+  label = 'Pagination',
+  nextLabel = 'Next page',
+  onChange,
+  page,
+  pageCount,
+  previousLabel = 'Previous page',
+  summary,
+}: PaginationProps) {
+  return (
+    <nav aria-label={label} className={cn('nim-pagination', className)}>
+      {summary ? <p className="nim-pagination__summary">{summary}</p> : <span />}
+      <div className="nim-pagination__list">
+        <button
+          aria-label={previousLabel}
+          className="nim-pagination__item"
+          disabled={page <= 1}
+          onClick={() => onChange(page - 1)}
+          type="button"
+        >
+          <Icon name="chevron-back" size="sm" />
+        </button>
+        {windowFor(page, pageCount).map((slot, index) =>
+          slot === 'gap' ? (
+            <span aria-hidden="true" className="nim-pagination__ellipsis" key={`gap-${index}`}>
+              …
+            </span>
+          ) : (
+            <button
+              aria-current={slot === page ? 'page' : undefined}
+              className="nim-pagination__item"
+              key={slot}
+              onClick={() => onChange(slot)}
+              type="button"
+            >
+              {slot}
+            </button>
+          ),
+        )}
+        <button
+          aria-label={nextLabel}
+          className="nim-pagination__item"
+          disabled={page >= pageCount}
+          onClick={() => onChange(page + 1)}
+          type="button"
+        >
+          <Icon name="chevron-forward" size="sm" />
+        </button>
+      </div>
+    </nav>
+  )
+}

package/src/components/password-field.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react'
+import type { InputHTMLAttributes } from 'react'
+import { FieldShell } from '@/components/field'
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export type PasswordStrength = 'fair' | 'good' | 'strong' | 'weak'
+
+export interface PasswordFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+  error?: string
+  hint?: string
+  label?: string
+  /** Draws the meter. Omit on a sign-in field: scoring a password someone
+      already has tells them nothing they can act on. */
+  strength?: PasswordStrength
+  /** Accessible names for the reveal toggle and the meter. */
+  labels?: { hide: string; show: string; strength: (level: PasswordStrength) => string }
+}
+
+const DEFAULT_LABELS = {
+  hide: 'Hide password',
+  show: 'Show password',
+  strength: (level: PasswordStrength) => `Password strength: ${level}`,
+}
+
+const STEPS: PasswordStrength[] = ['weak', 'fair', 'good', 'strong']
+
+/**
+ * A password input with a reveal toggle and an optional strength meter.
+ *
+ * Revealing is a real `type` swap rather than a font trick, so a password
+ * manager still sees a password field, and the toggle is a button with a
+ * label — an icon that changes silently leaves a screen reader unable to tell
+ * whether the characters are showing.
+ *
+ * Scoring is the caller's: strength depends on the policy being enforced, and
+ * a meter that disagrees with the server's rules is worse than none.
+ */
+export function PasswordField({
+  className,
+  error,
+  hint,
+  id,
+  label,
+  labels,
+  required,
+  strength,
+  ...props
+}: PasswordFieldProps) {
+  const [visible, setVisible] = useState(false)
+  const text = { ...DEFAULT_LABELS, ...labels }
+
+  return (
+    <FieldShell error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <>
+          <div className="nim-input-shell nim-input-shell--has-end">
+            <input
+              aria-describedby={describedBy}
+              aria-invalid={error ? true : undefined}
+              autoComplete={props.autoComplete ?? 'current-password'}
+              className={cn('nim-input', className)}
+              id={control}
+              required={required}
+              {...props}
+              type={visible ? 'text' : 'password'}
+            />
+            <button
+              aria-controls={control}
+              aria-label={visible ? text.hide : text.show}
+              aria-pressed={visible}
+              className="nim-password__toggle"
+              onClick={() => setVisible((was) => !was)}
+              type="button"
+            >
+              <Icon name="eye" size="sm" />
+            </button>
+          </div>
+
+          {strength ? (
+            <div
+              aria-label={text.strength(strength)}
+              className="nim-password__meter"
+              data-level={strength}
+              role="img"
+            >
+              {STEPS.map((step, index) => (
+                <span
+                  className="nim-password__step"
+                  data-on={index <= STEPS.indexOf(strength) ? 'true' : undefined}
+                  key={step}
+                />
+              ))}
+            </div>
+          ) : null}
+        </>
+      )}
+    </FieldShell>
+  )
+}
+
+/**
+ * A default score for products without a policy of their own: length first,
+ * then variety. Deliberately blunt — it is a hint, never a gate.
+ */
+export function scorePassword(password: string): PasswordStrength {
+  if (password.length < 8) return 'weak'
+  const variety = [/[a-z]/, /[A-Z]/, /\d/, /[^\w\s]/].filter((rule) => rule.test(password)).length
+  if (password.length >= 14 && variety >= 3) return 'strong'
+  if (password.length >= 10 && variety >= 2) return 'good'
+  return 'fair'
+}