@nim.zone/ui 0.6.0

package/src/components/feedback.tsx

@@ -0,0 +1,61 @@
+import type { HTMLAttributes } from 'react'
+import { cn } from '@/lib/cn'
+
+export interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
+  label?: string
+  size?: 'lg' | 'md' | 'sm'
+}
+
+export function Spinner({ className, label = 'Loading', size = 'md', ...props }: SpinnerProps) {
+  return (
+    <span
+      className={cn('nim-spinner', size !== 'md' && `nim-spinner--${size}`, className)}
+      role="status"
+      {...props}
+    >
+      <span className="nim-visually-hidden">{label}</span>
+    </span>
+  )
+}
+
+export interface ProgressProps extends HTMLAttributes<HTMLDivElement> {
+  label?: string
+  /** Omit for an indeterminate bar. */
+  value?: number
+}
+
+export function Progress({ className, label, value, ...props }: ProgressProps) {
+  const indeterminate = value === undefined
+  const clamped = indeterminate ? 0 : Math.min(100, Math.max(0, value))
+
+  return (
+    <div
+      aria-label={label}
+      aria-valuemax={100}
+      aria-valuemin={0}
+      aria-valuenow={indeterminate ? undefined : clamped}
+      className={cn('nim-progress', indeterminate && 'nim-progress--indeterminate', className)}
+      role="progressbar"
+      {...props}
+    >
+      <div className="nim-progress__fill" style={indeterminate ? undefined : { inlineSize: `${clamped}%` }} />
+    </div>
+  )
+}
+
+export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
+  height?: number | string
+  radius?: string
+  width?: number | string
+}
+
+export function Skeleton({ className, height = '1em', radius, width = '100%', ...props }: SkeletonProps) {
+  return (
+    <span
+      aria-hidden="true"
+      className={cn('nim-skeleton', className)}
+      style={{ blockSize: height, borderRadius: radius, inlineSize: width }}
+      {...props}
+    />
+  )
+}

package/src/components/field.tsx

@@ -0,0 +1,177 @@
+import { useId } from 'react'
+import type { InputHTMLAttributes, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface FieldShellProps {
+  children: (ids: { control: string; describedBy?: string }) => ReactNode
+  className?: string
+  error?: string
+  hint?: string
+  id?: string
+  label?: string
+  required?: boolean
+}
+
+/**
+ * Every nim form control shares this frame, which is what guarantees that a
+ * label, a hint, and an error are wired to the control with the right ids on
+ * every screen — the part teams most often get wrong by hand.
+ */
+export function FieldShell({ children, className, error, hint, id, label, required }: FieldShellProps) {
+  const generated = useId()
+  const control = id ?? `nim-${generated}`
+  const hintId = hint ? `${control}-hint` : undefined
+  const errorId = error ? `${control}-error` : undefined
+  const describedBy = [errorId, hintId].filter(Boolean).join(' ') || undefined
+
+  return (
+    <div className={cn('nim-field', error && 'nim-field--invalid', className)}>
+      {label ? (
+        <label className="nim-field__label" htmlFor={control}>
+          {label}
+          {required ? (
+            <span aria-hidden="true" className="nim-field__required">
+              *
+            </span>
+          ) : null}
+        </label>
+      ) : null}
+      {children({ control, describedBy })}
+      {error ? (
+        <p className="nim-field__error" id={errorId}>
+          {error}
+        </p>
+      ) : null}
+      {hint && !error ? (
+        <p className="nim-field__hint" id={hintId}>
+          {hint}
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  error?: string
+  hint?: string
+  iconEnd?: IconName
+  iconStart?: IconName
+  label?: string
+}
+
+export function Input({ className, error, hint, iconEnd, iconStart, id, label, required, ...props }: InputProps) {
+  return (
+    <FieldShell error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <div
+          className={cn(
+            'nim-input-shell',
+            iconStart && 'nim-input-shell--has-start',
+            iconEnd && 'nim-input-shell--has-end',
+          )}
+        >
+          {iconStart ? (
+            <span className="nim-input-shell__affix nim-input-shell__affix--start">
+              <Icon name={iconStart} size="sm" />
+            </span>
+          ) : null}
+          <input
+            aria-describedby={describedBy}
+            aria-invalid={error ? true : undefined}
+            className={cn('nim-input', className)}
+            id={control}
+            required={required}
+            {...props}
+          />
+          {iconEnd ? (
+            <span className="nim-input-shell__affix nim-input-shell__affix--end">
+              <Icon name={iconEnd} size="sm" />
+            </span>
+          ) : null}
+        </div>
+      )}
+    </FieldShell>
+  )
+}
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  error?: string
+  hint?: string
+  label?: string
+}
+
+export function Textarea({ className, error, hint, id, label, required, rows = 4, ...props }: TextareaProps) {
+  return (
+    <FieldShell error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <textarea
+          aria-describedby={describedBy}
+          aria-invalid={error ? true : undefined}
+          className={cn('nim-textarea', className)}
+          id={control}
+          required={required}
+          rows={rows}
+          {...props}
+        />
+      )}
+    </FieldShell>
+  )
+}
+
+export interface SelectOption {
+  disabled?: boolean
+  label: string
+  value: string
+}
+
+export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'children'> {
+  error?: string
+  hint?: string
+  label?: string
+  options: SelectOption[]
+  placeholder?: string
+}
+
+export function Select({
+  className,
+  error,
+  hint,
+  id,
+  label,
+  options,
+  placeholder,
+  required,
+  ...props
+}: SelectProps) {
+  return (
+    <FieldShell error={error} hint={hint} id={id} label={label} required={required}>
+      {({ control, describedBy }) => (
+        <div className="nim-input-shell nim-input-shell--has-end">
+          <select
+            aria-describedby={describedBy}
+            aria-invalid={error ? true : undefined}
+            className={cn('nim-select', className)}
+            id={control}
+            required={required}
+            {...props}
+          >
+            {placeholder ? (
+              <option value="" disabled>
+                {placeholder}
+              </option>
+            ) : null}
+            {options.map((option) => (
+              <option disabled={option.disabled} key={option.value} value={option.value}>
+                {option.label}
+              </option>
+            ))}
+          </select>
+          <span className="nim-input-shell__affix nim-input-shell__affix--end">
+            <Icon name="chevron-down" size="sm" />
+          </span>
+        </div>
+      )}
+    </FieldShell>
+  )
+}

package/src/components/icon-button.tsx

@@ -0,0 +1,35 @@
+import { forwardRef } from 'react'
+import type { ButtonHTMLAttributes } from 'react'
+import { Icon, type IconName, type IconSize } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export type IconButtonSize = 'sm' | 'md' | 'lg'
+export type IconButtonVariant = 'ghost' | 'outline' | 'solid'
+
+export interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** Required: an icon-only control has no other accessible name. */
+  label: string
+  name: IconName
+  size?: IconButtonSize
+  variant?: IconButtonVariant
+}
+
+const GLYPH_SIZE: Record<IconButtonSize, IconSize> = { sm: 'sm', md: 'md', lg: 'md' }
+
+export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
+  { className, label, name, size = 'md', type = 'button', variant = 'ghost', ...props },
+  ref,
+) {
+  return (
+    <button
+      aria-label={label}
+      className={cn('nim-icon-button', `nim-icon-button--${variant}`, `nim-icon-button--${size}`, className)}
+      ref={ref}
+      title={label}
+      type={type}
+      {...props}
+    >
+      <Icon name={name} size={GLYPH_SIZE[size]} />
+    </button>
+  )
+})

package/src/components/icon.tsx

@@ -0,0 +1,167 @@
+import {
+  AlertTriangle,
+  ArrowRight,
+  Bell,
+  Bookmark,
+  Calendar,
+  Camera,
+  Check,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronUp,
+  CircleAlert,
+  CircleStop,
+  CircleCheck,
+  Clock,
+  Copy,
+  Download,
+  ExternalLink,
+  Eye,
+  FileText,
+  Filter,
+  Heart,
+  Home,
+  Info,
+  Loader,
+  LogOut,
+  Menu,
+  Mic,
+  Minus,
+  Moon,
+  Paperclip,
+  Pause,
+  Pencil,
+  Play,
+  Plus,
+  Search,
+  Send,
+  Settings,
+  Share2,
+  Sparkles,
+  Star,
+  Sun,
+  Trash2,
+  TrendingDown,
+  TrendingUp,
+  Upload,
+  Video,
+  User,
+  Wallet,
+  X,
+} from 'lucide-react'
+import type { LucideIcon } from 'lucide-react'
+import type { SVGProps } from 'react'
+import { cn } from '@/lib/cn'
+
+/**
+ * Icons are addressed by role, not by vendor name. The registry is the whole
+ * point: it keeps the icon set finite and reviewable, it stops two screens
+ * meaning "delete" with two different glyphs, and it means swapping icon
+ * libraries later is one file rather than a codebase sweep.
+ */
+const REGISTRY = {
+  alert: AlertTriangle,
+  'arrow-forward': ArrowRight,
+  bell: Bell,
+  bookmark: Bookmark,
+  calendar: Calendar,
+  camera: Camera,
+  check: Check,
+  'check-circle': CircleCheck,
+  'chevron-back': ChevronLeft,
+  'chevron-down': ChevronDown,
+  'chevron-forward': ChevronRight,
+  'chevron-up': ChevronUp,
+  clock: Clock,
+  close: X,
+  copy: Copy,
+  danger: CircleAlert,
+  document: FileText,
+  download: Download,
+  edit: Pencil,
+  external: ExternalLink,
+  eye: Eye,
+  filter: Filter,
+  heart: Heart,
+  home: Home,
+  info: Info,
+  loading: Loader,
+  menu: Menu,
+  mic: Mic,
+  minus: Minus,
+  moon: Moon,
+  paperclip: Paperclip,
+  pause: Pause,
+  play: Play,
+  plus: Plus,
+  search: Search,
+  send: Send,
+  settings: Settings,
+  share: Share2,
+  'sign-out': LogOut,
+  stop: CircleStop,
+  sparkle: Sparkles,
+  star: Star,
+  sun: Sun,
+  trash: Trash2,
+  'trend-down': TrendingDown,
+  'trend-up': TrendingUp,
+  upload: Upload,
+  video: Video,
+  user: User,
+  wallet: Wallet,
+} satisfies Record<string, LucideIcon>
+
+/**
+ * Icons that point somewhere. These mirror under `dir="rtl"`, because a
+ * "forward" arrow in Persian points left; everything else — a plus, a check, a
+ * clock — means the same thing in both directions and must NOT be flipped.
+ * Getting this wrong per-component is why RTL interfaces end up with mirrored
+ * checkmarks, so the decision lives here, once.
+ */
+const DIRECTIONAL = new Set<string>([
+  'arrow-forward',
+  'chevron-back',
+  'chevron-forward',
+  'external',
+  'send',
+  'share',
+  'sign-out',
+])
+
+export type IconName = keyof typeof REGISTRY
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+export type IconTone = 'accent' | 'danger' | 'default' | 'muted' | 'success' | 'warning'
+
+const SIZES: Record<IconSize, number> = { xs: 14, sm: 16, md: 20, lg: 24, xl: 32 }
+
+export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'ref'> {
+  /** Give a label only when the icon is the sole carrier of meaning. */
+  label?: string
+  name: IconName
+  size?: IconSize
+  tone?: IconTone
+}
+
+export function Icon({ className, label, name, size = 'md', tone = 'default', ...props }: IconProps) {
+  const Glyph = REGISTRY[name]
+
+  return (
+    <Glyph
+      aria-hidden={label ? undefined : true}
+      aria-label={label}
+      className={cn('nim-icon', className)}
+      data-flip={DIRECTIONAL.has(name) ? 'true' : undefined}
+      data-tone={tone === 'default' ? undefined : tone}
+      focusable="false"
+      height={SIZES[size]}
+      role={label ? 'img' : undefined}
+      strokeWidth={1.75}
+      width={SIZES[size]}
+      {...props}
+    />
+  )
+}
+
+export const iconNames = Object.keys(REGISTRY) as IconName[]

package/src/components/layout.tsx

@@ -0,0 +1,38 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '@/lib/cn'
+
+interface BoxProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode
+}
+
+/** The mobile app viewport, centred on a desktop screen. */
+export function AppFrame({ children, className, ...props }: BoxProps) {
+  return (
+    <div className={cn('nim-app-frame', className)} {...props}>
+      {children}
+    </div>
+  )
+}
+
+/** Vertical rhythm. Spacing between components belongs to the page, not to
+    the components, and this is where the page expresses it. */
+export function Stack({
+  children,
+  className,
+  gap = 'md',
+  ...props
+}: BoxProps & { gap?: 'loose' | 'md' | 'tight' }) {
+  return (
+    <div className={cn('nim-stack', gap !== 'md' && `nim-stack--${gap}`, className)} {...props}>
+      {children}
+    </div>
+  )
+}
+
+export function Inline({ children, className, ...props }: BoxProps) {
+  return (
+    <div className={cn('nim-inline', className)} {...props}>
+      {children}
+    </div>
+  )
+}

package/src/components/list.tsx

@@ -0,0 +1,78 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface ListProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode
+  /** Drops the surrounding plate and keeps only the dividers. */
+  plain?: boolean
+}
+
+export function List({ children, className, plain = false, ...props }: ListProps) {
+  return (
+    <div className={cn('nim-list', plain && 'nim-list--plain', className)} {...props}>
+      {children}
+    </div>
+  )
+}
+
+export interface ListRowProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /** Renders the row as a link. Mutually exclusive with `onClick`. */
+  href?: string
+  leading?: ReactNode
+  subtitle?: ReactNode
+  title: ReactNode
+  trailing?: ReactNode
+}
+
+export function ListRow({
+  className,
+  href,
+  leading,
+  onClick,
+  subtitle,
+  title,
+  trailing,
+  ...props
+}: ListRowProps) {
+  const interactive = Boolean(href || onClick)
+  const content = (
+    <>
+      {leading ? <span className="nim-list-row__leading">{leading}</span> : null}
+      <span className="nim-list-row__content">
+        <span className="nim-list-row__title">{title}</span>
+        {subtitle ? <span className="nim-list-row__subtitle">{subtitle}</span> : null}
+      </span>
+      {trailing ? <span className="nim-list-row__trailing">{trailing}</span> : null}
+      {interactive && !trailing ? (
+        <Icon className="nim-list-row__chevron" name="chevron-forward" size="sm" />
+      ) : null}
+    </>
+  )
+
+  const classes = cn('nim-list-row', interactive && 'nim-list-row--interactive', className)
+
+  // A row that does something is a real button or link, never a div with a
+  // click handler — that is what gives it keyboard focus for free.
+  if (href) {
+    return (
+      <a className={classes} href={href} {...props}>
+        {content}
+      </a>
+    )
+  }
+
+  if (onClick) {
+    return (
+      <button className={classes} onClick={onClick} type="button" {...props}>
+        {content}
+      </button>
+    )
+  }
+
+  return (
+    <div className={classes} {...props}>
+      {content}
+    </div>
+  )
+}