@nim.zone/ui 0.6.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@nim.zone/ui",
+  "version": "0.6.0",
+  "type": "module",
+  "description": "nim — the front-end design system and UI kit shared across nim products.",
+  "keywords": [
+    "design-system",
+    "ui-kit",
+    "react",
+    "components",
+    "tokens",
+    "rtl",
+    "persian",
+    "tailwind",
+    "accessible"
+  ],
+  "author": "Nima Sarayan",
+  "license": "MIT",
+  "homepage": "https://nim.zone/uikit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimasrn/nim.git",
+    "directory": "nim-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/nimasrn/nim/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/nim.js"
+    },
+    "./styles.css": "./dist/nim.css",
+    "./src/theme/index.css": "./src/theme/index.css",
+    "./fonts.css": "./src/theme/fonts.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build --mode lib",
+    "build:docs": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --max-warnings=0",
+    "typecheck": "tsc -b --pretty",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "lucide-react": "^0.544.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/node": "^26.2.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react-swc": "^3.9.0",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^16.4.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwindcss": "^4.2.2",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.59.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}

package/src/components/admin-shell.tsx

@@ -0,0 +1,338 @@
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { IconButton } from '@/components/icon-button'
+import { cn } from '@/lib/cn'
+
+export interface AdminNavItem {
+  href?: string
+  icon?: IconName
+  key: string
+  label: ReactNode
+  onSelect?: () => void
+}
+
+export interface AdminNavGroup {
+  icon?: IconName
+  items: AdminNavItem[]
+  key: string
+  label: ReactNode
+}
+
+export interface AdminShellProps {
+  /** Brand mark at the top of the sidebar. */
+  brand?: ReactNode
+  children: ReactNode
+  className?: string
+  /** Under the nav: session state, build version — the things an operator
+      checks before believing a screen. */
+  sidebarFooter?: ReactNode
+  groups: AdminNavGroup[]
+  labels?: { menu: string; nav: string; close: string }
+  /** `key` of the active item. */
+  value: string
+  /** Search field, status pills, the signed-in operator. */
+  toolbar?: ReactNode
+  title?: ReactNode
+}
+
+const DEFAULT_LABELS = {
+  close: 'Close menu',
+  menu: 'Open menu',
+  nav: 'Admin navigation',
+}
+
+/**
+ * The console layout: a grouped sidebar, a topbar, and one scrolling workspace.
+ *
+ * The counterpart to `AppShell`, and deliberately a different component rather
+ * than a `variant`: an operator console is a desktop-first, two-column, deep
+ * hierarchy, and a phone app is a single column with five destinations. Sharing
+ * one component would mean every screen carrying the other's assumptions.
+ *
+ * Below the layout's breakpoint the same sidebar becomes a drawer — the same
+ * markup, not a second nav to keep in sync, which is how the two drift apart.
+ */
+export function AdminShell({
+  brand,
+  children,
+  className,
+  groups,
+  labels,
+  sidebarFooter,
+  title,
+  toolbar,
+  value,
+}: AdminShellProps) {
+  const text = { ...DEFAULT_LABELS, ...labels }
+  const [open, setOpen] = useState(false)
+
+  const nav = (
+    <nav aria-label={text.nav} className="nim-admin__nav">
+      {groups.map((group) => (
+        <div className="nim-admin__group" key={group.key}>
+          <p className="nim-admin__group-label">
+            {group.icon ? <Icon name={group.icon} size="xs" /> : null}
+            {group.label}
+          </p>
+          {group.items.map((item) => {
+            const active = item.key === value
+            const content = (
+              <>
+                {item.icon ? <Icon name={item.icon} size="sm" /> : null}
+                <span>{item.label}</span>
+              </>
+            )
+            const props = {
+              'aria-current': active ? ('page' as const) : undefined,
+              className: 'nim-admin__link',
+              'data-active': active ? 'true' : undefined,
+              onClick: () => {
+                item.onSelect?.()
+                setOpen(false)
+              },
+            }
+            return item.href ? (
+              <a href={item.href} key={item.key} {...props}>
+                {content}
+              </a>
+            ) : (
+              <button key={item.key} type="button" {...props}>
+                {content}
+              </button>
+            )
+          })}
+        </div>
+      ))}
+    </nav>
+  )
+
+  return (
+    <div className={cn('nim-admin', className)} data-drawer={open ? 'open' : undefined}>
+      <aside className="nim-admin__sidebar">
+        {brand ? <div className="nim-admin__brand">{brand}</div> : null}
+        {nav}
+        {sidebarFooter ? <div className="nim-admin__sidebar-foot">{sidebarFooter}</div> : null}
+      </aside>
+
+      {/* The drawer is the sidebar again, not a second navigation: one source
+          for the items, so the two cannot disagree. */}
+      <div className="nim-admin__drawer" hidden={!open}>
+        <div className="nim-admin__scrim" onClick={() => setOpen(false)} />
+        <div className="nim-admin__drawer-panel">
+          <div className="nim-admin__drawer-head">
+            {brand}
+            <IconButton label={text.close} name="close" onClick={() => setOpen(false)} size="sm" />
+          </div>
+          {nav}
+        </div>
+      </div>
+
+      <div className="nim-admin__workspace">
+        <header className="nim-admin__topbar">
+          <IconButton
+            aria-expanded={open}
+            className="nim-admin__menu"
+            label={text.menu}
+            name="menu"
+            onClick={() => setOpen(true)}
+            size="sm"
+          />
+          {title ? <h1 className="nim-admin__title">{title}</h1> : null}
+          {toolbar ? <div className="nim-admin__toolbar">{toolbar}</div> : null}
+        </header>
+        <main className="nim-admin__main">{children}</main>
+      </div>
+    </div>
+  )
+}
+
+export interface DetailHeaderProps {
+  /** Buttons for this record: approve, retry, export. */
+  actions?: ReactNode
+  back?: { href?: string; label: string; onClick?: () => void }
+  className?: string
+  /** Status badge, owner, id — the facts that qualify the title. */
+  meta?: ReactNode
+  status?: ReactNode
+  subtitle?: ReactNode
+  title: ReactNode
+}
+
+/**
+ * The top of a record: where it sits, what it is, and what can be done to it.
+ *
+ * The actions live here rather than at the bottom of the page because an
+ * operator working a queue acts on the record without reading all of it, and a
+ * button below a thousand-row table is a button nobody finds.
+ */
+export function DetailHeader({
+  actions,
+  back,
+  className,
+  meta,
+  status,
+  subtitle,
+  title,
+}: DetailHeaderProps) {
+  return (
+    <header className={cn('nim-detail-header', className)}>
+      {back ? (
+        back.href ? (
+          <a className="nim-detail-header__back" href={back.href}>
+            <Icon name="chevron-back" size="sm" />
+            {back.label}
+          </a>
+        ) : (
+          <button className="nim-detail-header__back" onClick={back.onClick} type="button">
+            <Icon name="chevron-back" size="sm" />
+            {back.label}
+          </button>
+        )
+      ) : null}
+
+      <div className="nim-detail-header__row">
+        <div className="nim-detail-header__text">
+          {/* The status sits beside the heading, not inside it: a badge folded
+              into an <h1> becomes part of the heading's accessible name, and
+              "Payment #48210 Awaiting review" is not what the record is
+              called. */}
+          <div className="nim-detail-header__headline">
+            <h1 className="nim-detail-header__title">{title}</h1>
+            {status ? <span className="nim-detail-header__status">{status}</span> : null}
+          </div>
+          {subtitle ? <p className="nim-detail-header__subtitle">{subtitle}</p> : null}
+          {meta ? <p className="nim-detail-header__meta">{meta}</p> : null}
+        </div>
+        {actions ? <div className="nim-detail-header__actions">{actions}</div> : null}
+      </div>
+    </header>
+  )
+}
+
+export interface FilterChip {
+  key: string
+  label: ReactNode
+  onRemove: () => void
+  /** The value the filter is set to, shown after the label. */
+  value?: ReactNode
+}
+
+export interface FilterChipsProps {
+  chips: FilterChip[]
+  className?: string
+  clearLabel?: string
+  labels?: { remove: (label: string) => string; toolbar: string }
+  onClearAll?: () => void
+}
+
+/**
+ * The filters currently narrowing a table, each removable.
+ *
+ * It renders nothing when there are none — an empty toolbar reserving space
+ * for filters nobody set is the reason these strips feel like chrome. Every
+ * chip states what it removes in its accessible name, because "remove" ten
+ * times over is no name at all.
+ */
+export function FilterChips({
+  chips,
+  className,
+  clearLabel,
+  labels,
+  onClearAll,
+}: FilterChipsProps) {
+  if (chips.length === 0) return null
+  const text = {
+    remove: (label: string) => `Remove filter ${label}`,
+    toolbar: 'Active filters',
+    ...labels,
+  }
+
+  return (
+    <div aria-label={text.toolbar} className={cn('nim-filter-chips', className)} role="toolbar">
+      {chips.map((chip) => (
+        <span className="nim-filter-chip" key={chip.key}>
+          <span className="nim-filter-chip__label">
+            {chip.label}
+            {chip.value !== undefined ? <>: {chip.value}</> : null}
+          </span>
+          <button
+            aria-label={text.remove(typeof chip.label === 'string' ? chip.label : chip.key)}
+            className="nim-filter-chip__remove"
+            onClick={chip.onRemove}
+            type="button"
+          >
+            <Icon name="close" size="xs" />
+          </button>
+        </span>
+      ))}
+      {onClearAll && clearLabel ? (
+        <button className="nim-filter-chips__clear" onClick={onClearAll} type="button">
+          {clearLabel}
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+export interface ActivityEvent {
+  /** What happened, in the product's own words. */
+  action: ReactNode
+  actor?: ReactNode
+  /** ISO timestamp. Formatted here, in the viewer's locale. */
+  at?: string
+  icon?: IconName
+  id: string
+  target?: ReactNode
+  tone?: 'accent' | 'danger' | 'default' | 'success' | 'warning'
+}
+
+export interface ActivityFeedProps {
+  className?: string
+  empty?: ReactNode
+  events: ActivityEvent[]
+  locale?: string
+}
+
+/**
+ * Who did what, most recent first.
+ *
+ * Timestamps are absolute rather than "3 hours ago": an audit trail is read to
+ * reconstruct a sequence, and a relative time that keeps moving is exactly
+ * what you cannot compare two of.
+ */
+export function ActivityFeed({ className, empty, events, locale }: ActivityFeedProps) {
+  const when = new Intl.DateTimeFormat(locale, {
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    month: 'short',
+  })
+
+  if (events.length === 0) {
+    return <div className={cn('nim-activity', className)}>{empty}</div>
+  }
+
+  return (
+    <ol className={cn('nim-activity', className)}>
+      {events.map((event) => (
+        <li className="nim-activity__item" data-tone={event.tone} key={event.id}>
+          <span className="nim-activity__marker">
+            {event.icon ? <Icon name={event.icon} size="xs" /> : null}
+          </span>
+          <div className="nim-activity__body">
+            <p className="nim-activity__action">
+              {event.actor ? <strong>{event.actor}</strong> : null} {event.action}{' '}
+              {event.target ? <span className="nim-activity__target">{event.target}</span> : null}
+            </p>
+            {event.at ? (
+              <time className="nim-activity__time" dateTime={event.at}>
+                {when.format(new Date(event.at))}
+              </time>
+            ) : null}
+          </div>
+        </li>
+      ))}
+    </ol>
+  )
+}

package/src/components/app-shell.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react'
+import { TabBar, type TabBarProps } from '@/components/tab-bar'
+import { cn } from '@/lib/cn'
+
+export interface AppShellProps {
+  children: ReactNode
+  className?: string
+  /** Sticky top row: a title, a back control, an action. Optional — many
+      screens carry their own header inside the content instead. */
+  header?: ReactNode
+  /** The bottom navigation. Omit it on a screen deeper in the stack: a tab bar
+      that stays visible under a detail page invites the viewer to leave. */
+  tabs?: TabBarProps
+}
+
+/**
+ * The frame an app lives in: a sticky header, one scrolling region, and the
+ * tab bar.
+ *
+ * The scroll container is here and nowhere else, which is what makes scroll
+ * restoration, pull-to-refresh and "scroll to top on tab change" one thing to
+ * implement rather than one per screen. The content region reserves room for
+ * the bar it is drawn under, so the last row of a list is never hidden behind
+ * it — the failure this component exists to prevent.
+ */
+export function AppShell({ children, className, header, tabs }: AppShellProps) {
+  return (
+    <div className={cn('nim-app-shell', className)}>
+      {header ? <header className="nim-app-shell__header">{header}</header> : null}
+      <main className="nim-app-shell__content" data-has-tabs={tabs ? 'true' : undefined}>
+        {children}
+      </main>
+      {tabs ? <TabBar {...tabs} /> : null}
+    </div>
+  )
+}

package/src/components/auth-screen.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode } from 'react'
+import { Button } from '@/components/button'
+import { cn } from '@/lib/cn'
+
+export interface AuthScreenProps {
+  /** The form itself: a PhoneField, an OtpInput, a PasswordField. */
+  children: ReactNode
+  className?: string
+  /** Brand mark above the heading. */
+  brand?: ReactNode
+  /** Small link back to the previous step — the OTP step's way home. */
+  back?: { label: string; onClick: () => void }
+  /** Terms line, support link, resend timer. Sits under the CTA. */
+  footer?: ReactNode
+  subtitle?: ReactNode
+  title: ReactNode
+  /** The single primary action. A sign-in screen has exactly one. */
+  action?: { disabled?: boolean; label: string; loading?: boolean; onClick: () => void }
+}
+
+/**
+ * The frame every step of a sign-in flow shares: brand, one heading, one
+ * explanation, the fields, and a single action pinned to the bottom.
+ *
+ * Keeping it one component is what makes the phone step, the code step and the
+ * password step read as one screen changing rather than three screens — and it
+ * puts the CTA in the same place each time, which is the part a thumb learns.
+ */
+export function AuthScreen({
+  action,
+  back,
+  brand,
+  children,
+  className,
+  footer,
+  subtitle,
+  title,
+}: AuthScreenProps) {
+  return (
+    <section className={cn('nim-auth', className)}>
+      {brand ? <div className="nim-auth__brand">{brand}</div> : null}
+
+      <div className="nim-auth__body">
+        {back ? (
+          <Button className="nim-auth__back" iconStart="chevron-back" onClick={back.onClick} size="sm" variant="ghost">
+            {back.label}
+          </Button>
+        ) : null}
+        <h1 className="nim-auth__title">{title}</h1>
+        {subtitle ? <p className="nim-auth__subtitle">{subtitle}</p> : null}
+        <div className="nim-auth__fields">{children}</div>
+      </div>
+
+      <div className="nim-auth__foot">
+        {action ? (
+          <Button
+            disabled={action.disabled}
+            fullWidth
+            loading={action.loading}
+            onClick={action.onClick}
+            size="lg"
+            variant="accent"
+          >
+            {action.label}
+          </Button>
+        ) : null}
+        {footer ? <div className="nim-auth__footer">{footer}</div> : null}
+      </div>
+    </section>
+  )
+}

package/src/components/avatar.tsx

@@ -0,0 +1,32 @@
+import type { HTMLAttributes } from 'react'
+import { cn } from '@/lib/cn'
+
+export type AvatarSize = 'lg' | 'md' | 'sm'
+
+export interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Falls back to initials derived from `name` when no image is supplied. */
+  name: string
+  shape?: 'round' | 'square'
+  size?: AvatarSize
+  src?: string
+}
+
+const initials = (name: string) =>
+  name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? '')
+    .join('')
+
+export function Avatar({ className, name, shape = 'round', size = 'md', src, ...props }: AvatarProps) {
+  return (
+    <span
+      className={cn('nim-avatar', size !== 'md' && `nim-avatar--${size}`, shape === 'square' && 'nim-avatar--square', className)}
+      {...props}
+    >
+      {src ? <img alt="" src={src} /> : <span aria-hidden="true">{initials(name)}</span>}
+      <span className="nim-visually-hidden">{name}</span>
+    </span>
+  )
+}

package/src/components/badge.tsx

@@ -0,0 +1,44 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { cn } from '@/lib/cn'
+
+export type BadgeSize = 'md' | 'sm'
+export type BadgeTone = 'outline' | 'soft' | 'solid'
+export type BadgeVariant = 'accent' | 'danger' | 'info' | 'neutral' | 'success' | 'warning'
+
+export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+  children: ReactNode
+  /** Shows a status dot before the label — for live/among-states meanings. */
+  dot?: boolean
+  pill?: boolean
+  size?: BadgeSize
+  tone?: BadgeTone
+  variant?: BadgeVariant
+}
+
+export function Badge({
+  children,
+  className,
+  dot = false,
+  pill = false,
+  size = 'md',
+  tone = 'soft',
+  variant = 'neutral',
+  ...props
+}: BadgeProps) {
+  return (
+    <span
+      className={cn(
+        'nim-badge',
+        `nim-badge--${variant}`,
+        `nim-badge--${tone}`,
+        size === 'sm' && 'nim-badge--sm',
+        pill && 'nim-badge--pill',
+        className,
+      )}
+      {...props}
+    >
+      {dot ? <span aria-hidden="true" className="nim-badge__dot" /> : null}
+      {children}
+    </span>
+  )
+}

package/src/components/banner.tsx

@@ -0,0 +1,47 @@
+import type { HTMLAttributes, ReactNode } from 'react'
+import { Icon, type IconName } from '@/components/icon'
+import { cn } from '@/lib/cn'
+
+export type BannerTone = 'accent' | 'danger' | 'info' | 'neutral' | 'success' | 'warning'
+
+export interface BannerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  action?: ReactNode
+  children: ReactNode
+  icon?: IconName
+  title?: ReactNode
+  tone?: BannerTone
+}
+
+const DEFAULT_ICON: Record<BannerTone, IconName> = {
+  accent: 'sparkle',
+  danger: 'danger',
+  info: 'info',
+  neutral: 'info',
+  success: 'check-circle',
+  warning: 'alert',
+}
+
+export function Banner({
+  action,
+  children,
+  className,
+  icon,
+  title,
+  tone = 'neutral',
+  ...props
+}: BannerProps) {
+  return (
+    <div
+      className={cn('nim-banner', `nim-banner--${tone}`, className)}
+      role={tone === 'danger' ? 'alert' : 'status'}
+      {...props}
+    >
+      <Icon className="nim-banner__icon" name={icon ?? DEFAULT_ICON[tone]} size="sm" />
+      <div className="nim-banner__content">
+        {title ? <p className="nim-banner__title">{title}</p> : null}
+        <div>{children}</div>
+      </div>
+      {action ? <div>{action}</div> : null}
+    </div>
+  )
+}