@nim.zone/ui 0.6.0

package/src/components/combobox.tsx

@@ -0,0 +1,157 @@
+import { useId, useMemo, useRef, useState } from 'react'
+import { FieldShell } from '@/components/field'
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface ComboboxOption<T extends string> {
+  disabled?: boolean
+  label: string
+  /** A trailing hint set in the mono — a count, a code, a date. */
+  meta?: string
+  value: T
+}
+
+export interface ComboboxProps<T extends string> {
+  className?: string
+  /** Shown when nothing matches. Give the viewer the way forward rather than
+      a dead end: "No client matches — create it". */
+  emptyState?: (query: string) => React.ReactNode
+  error?: string
+  hint?: string
+  id?: string
+  label?: string
+  onChange: (value: T | null) => void
+  options: ComboboxOption<T>[]
+  placeholder?: string
+  required?: boolean
+  value: T | null
+}
+
+/**
+ * A text input that suggests, and can still be typed into.
+ *
+ * A real `<input>` with `role="combobox"` over a `role="listbox"`, so the
+ * platform's text editing, autofill and form participation are untouched.
+ * Arrow keys move the active option, Enter commits it, Escape reverts to the
+ * last committed value rather than clearing the field.
+ */
+export function Combobox<T extends string>({
+  className,
+  emptyState,
+  error,
+  hint,
+  id,
+  label,
+  onChange,
+  options,
+  placeholder,
+  required,
+  value,
+}: ComboboxProps<T>) {
+  const listId = useId()
+  const selected = options.find((option) => option.value === value) ?? null
+  const [query, setQuery] = useState('')
+  const [open, setOpen] = useState(false)
+  const [active, setActive] = useState(0)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const matches = useMemo(() => {
+    const needle = query.trim().toLowerCase()
+    if (!needle) return options
+    return options.filter((option) => option.label.toLowerCase().includes(needle))
+  }, [options, query])
+
+  const commit = (option: ComboboxOption<T>) => {
+    onChange(option.value)
+    setQuery('')
+    setOpen(false)
+  }
+
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      setQuery('')
+      setOpen(false)
+      return
+    }
+    if (!open && (event.key === 'ArrowDown' || event.key === 'ArrowUp')) {
+      setOpen(true)
+      return
+    }
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      const step = event.key === 'ArrowDown' ? 1 : -1
+      const usable = matches.filter((option) => !option.disabled)
+      if (usable.length === 0) return
+      setActive((index) => (index + step + usable.length) % usable.length)
+    }
+    if (event.key === 'Enter') {
+      const usable = matches.filter((option) => !option.disabled)
+      const option = usable[active]
+      if (option) {
+        event.preventDefault()
+        commit(option)
+      }
+    }
+  }
+
+  const usable = matches.filter((option) => !option.disabled)
+
+  return (
+    <FieldShell className={className} error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <div className="nim-combobox">
+          <div className={cn('nim-input-shell', 'nim-input-shell--has-end')}>
+            <input
+              aria-autocomplete="list"
+              aria-controls={open ? listId : undefined}
+              aria-describedby={describedBy}
+              aria-expanded={open}
+              className="nim-input"
+              id={control}
+              onBlur={() => window.setTimeout(() => setOpen(false), 120)}
+              onChange={(event) => {
+                setQuery(event.target.value)
+                setActive(0)
+                setOpen(true)
+              }}
+              onFocus={() => setOpen(true)}
+              onKeyDown={onKeyDown}
+              placeholder={placeholder}
+              ref={inputRef}
+              role="combobox"
+              value={open ? query : (selected?.label ?? '')}
+            />
+            <span className="nim-input-shell__affix nim-input-shell__affix--end">
+              <Icon name="chevron-down" size="sm" />
+            </span>
+          </div>
+          {open ? (
+            <div className="nim-combobox__list" id={listId} role="listbox">
+              {usable.length === 0 ? (
+                <div className="nim-combobox__empty">
+                  {emptyState ? emptyState(query) : `Nothing matches “${query}”.`}
+                </div>
+              ) : (
+                matches.map((option) => (
+                  <button
+                    aria-selected={usable.indexOf(option) === active}
+                    className="nim-combobox__option"
+                    disabled={option.disabled}
+                    key={option.value}
+                    onClick={() => commit(option)}
+                    onPointerEnter={() => setActive(usable.indexOf(option))}
+                    role="option"
+                    type="button"
+                  >
+                    <span>{option.label}</span>
+                    {option.meta ? <span className="nim-combobox__meta">{option.meta}</span> : null}
+                  </button>
+                ))
+              )}
+            </div>
+          ) : null}
+        </div>
+      )}
+    </FieldShell>
+  )
+}

package/src/components/date-field.tsx

@@ -0,0 +1,394 @@
+import { useMemo, useRef, useState } from 'react'
+import { FieldShell } from '@/components/field'
+import { Icon } from '@/components/icon'
+import { IconButton } from '@/components/icon-button'
+import { Popover } from '@/components/menu'
+import { useNim } from '@/components/theme'
+import { cn } from '@/lib/cn'
+import {
+  addDays,
+  addMonths,
+  defaultSystem,
+  defaultWeekStart,
+  formatNumeric,
+  localeFor,
+  parseNumeric,
+  partsOf,
+  startOfMonth,
+  todayIso,
+  weekdayOf,
+  type CalendarSystem,
+  type IsoDate,
+} from '@/lib/calendars'
+
+export type { CalendarSystem, IsoDate } from '@/lib/calendars'
+
+export interface CalendarProps {
+  className?: string
+  /** Days to flag — a due date, a booking, anything the month should mark. */
+  marked?: IsoDate[]
+  max?: IsoDate
+  min?: IsoDate
+  month: IsoDate
+  onMonthChange: (month: IsoDate) => void
+  onSelect: (date: IsoDate) => void
+  /** The calendar the grid is drawn in. Defaults to Jalali for an `fa` locale
+      and Gregorian everywhere else. The value stays an ISO Gregorian date in
+      both — the calendar is what the viewer reads, not what the API gets. */
+  system?: CalendarSystem
+  value?: IsoDate | null
+  /** 1 = Monday. Defaults to Saturday on the Jalali calendar, Monday on the
+      Gregorian one — the week does not start on the same day everywhere. */
+  weekStart?: number
+}
+
+const labels = {
+  next: 'Next month',
+  previous: 'Previous month',
+}
+
+export function Calendar({
+  className,
+  marked = [],
+  max,
+  min,
+  month,
+  onMonthChange,
+  onSelect,
+  system,
+  value,
+  weekStart,
+}: CalendarProps) {
+  const { locale } = useNim()
+  const calendar = system ?? defaultSystem(locale)
+  const start = weekStart ?? defaultWeekStart(calendar)
+  const today = todayIso()
+  const intlLocale = localeFor(locale, calendar)
+
+  // Month name, weekday names and the digits all come from the locale and the
+  // calendar together. Before 0.4 the grid was Gregorian by contract and the
+  // formatter was pinned to `gregory` to stop an `fa` locale labelling it
+  // «شهریور» over Gregorian cells. Now the grid itself can be Jalali, so the
+  // label and the cells agree either way — and pinning would be the bug.
+  const monthFormat = useMemo(
+    () => new Intl.DateTimeFormat(intlLocale, { month: 'long', timeZone: 'UTC', year: 'numeric' }),
+    [intlLocale],
+  )
+  const dayFormat = useMemo(() => new Intl.NumberFormat(locale), [locale])
+  const weekdayFormat = useMemo(
+    () => new Intl.DateTimeFormat(intlLocale, { timeZone: 'UTC', weekday: 'short' }),
+    [intlLocale],
+  )
+
+  const anchor = startOfMonth(month, calendar)
+  const anchorMonth = partsOf(anchor, calendar).month
+
+  const days = useMemo(() => {
+    // How far back the grid must reach to land on the week's first day.
+    const lead = (weekdayOf(anchor) - start + 7) % 7
+    const gridStart = addDays(anchor, -lead)
+
+    return Array.from({ length: 42 }, (_, index) => {
+      const date = addDays(gridStart, index)
+      const parts = partsOf(date, calendar)
+      return { date, day: parts.day, outside: parts.month !== anchorMonth }
+    })
+  }, [anchor, anchorMonth, calendar, start])
+
+  const weekdays = useMemo(() => {
+    // 2024-01-07 is a Sunday, so adding the weekday index walks a real week.
+    const sunday = '2024-01-07'
+    return Array.from({ length: 7 }, (_, index) => ({
+      key: `${start}-${index}`,
+      label: weekdayFormat.format(new Date(`${addDays(sunday, (start + index) % 7)}T00:00:00Z`)),
+    }))
+  }, [start, weekdayFormat])
+
+  return (
+    <div className={cn('nim-calendar', className)}>
+      <div className="nim-calendar__header">
+        <IconButton
+          label={labels.previous}
+          name="chevron-back"
+          onClick={() => onMonthChange(addMonths(anchor, -1, calendar))}
+          size="sm"
+        />
+        <span className="nim-calendar__month">
+          {monthFormat.format(new Date(`${anchor}T00:00:00Z`))}
+        </span>
+        <IconButton
+          label={labels.next}
+          name="chevron-forward"
+          onClick={() => onMonthChange(addMonths(anchor, 1, calendar))}
+          size="sm"
+        />
+      </div>
+      <div className="nim-calendar__grid" role="grid">
+        {weekdays.map((weekday) => (
+          <span className="nim-calendar__weekday" key={weekday.key}>
+            {weekday.label}
+          </span>
+        ))}
+        {days.map((day) => (
+          <button
+            aria-selected={day.date === value}
+            className={cn(
+              'nim-calendar__day',
+              day.outside && 'nim-calendar__day--outside',
+              day.date === today && 'nim-calendar__day--today',
+              marked.includes(day.date) && 'nim-calendar__day--marked',
+            )}
+            disabled={(min !== undefined && day.date < min) || (max !== undefined && day.date > max)}
+            key={day.date}
+            onClick={() => onSelect(day.date)}
+            role="gridcell"
+            type="button"
+          >
+            {dayFormat.format(day.day)}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+interface DateEntryProps extends Omit<CalendarProps, 'month' | 'onMonthChange' | 'onSelect' | 'value'> {
+  error?: string
+  hint?: string
+  id?: string
+  label?: string
+  onChange: (value: IsoDate) => void
+  required?: boolean
+  value: IsoDate
+}
+
+export type DateFieldProps = DateEntryProps
+
+/**
+ * The typed half of date entry, shared by the field and the picker.
+ *
+ * On the Gregorian calendar this is `<input type="date">`: the mobile date
+ * keyboard, the locale's field order and form validation all come from the
+ * platform, and none of it is worth reimplementing. On the Jalali calendar the
+ * platform has nothing to offer — no browser ships a Jalali date input — so it
+ * is a text field that reads `۱۴۰۴/۰۶/۰۱`, accepts Persian digits, and commits
+ * only what round-trips through ICU.
+ */
+function DateEntry({
+  calendar,
+  describedBy,
+  id,
+  invalid,
+  locale,
+  onChange,
+  value,
+}: {
+  calendar: CalendarSystem
+  describedBy?: string
+  id: string
+  invalid?: boolean
+  locale: string | undefined
+  onChange: (value: IsoDate) => void
+  value: IsoDate
+}) {
+  // What the viewer is typing, kept apart from the committed value so a
+  // half-written year is not repeatedly reformatted under the caret.
+  const [draft, setDraft] = useState<string | null>(null)
+
+  if (calendar === 'gregory') {
+    return (
+      <input
+        aria-describedby={describedBy}
+        aria-invalid={invalid ? true : undefined}
+        className="nim-input"
+        id={id}
+        onChange={(event) => onChange(event.target.value)}
+        type="date"
+        value={value}
+      />
+    )
+  }
+
+  const shown = draft ?? (value ? formatNumeric(value, locale, calendar) : '')
+
+  return (
+    <input
+      aria-describedby={describedBy}
+      aria-invalid={invalid ? true : undefined}
+      className="nim-input"
+      dir="ltr"
+      id={id}
+      inputMode="numeric"
+      onBlur={() => setDraft(null)}
+      onChange={(event) => {
+        setDraft(event.target.value)
+        const parsed = parseNumeric(event.target.value, calendar)
+        if (parsed) onChange(parsed)
+        else if (event.target.value.trim() === '') onChange('')
+      }}
+      placeholder={formatNumeric(todayIso(), locale, calendar)}
+      type="text"
+      value={shown}
+    />
+  )
+}
+
+/**
+ * A text field with a calendar under it, in that order of importance: typing a
+ * date always works, which matters more to more people than the grid does.
+ *
+ * Both halves answer the same calendar system, so a Persian interface types
+ * ۱۴۰۴/۰۶/۰۱ into a Jalali grid — and still hands the caller `2025-08-23`.
+ */
+export function DateField({
+  error,
+  hint,
+  id,
+  label,
+  onChange,
+  required,
+  value,
+  ...calendarProps
+}: DateFieldProps) {
+  const { locale } = useNim()
+  const calendar = calendarProps.system ?? defaultSystem(locale)
+  const [month, setMonth] = useState<IsoDate>(value || todayIso())
+
+  return (
+    <FieldShell error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <div className="nim-stack nim-stack--tight">
+          <DateEntry
+            calendar={calendar}
+            describedBy={describedBy}
+            id={control}
+            invalid={Boolean(error)}
+            locale={locale}
+            onChange={(next) => {
+              onChange(next)
+              if (next) setMonth(next)
+            }}
+            value={value}
+          />
+          <Calendar
+            {...calendarProps}
+            month={month}
+            onMonthChange={setMonth}
+            onSelect={(date) => {
+              onChange(date)
+              setMonth(date)
+            }}
+            system={calendar}
+            value={value}
+          />
+        </div>
+      )}
+    </FieldShell>
+  )
+}
+
+export interface DatePickerProps extends DateEntryProps {
+  /** Accessible names for the two controls the picker adds. */
+  labels?: { clear: string; open: string }
+  /** The same date on the other calendar, under the field. On by default for
+      Jalali, where a viewer often has to reconcile a Gregorian document. */
+  showEquivalent?: boolean
+}
+
+/**
+ * The compact form of date entry: one field, with the grid behind a button.
+ *
+ * Use it in a form, where a permanently open month steals the space three
+ * other fields need; `DateField` is for the screen whose subject is the date.
+ * On the Jalali calendar it prints the Gregorian equivalent under the field —
+ * the reconciliation an Iranian office does by hand all day.
+ */
+export function DatePicker({
+  error,
+  hint,
+  id,
+  label,
+  labels: names,
+  onChange,
+  required,
+  showEquivalent,
+  value,
+  ...calendarProps
+}: DatePickerProps) {
+  const { locale } = useNim()
+  const calendar = calendarProps.system ?? defaultSystem(locale)
+  const [open, setOpen] = useState(false)
+  const [month, setMonth] = useState<IsoDate>(value || todayIso())
+  const trigger = useRef<HTMLButtonElement>(null)
+  const text = { clear: 'Clear date', open: 'Open calendar', ...names }
+  const equivalent = showEquivalent ?? calendar === 'persian'
+  const other: CalendarSystem = calendar === 'persian' ? 'gregory' : 'persian'
+
+  return (
+    <FieldShell error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <div className="nim-date-picker">
+          <div className="nim-date-picker__group">
+            <DateEntry
+              calendar={calendar}
+              describedBy={describedBy}
+              id={control}
+              invalid={Boolean(error)}
+              locale={locale}
+              onChange={(next) => {
+                onChange(next)
+                if (next) setMonth(next)
+              }}
+              value={value}
+            />
+            {value ? (
+              <IconButton
+                label={text.clear}
+                name="close"
+                onClick={() => onChange('')}
+                size="sm"
+              />
+            ) : null}
+            <IconButton
+              aria-expanded={open}
+              label={text.open}
+              name="calendar"
+              onClick={() => setOpen((was) => !was)}
+              ref={trigger}
+              size="sm"
+            />
+          </div>
+
+          {equivalent && value ? (
+            <p className="nim-date-picker__equivalent">
+              <Icon name="calendar" size="xs" />
+              <span dir={other === 'gregory' ? 'ltr' : undefined}>
+                {formatNumeric(value, locale, other)}
+              </span>
+            </p>
+          ) : null}
+
+          <Popover
+            label={label ?? text.open}
+            onClose={() => setOpen(false)}
+            open={open}
+            triggerRef={trigger}
+          >
+            <Calendar
+              {...calendarProps}
+              month={month}
+              onMonthChange={setMonth}
+              onSelect={(date) => {
+                onChange(date)
+                setMonth(date)
+                setOpen(false)
+              }}
+              system={calendar}
+              value={value}
+            />
+          </Popover>
+        </div>
+      )}
+    </FieldShell>
+  )
+}

package/src/components/dialog.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useRef } from 'react'
+import type { ReactNode } from 'react'
+import { IconButton } from '@/components/icon-button'
+import { cn } from '@/lib/cn'
+
+export interface DialogProps {
+  children: ReactNode
+  className?: string
+  closeLabel?: string
+  description?: ReactNode
+  footer?: ReactNode
+  onClose: () => void
+  open: boolean
+  title: ReactNode
+}
+
+/**
+ * The centred modal, for a decision that has to be made now. The Sheet remains
+ * nim's mobile-first surface; this is what a desktop confirmation wants.
+ *
+ * It renders a real `<dialog>` opened with `showModal()`, so the top layer,
+ * the focus trap, the inert background and Escape all come from the platform
+ * rather than from a scrim div and a keydown listener.
+ */
+export function Dialog({
+  children,
+  className,
+  closeLabel = 'Close',
+  description,
+  footer,
+  onClose,
+  open,
+  title,
+}: DialogProps) {
+  const ref = useRef<HTMLDialogElement>(null)
+
+  useEffect(() => {
+    const dialog = ref.current
+    if (!dialog) return
+
+    if (open && !dialog.open) dialog.showModal()
+    if (!open && dialog.open) dialog.close()
+  }, [open])
+
+  useEffect(() => {
+    const dialog = ref.current
+    if (!dialog) return
+
+    // `close` fires for Escape and for the platform's own dismissals, so the
+    // caller's state stays in step without a second key listener.
+    const onCancel = () => onClose()
+    dialog.addEventListener('close', onCancel)
+    return () => dialog.removeEventListener('close', onCancel)
+  }, [onClose])
+
+  return (
+    <dialog
+      className={cn('nim-dialog', className)}
+      onClick={(event) => {
+        // A click landing on the dialog element itself is a click on the
+        // backdrop — the children cover the rest of its box.
+        if (event.target === ref.current) onClose()
+      }}
+      ref={ref}
+    >
+      <div className="nim-dialog__header">
+        <div>
+          <p className="nim-title nim-title--md">{title}</p>
+          {description ? <p className="nim-caption">{description}</p> : null}
+        </div>
+        <IconButton label={closeLabel} name="close" onClick={onClose} size="sm" />
+      </div>
+      <div className="nim-dialog__body">{children}</div>
+      {footer ? <div className="nim-dialog__footer">{footer}</div> : null}
+    </dialog>
+  )
+}

package/src/components/empty-state.tsx

@@ -0,0 +1,23 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  actions?: ReactNode
+  description?: ReactNode
+  icon?: IconName
+  title: ReactNode
+}
+
+export function EmptyState({ actions, className, description, icon = 'search', title, ...props }: EmptyStateProps) {
+  return (
+    <div className={cn('nim-empty', className)} {...props}>
+      <span className="nim-empty__icon">
+        <Icon name={icon} size="md" />
+      </span>
+      <p className="nim-title nim-title--md">{title}</p>
+      {description ? <p className="nim-body nim-body--sm nim-empty__body">{description}</p> : null}
+      {actions ? <div className="nim-empty__actions">{actions}</div> : null}
+    </div>
+  )
+}