@nim.zone/ui 0.6.0

package/src/components/phone-field.tsx

@@ -0,0 +1,242 @@
+import { useEffect, useId, useMemo, useRef, useState } from 'react'
+import { Icon } from '@/components/icon'
+import { cn } from '@/lib/cn'
+import { COUNTRIES, countryByIso2, countryNamer, toAsciiDigits } from '@/lib/countries'
+
+export interface PhoneFieldProps {
+  className?: string
+  /** ISO 3166-1 alpha-2 of the selected country, e.g. `IR`. */
+  country: string
+  error?: string
+  hint?: string
+  id?: string
+  label?: string
+  /** Locale the country names are shown in. Defaults to the document's. */
+  locale?: string
+  onChange: (value: string) => void
+  onCountryChange: (iso2: string) => void
+  onSubmit?: () => void
+  placeholder?: string
+  /** Countries to float above the alphabetical list — the ones most viewers
+      of this product will pick. */
+  priority?: string[]
+  required?: boolean
+  /** Accessible names for the picker. */
+  labels?: { pickCountry: string; search: string; noMatch: string }
+  /** The national number, ASCII digits only, without the dialling code. */
+  value: string
+}
+
+const DEFAULT_LABELS = {
+  noMatch: 'No country matches',
+  pickCountry: 'Country code',
+  search: 'Search countries',
+}
+
+/**
+ * Phone number entry: a country picker welded to a number input.
+ *
+ * The two halves are separate props on purpose. A field that owns one E.164
+ * string has to re-parse it on every keystroke to know which flag to draw, and
+ * gets it wrong the moment someone types a `+` themselves; keeping the country
+ * and the national digits apart means `+${dial}${value}` is the whole
+ * serialisation and there is nothing to guess.
+ *
+ * The picker lists every ISO country, named in the viewer's locale, searchable
+ * by name, code, or ISO letters. The input is `dir="ltr"` in every direction —
+ * a phone number reads left to right in Persian too — and Persian digits are
+ * normalised to ASCII on the way in.
+ */
+export function PhoneField({
+  className,
+  country,
+  error,
+  hint,
+  id,
+  label,
+  labels,
+  locale,
+  onChange,
+  onCountryChange,
+  onSubmit,
+  placeholder,
+  priority = [],
+  required,
+  value,
+}: PhoneFieldProps) {
+  const generated = useId()
+  const controlId = id ?? `nim-${generated}`
+  const hintId = hint ? `${controlId}-hint` : undefined
+  const errorId = error ? `${controlId}-error` : undefined
+  const text = { ...DEFAULT_LABELS, ...labels }
+
+  const [open, setOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const shell = useRef<HTMLDivElement>(null)
+  const trigger = useRef<HTMLButtonElement>(null)
+  const search = useRef<HTMLInputElement>(null)
+
+  const resolvedLocale =
+    locale ?? (typeof document === 'undefined' ? 'en' : document.documentElement.lang || 'en')
+  const nameOf = useMemo(() => countryNamer(resolvedLocale), [resolvedLocale])
+  const selected = countryByIso2(country) ?? COUNTRIES[0]
+
+  const options = useMemo(() => {
+    const collator = new Intl.Collator(resolvedLocale)
+    const named = COUNTRIES.map((item) => ({ ...item, name: nameOf(item.iso2) }))
+    const rank = (iso2: string) => {
+      const index = priority.indexOf(iso2)
+      return index === -1 ? priority.length : index
+    }
+    return named.sort(
+      (a, b) => rank(a.iso2) - rank(b.iso2) || collator.compare(a.name, b.name),
+    )
+  }, [nameOf, priority, resolvedLocale])
+
+  const matches = useMemo(() => {
+    const needle = query.trim().toLocaleLowerCase(resolvedLocale)
+    if (!needle) return options
+    const digits = toAsciiDigits(needle)
+    return options.filter(
+      (item) =>
+        item.name.toLocaleLowerCase(resolvedLocale).includes(needle) ||
+        item.iso2.toLowerCase().includes(needle) ||
+        (digits ? item.dial.startsWith(digits) : false),
+    )
+  }, [options, query, resolvedLocale])
+
+  useEffect(() => {
+    if (!open) return
+    search.current?.focus()
+    const dismiss = (event: MouseEvent) => {
+      if (!shell.current?.contains(event.target as Node)) setOpen(false)
+    }
+    const escape = (event: globalThis.KeyboardEvent) => {
+      if (event.key !== 'Escape') return
+      setOpen(false)
+      trigger.current?.focus()
+    }
+    document.addEventListener('mousedown', dismiss)
+    document.addEventListener('keydown', escape)
+    return () => {
+      document.removeEventListener('mousedown', dismiss)
+      document.removeEventListener('keydown', escape)
+    }
+  }, [open])
+
+  const choose = (iso2: string) => {
+    onCountryChange(iso2)
+    setOpen(false)
+    setQuery('')
+    trigger.current?.focus()
+  }
+
+  return (
+    <div className={cn('nim-field', error && 'nim-field--invalid', className)}>
+      {label ? (
+        <label className="nim-field__label" htmlFor={controlId}>
+          {label}
+          {required ? (
+            <span aria-hidden="true" className="nim-field__required">
+              *
+            </span>
+          ) : null}
+        </label>
+      ) : null}
+
+      <div className="nim-phone" ref={shell}>
+        <div className="nim-phone__shell" dir="ltr">
+          <button
+            aria-expanded={open}
+            aria-haspopup="listbox"
+            aria-label={`${text.pickCountry}: ${nameOf(selected.iso2)} +${selected.dial}`}
+            className="nim-phone__country"
+            onClick={() => setOpen((was) => !was)}
+            ref={trigger}
+            type="button"
+          >
+            <span aria-hidden="true" className="nim-phone__flag">
+              {selected.flag}
+            </span>
+            <span className="nim-phone__dial">+{selected.dial}</span>
+            <Icon className="nim-phone__caret" name="chevron-down" size="xs" />
+          </button>
+
+          <input
+            aria-describedby={[errorId, hintId].filter(Boolean).join(' ') || undefined}
+            aria-invalid={error ? true : undefined}
+            autoComplete="tel-national"
+            className="nim-phone__input"
+            enterKeyHint="go"
+            id={controlId}
+            inputMode="tel"
+            onChange={(event) => onChange(toAsciiDigits(event.target.value))}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') onSubmit?.()
+            }}
+            placeholder={placeholder}
+            required={required}
+            type="tel"
+            value={value}
+          />
+        </div>
+
+        {open ? (
+          <div className="nim-phone__picker">
+            <div className="nim-phone__search">
+              <Icon name="search" size="sm" />
+              <input
+                aria-label={text.search}
+                className="nim-phone__search-input"
+                onChange={(event) => setQuery(event.target.value)}
+                placeholder={text.search}
+                ref={search}
+                type="search"
+                value={query}
+              />
+            </div>
+            <ul className="nim-phone__list" role="listbox">
+              {matches.map((item) => (
+                <li key={item.iso2}>
+                  <button
+                    aria-selected={item.iso2 === selected.iso2}
+                    className="nim-phone__option"
+                    onClick={() => choose(item.iso2)}
+                    role="option"
+                    type="button"
+                  >
+                    <span aria-hidden="true" className="nim-phone__flag">
+                      {item.flag}
+                    </span>
+                    <span className="nim-phone__name">{item.name}</span>
+                    <span className="nim-phone__option-dial" dir="ltr">
+                      +{item.dial}
+                    </span>
+                  </button>
+                </li>
+              ))}
+              {matches.length === 0 ? <li className="nim-phone__empty">{text.noMatch}</li> : null}
+            </ul>
+          </div>
+        ) : null}
+      </div>
+
+      {error ? (
+        <p className="nim-field__error" id={errorId}>
+          {error}
+        </p>
+      ) : null}
+      {hint && !error ? (
+        <p className="nim-field__hint" id={hintId}>
+          {hint}
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+/** `+${dial}${national}` — what an auth API actually wants. */
+export function toE164(country: string, national: string): string {
+  const dial = countryByIso2(country)?.dial ?? ''
+  return `+${dial}${toAsciiDigits(national).replace(/^0+/, '')}`
+}

package/src/components/plan-card.tsx

@@ -0,0 +1,124 @@
+import type { ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export interface PlanFeature {
+  label: ReactNode
+  /** `included` is shipped, `pending` is bought but not released yet, and
+      `excluded` is what this plan does not get. All three are worth showing:
+      a plan card that lists only wins tells the viewer nothing to choose on. */
+  state?: 'excluded' | 'included' | 'pending'
+  /** A short status word beside a pending row — "soon", "beta". */
+  note?: string
+}
+
+export interface PlanCardProps {
+  /** The one plan being recommended. At most one card in a set. */
+  badge?: string
+  className?: string
+  features?: PlanFeature[]
+  icon?: IconName
+  /** The headline figure, already formatted and localised by the caller. */
+  price: ReactNode
+  /** What the price buys — "per month", "6 months". */
+  priceCaption?: ReactNode
+  /** The comparable unit price, so plans of different lengths can be read
+      against each other. */
+  secondary?: { caption: ReactNode; value: ReactNode }
+  name: ReactNode
+  onSelect?: () => void
+  selected?: boolean
+  tagline?: ReactNode
+}
+
+const STATE_ICON: Record<NonNullable<PlanFeature['state']>, IconName> = {
+  excluded: 'minus',
+  included: 'check',
+  pending: 'clock',
+}
+
+/**
+ * One subscription tier, as a card the viewer chooses.
+ *
+ * The whole card is the control — a radio hidden behind a tap target the size
+ * of a fingernail is the reason plan pickers feel fussy — so it renders as a
+ * `<button>` with `aria-pressed` when selectable, and as a plain plate when it
+ * is only being displayed.
+ *
+ * Prices are `ReactNode` rather than numbers: currency, digit shaping and
+ * grouping are the product's locale decisions, and a kit that formats them
+ * would be wrong in Persian first.
+ */
+export function PlanCard({
+  badge,
+  className,
+  features = [],
+  icon,
+  name,
+  onSelect,
+  price,
+  priceCaption,
+  secondary,
+  selected = false,
+  tagline,
+}: PlanCardProps) {
+  const body = (
+    <>
+      <div className="nim-plan__top">
+        {icon ? (
+          <span className="nim-plan__icon">
+            <Icon name={icon} size="md" />
+          </span>
+        ) : null}
+        <div className="nim-plan__heading">
+          <span className="nim-plan__name">{name}</span>
+          {tagline ? <span className="nim-plan__tagline">{tagline}</span> : null}
+        </div>
+        {badge ? <span className="nim-plan__badge">{badge}</span> : null}
+        {onSelect ? (
+          <span aria-hidden="true" className="nim-plan__radio">
+            {selected ? <Icon name="check" size="xs" /> : null}
+          </span>
+        ) : null}
+      </div>
+
+      <div className="nim-plan__price-box">
+        <div>
+          {priceCaption ? <span className="nim-plan__price-caption">{priceCaption}</span> : null}
+          <strong className="nim-plan__price">{price}</strong>
+        </div>
+        {secondary ? (
+          <div className="nim-plan__secondary">
+            <span className="nim-plan__price-caption">{secondary.caption}</span>
+            <strong className="nim-plan__secondary-value">{secondary.value}</strong>
+          </div>
+        ) : null}
+      </div>
+
+      {features.length ? (
+        <ul className="nim-plan__features">
+          {features.map((feature, index) => {
+            const state = feature.state ?? 'included'
+            return (
+              <li className="nim-plan__feature" data-state={state} key={index}>
+                <Icon name={STATE_ICON[state]} size="xs" />
+                <span className="nim-plan__feature-label">{feature.label}</span>
+                {feature.note ? <span className="nim-plan__feature-note">{feature.note}</span> : null}
+              </li>
+            )
+          })}
+        </ul>
+      ) : null}
+    </>
+  )
+
+  const classes = cn('nim-plan', selected && 'nim-plan--selected', className)
+
+  return onSelect ? (
+    <button aria-pressed={selected} className={classes} onClick={onSelect} type="button">
+      {body}
+    </button>
+  ) : (
+    <article className={classes}>{body}</article>
+  )
+}

package/src/components/plan-picker.tsx

@@ -0,0 +1,144 @@
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import { Button } from '@/components/button'
+import { PlanCard, type PlanCardProps } from '@/components/plan-card'
+import { Segmented } from '@/components/segmented'
+import { cn } from '@/lib/cn'
+
+export interface BillingCycle {
+  id: string
+  label: string
+  /** "Save 15%" — the reason to pick the longer commitment. */
+  note?: string
+}
+
+export interface PlanOffer
+  extends Omit<PlanCardProps, 'onSelect' | 'price' | 'secondary' | 'selected'> {
+  id: string
+  /** Price per billing cycle, keyed by cycle id. Already formatted: currency
+      and digit shaping are the product's locale decision, not the kit's. */
+  prices: Record<string, { monthly?: ReactNode; price: ReactNode }>
+}
+
+export interface PlanPickerProps {
+  className?: string
+  /** Billing periods. One cycle, or none at all, hides the switch. */
+  cycles?: BillingCycle[]
+  cycle?: string
+  defaultCycle?: string
+  defaultPlan?: string
+  labels?: { cycle: string; monthly: string; price: string }
+  /** Fine print under the action — renewal terms, store rules. */
+  note?: ReactNode
+  onCycleChange?: (cycle: string) => void
+  onPlanChange?: (plan: string) => void
+  /** Fires with the chosen plan and cycle. Payment is the app's business. */
+  onSubmit?: (plan: string, cycle: string) => void
+  plans: PlanOffer[]
+  plan?: string
+  submitLabel?: string
+}
+
+const DEFAULT_LABELS = {
+  cycle: 'Billing period',
+  monthly: 'Per month',
+  price: 'This package',
+}
+
+/**
+ * The subscription screen: billing period, the tiers, and one action.
+ *
+ * Ready to mount — it holds the selection, keeps the cycle and the prices in
+ * step, and hands `onSubmit` the pair the checkout needs. Pass `plan`/`cycle`
+ * to drive it from outside instead, e.g. when a deep link opens the screen on
+ * a specific tier.
+ *
+ * It deliberately does not take a payment handler, a store SDK, or a currency:
+ * a plan picker that also knows how to charge is two screens welded together,
+ * and only one of them is the same across products.
+ */
+export function PlanPicker({
+  className,
+  cycle,
+  cycles = [],
+  defaultCycle,
+  defaultPlan,
+  labels,
+  note,
+  onCycleChange,
+  onPlanChange,
+  onSubmit,
+  plan,
+  plans,
+  submitLabel,
+}: PlanPickerProps) {
+  const text = { ...DEFAULT_LABELS, ...labels }
+  const [ownCycle, setOwnCycle] = useState(defaultCycle ?? cycles[0]?.id ?? '')
+  const [ownPlan, setOwnPlan] = useState(defaultPlan ?? plans[0]?.id ?? '')
+  const activeCycle = cycle ?? ownCycle
+  const activePlan = plan ?? ownPlan
+
+  const choose = (next: string) => {
+    setOwnPlan(next)
+    onPlanChange?.(next)
+  }
+
+  const switchCycle = (next: string) => {
+    setOwnCycle(next)
+    onCycleChange?.(next)
+  }
+
+  const current = cycles.find((item) => item.id === activeCycle)
+
+  return (
+    <section className={cn('nim-plan-picker', className)}>
+      {cycles.length > 1 ? (
+        <div className="nim-plan-picker__cycles">
+          <Segmented
+            fullWidth
+            label={text.cycle}
+            onChange={switchCycle}
+            options={cycles.map((item) => ({ label: item.label, value: item.id }))}
+            value={activeCycle}
+          />
+          {current?.note ? <p className="nim-plan-picker__save">{current.note}</p> : null}
+        </div>
+      ) : null}
+
+      <div className="nim-plan-picker__plans">
+        {plans.map(({ id, prices, ...card }) => {
+          const price = prices[activeCycle] ?? Object.values(prices)[0]
+          return (
+            <PlanCard
+              {...card}
+              key={id}
+              onSelect={() => choose(id)}
+              price={price?.price ?? ''}
+              priceCaption={text.price}
+              secondary={
+                price?.monthly === undefined
+                  ? undefined
+                  : { caption: text.monthly, value: price.monthly }
+              }
+              selected={id === activePlan}
+            />
+          )
+        })}
+      </div>
+
+      {submitLabel ? (
+        <div className="nim-plan-picker__foot">
+          <Button
+            fullWidth
+            onClick={() => onSubmit?.(activePlan, activeCycle)}
+            size="lg"
+            variant="accent"
+          >
+            {submitLabel}
+          </Button>
+          {note ? <p className="nim-plan-picker__note">{note}</p> : null}
+        </div>
+      ) : null}
+    </section>
+  )
+}

package/src/components/profile-header.tsx

@@ -0,0 +1,134 @@
+import type { CSSProperties, ReactNode } from 'react'
+import { cn } from '@/lib/cn'
+
+export interface AvatarRingProps {
+  className?: string
+  /** What the ring is measuring, for assistive tech. */
+  label: string
+  /** Initials, or a small caption under them. */
+  caption?: ReactNode
+  /** Image URL. Falls back to `initials` when absent or broken. */
+  src?: string
+  initials: string
+  size?: number
+  /** 0–100. The ring is the progress; the number belongs in the caption. */
+  value: number
+}
+
+/**
+ * An avatar wearing a progress ring: profile completion, a skin score, a
+ * streak — one figure the viewer is meant to want to finish.
+ *
+ * The ring is an SVG arc rather than a conic gradient so it keeps a rounded
+ * cap and stays crisp at any size, and it carries `role="img"` with the label,
+ * because the arc is the only place the value is stated for a sighted viewer.
+ */
+export function AvatarRing({
+  caption,
+  className,
+  initials,
+  label,
+  size = 96,
+  src,
+  value,
+}: AvatarRingProps) {
+  const stroke = Math.max(4, Math.round(size * 0.05))
+  const radius = (size - stroke) / 2
+  const circumference = 2 * Math.PI * radius
+  const filled = (Math.min(100, Math.max(0, value)) / 100) * circumference
+
+  return (
+    <div
+      aria-label={label}
+      className={cn('nim-avatar-ring', className)}
+      role="img"
+      style={{ '--nim-ring-size': `${size}px`, '--nim-ring-stroke': `${stroke}px` } as CSSProperties}
+    >
+      <svg aria-hidden="true" className="nim-avatar-ring__arc" viewBox={`0 0 ${size} ${size}`}>
+        <circle
+          className="nim-avatar-ring__track"
+          cx={size / 2}
+          cy={size / 2}
+          fill="none"
+          r={radius}
+          strokeWidth={stroke}
+        />
+        <circle
+          className="nim-avatar-ring__fill"
+          cx={size / 2}
+          cy={size / 2}
+          fill="none"
+          r={radius}
+          strokeDasharray={`${filled} ${circumference}`}
+          strokeLinecap="round"
+          strokeWidth={stroke}
+        />
+      </svg>
+      <span className="nim-avatar-ring__face">
+        {src ? (
+          <img alt="" className="nim-avatar-ring__image" src={src} />
+        ) : (
+          <span className="nim-avatar-ring__initials">{initials}</span>
+        )}
+        {caption && !src ? <span className="nim-avatar-ring__caption">{caption}</span> : null}
+      </span>
+    </div>
+  )
+}
+
+export interface ProfileHeaderProps {
+  /** The row of quick figures under the identity block. */
+  stats?: { label: ReactNode; value: ReactNode }[]
+  /** Small pills: plan, skin type, billing cycle. */
+  chips?: ReactNode
+  actions?: ReactNode
+  avatar: ReactNode
+  className?: string
+  /** The line above the name — "vlora account", the tenant, the role. */
+  eyebrow?: ReactNode
+  name: ReactNode
+}
+
+/**
+ * The plate at the top of a profile: who this is, what they have, and the two
+ * things they should do next.
+ *
+ * It is a header, not a dashboard. Anything that needs a chart or a list goes
+ * in the sections beneath it — this block stays readable at a glance, which is
+ * the only reason it earns the space it takes.
+ */
+export function ProfileHeader({
+  actions,
+  avatar,
+  chips,
+  className,
+  eyebrow,
+  name,
+  stats = [],
+}: ProfileHeaderProps) {
+  return (
+    <section className={cn('nim-profile-header', className)}>
+      <div className="nim-profile-header__identity">
+        {avatar}
+        <div className="nim-profile-header__who">
+          {eyebrow ? <p className="nim-profile-header__eyebrow">{eyebrow}</p> : null}
+          <h1 className="nim-profile-header__name">{name}</h1>
+          {chips ? <div className="nim-profile-header__chips">{chips}</div> : null}
+        </div>
+      </div>
+
+      {stats.length ? (
+        <dl className="nim-profile-header__stats">
+          {stats.map((stat, index) => (
+            <div className="nim-profile-header__stat" key={index}>
+              <dt className="nim-profile-header__stat-label">{stat.label}</dt>
+              <dd className="nim-profile-header__stat-value">{stat.value}</dd>
+            </div>
+          ))}
+        </dl>
+      ) : null}
+
+      {actions ? <div className="nim-profile-header__actions">{actions}</div> : null}
+    </section>
+  )
+}