@annondeveloper/ui-kit 0.1.0

package/dist/select-nnBJUO8U.d.ts

@@ -0,0 +1,26 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface SelectProps {
+    /** Currently selected value. */
+    value: string;
+    /** Callback when selection changes. */
+    onValueChange: (v: string) => void;
+    /** Available options. */
+    options: SelectOption[];
+    /** Placeholder text when no value is selected. */
+    placeholder?: string;
+    className?: string;
+    /** Disable the select. */
+    disabled?: boolean;
+}
+/**
+ * @description A themed select dropdown built on Radix UI Select.
+ * Supports dark/light mode via CSS custom property tokens.
+ */
+declare function Select({ value, onValueChange, options, placeholder, className, disabled, }: SelectProps): react_jsx_runtime.JSX.Element;
+
+export { type SelectOption as S, Select as a, type SelectProps as b };

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@annondeveloper/ui-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A React component library with dark/light theming, built on Radix UI, Tailwind CSS v4, and Framer Motion.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./form": {
+      "import": "./dist/form.js",
+      "types": "./dist/form.d.ts"
+    },
+    "./theme.css": "./src/theme.css"
+  },
+  "bin": {
+    "ui-kit": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "src/theme.css",
+    "src/utils.ts",
+    "src/components/"
+  ],
+  "scripts": {
+    "build": "tsup && tsup --config tsup.cli.config.ts && node -e \"const f='dist/cli/index.js',c=require('fs');c.writeFileSync(f,'#!/usr/bin/env node\\n'+c.readFileSync(f,'utf8'))\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test",
+    "release": "npm version patch && git push --follow-tags",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build --output-dir storybook-static"
+  },
+  "peerDependencies": {
+    "@radix-ui/react-alert-dialog": "^1.0.0",
+    "@radix-ui/react-dropdown-menu": "^2.0.0",
+    "@radix-ui/react-popover": "^1.0.0",
+    "@radix-ui/react-select": "^2.0.0",
+    "@radix-ui/react-tooltip": "^1.0.0",
+    "clsx": "^2.0.0",
+    "framer-motion": "^12.0.0",
+    "lucide-react": ">=0.400.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.0.0",
+    "sonner": "^2.0.0",
+    "tailwind-merge": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-hook-form": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@axe-core/react": "^4.11.1",
+    "@radix-ui/react-alert-dialog": "^1.0.0",
+    "@radix-ui/react-dropdown-menu": "^2.0.0",
+    "@radix-ui/react-popover": "^1.0.0",
+    "@radix-ui/react-select": "^2.0.0",
+    "@radix-ui/react-tooltip": "^1.0.0",
+    "@storybook/addon-a11y": "^8.6.18",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/react": "^8.6.18",
+    "@storybook/react-vite": "^8.6.18",
+    "@tanstack/react-table": "^8.0.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest-axe": "^3.5.9",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "axe-core": "^4.11.1",
+    "clsx": "^2.0.0",
+    "framer-motion": "^12.0.0",
+    "jest-axe": "^10.0.0",
+    "jsdom": "^29.0.0",
+    "lucide-react": ">=0.400.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.71.2",
+    "sonner": "^2.0.0",
+    "storybook": "^8.6.18",
+    "tailwind-merge": "^2.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/annondeveloper/ui-kit.git"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "components",
+    "ui-kit",
+    "tailwind",
+    "radix-ui",
+    "framer-motion",
+    "dark-mode",
+    "design-system",
+    "typescript"
+  ],
+  "sideEffects": false
+}

package/src/components/animated-counter.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { AnimatedCounter } from './animated-counter'
+import { Button } from './button'
+
+const meta: Meta<typeof AnimatedCounter> = {
+  title: 'Components/AnimatedCounter',
+  component: AnimatedCounter,
+  tags: ['autodocs'],
+  argTypes: {
+    value: { control: 'number' },
+    duration: { control: { type: 'range', min: 100, max: 2000, step: 100 } },
+  },
+}
+export default meta
+type Story = StoryObj<typeof AnimatedCounter>
+
+export const Default: Story = {
+  args: { value: 1234 },
+}
+
+export const WithFormat: Story = {
+  args: {
+    value: 98.7,
+    format: (n: number) => `${n.toFixed(1)}%`,
+  },
+}
+
+export const Interactive: Story = {
+  render: () => {
+    const [value, setValue] = useState(0)
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
+        <span style={{ fontSize: '2rem', fontWeight: 600, fontVariantNumeric: 'tabular-nums' }}>
+          <AnimatedCounter value={value} />
+        </span>
+        <div style={{ display: 'flex', gap: '0.5rem' }}>
+          <Button size="sm" onClick={() => setValue(v => v + 100)}>+100</Button>
+          <Button size="sm" onClick={() => setValue(v => v + 1000)}>+1000</Button>
+          <Button size="sm" variant="secondary" onClick={() => setValue(0)}>Reset</Button>
+        </div>
+      </div>
+    )
+  },
+}
+
+export const FormattedCurrency: Story = {
+  render: () => {
+    const [value, setValue] = useState(49999)
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
+        <span style={{ fontSize: '2.5rem', fontWeight: 700 }}>
+          <AnimatedCounter
+            value={value}
+            format={(n) => `$${Math.round(n).toLocaleString()}`}
+          />
+        </span>
+        <Button size="sm" onClick={() => setValue(v => v + Math.floor(Math.random() * 10000))}>
+          Add Revenue
+        </Button>
+      </div>
+    )
+  },
+}
+
+export const SlowAnimation: Story = {
+  args: { value: 500, duration: 1500 },
+}

package/src/components/animated-counter.tsx

@@ -0,0 +1,85 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+export interface AnimatedCounterProps {
+  /** The target numeric value to animate to. */
+  value: number
+  /** Animation duration in milliseconds. */
+  duration?: number
+  className?: string
+  /** Custom formatting function for the displayed number. */
+  format?: (n: number) => string
+}
+
+function easeOutCubic(t: number): number {
+  return 1 - Math.pow(1 - t, 3)
+}
+
+/**
+ * @description An animated number counter that transitions smoothly between values
+ * using requestAnimationFrame. Respects prefers-reduced-motion.
+ */
+export function AnimatedCounter({
+  value,
+  duration = 400,
+  className,
+  format,
+}: AnimatedCounterProps) {
+  const reduced = useReducedMotion()
+  const prevRef = useRef(value)
+  const rafRef = useRef<number | null>(null)
+  const [displayed, setDisplayed] = useState(value)
+
+  useEffect(() => {
+    const from = prevRef.current
+    const to = value
+    prevRef.current = value
+
+    if (reduced || from === to) {
+      setDisplayed(to)
+      return
+    }
+
+    const start = performance.now()
+
+    function tick(now: number) {
+      const elapsed = now - start
+      const progress = Math.min(elapsed / duration, 1)
+      const eased = easeOutCubic(progress)
+      const current = from + (to - from) * eased
+
+      setDisplayed(current)
+
+      if (progress < 1) {
+        rafRef.current = requestAnimationFrame(tick)
+      } else {
+        setDisplayed(to)
+      }
+    }
+
+    rafRef.current = requestAnimationFrame(tick)
+
+    return () => {
+      if (rafRef.current !== null) {
+        cancelAnimationFrame(rafRef.current)
+      }
+    }
+  }, [value, duration, reduced])
+
+  const formatted = format
+    ? format(displayed)
+    : Number.isInteger(value)
+      ? Math.round(displayed).toString()
+      : displayed.toFixed(
+          value.toString().split('.')[1]?.length ?? 1
+        )
+
+  return (
+    <span className={cn('tabular-nums', className)}>
+      {formatted}
+    </span>
+  )
+}

package/src/components/avatar.tsx

@@ -0,0 +1,106 @@
+'use client'
+
+import { useState } from 'react'
+import { cn } from '../utils'
+
+export interface AvatarProps {
+  /** Image source URL. */
+  src?: string
+  /** Alt text for the image; used for accessibility. */
+  alt: string
+  /** Initials fallback (e.g. "JD"). Derived from alt if not provided. */
+  fallback?: string
+  /** Size preset. */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  /** Optional status dot overlay. */
+  status?: 'online' | 'offline' | 'busy' | 'away'
+  /** Additional class name for the root element. */
+  className?: string
+}
+
+const sizeClasses: Record<NonNullable<AvatarProps['size']>, { root: string; text: string; dot: string }> = {
+  xs: { root: 'h-6 w-6', text: 'text-[10px]', dot: 'h-2 w-2 -bottom-0 -right-0 ring-1' },
+  sm: { root: 'h-8 w-8', text: 'text-xs', dot: 'h-2.5 w-2.5 -bottom-0.5 -right-0.5 ring-[1.5px]' },
+  md: { root: 'h-10 w-10', text: 'text-sm', dot: 'h-3 w-3 -bottom-0.5 -right-0.5 ring-2' },
+  lg: { root: 'h-12 w-12', text: 'text-base', dot: 'h-3.5 w-3.5 -bottom-0.5 -right-0.5 ring-2' },
+  xl: { root: 'h-16 w-16', text: 'text-lg', dot: 'h-4 w-4 -bottom-0.5 -right-0.5 ring-2' },
+}
+
+const statusColors: Record<NonNullable<AvatarProps['status']>, string> = {
+  online: 'bg-[hsl(var(--status-ok))]',
+  offline: 'bg-[hsl(var(--text-disabled))]',
+  busy: 'bg-[hsl(var(--status-critical))]',
+  away: 'bg-[hsl(var(--status-warning))]',
+}
+
+/**
+ * Derive initials from a name string (max 2 characters).
+ */
+function deriveInitials(name: string): string {
+  const parts = name.trim().split(/\s+/)
+  if (parts.length >= 2) {
+    return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase()
+  }
+  return name.slice(0, 2).toUpperCase()
+}
+
+/**
+ * @description User/entity avatar with image support and initials fallback.
+ * Optional status dot overlay for presence indication.
+ */
+export function Avatar({
+  src,
+  alt,
+  fallback,
+  size = 'md',
+  status,
+  className,
+}: AvatarProps) {
+  const [imgError, setImgError] = useState(false)
+  const s = sizeClasses[size]
+  const initials = fallback ?? deriveInitials(alt)
+  const showImage = src && !imgError
+
+  return (
+    <div className={cn('relative inline-flex shrink-0', className)}>
+      <div
+        className={cn(
+          s.root,
+          'rounded-full overflow-hidden',
+          'flex items-center justify-center',
+          !showImage && 'bg-[hsl(var(--bg-overlay))]',
+        )}
+      >
+        {showImage ? (
+          <img
+            src={src}
+            alt={alt}
+            onError={() => setImgError(true)}
+            className="h-full w-full object-cover"
+          />
+        ) : (
+          <span
+            className={cn(
+              s.text,
+              'font-semibold text-[hsl(var(--text-secondary))] select-none',
+            )}
+          >
+            {initials}
+          </span>
+        )}
+      </div>
+
+      {/* Status dot */}
+      {status && (
+        <span
+          className={cn(
+            'absolute rounded-full ring-[hsl(var(--bg-surface))]',
+            s.dot,
+            statusColors[status],
+          )}
+          aria-label={status}
+        />
+      )}
+    </div>
+  )
+}

package/src/components/badge.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Shield, Zap, AlertTriangle } from 'lucide-react'
+import { Badge, createBadgeVariant } from './badge'
+
+const meta: Meta<typeof Badge> = {
+  title: 'Components/Badge',
+  component: Badge,
+  tags: ['autodocs'],
+  argTypes: {
+    color: {
+      control: 'select',
+      options: ['brand', 'blue', 'green', 'yellow', 'red', 'orange', 'purple', 'pink', 'teal', 'gray'],
+    },
+    size: {
+      control: 'select',
+      options: ['xs', 'sm', 'md'],
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Badge>
+
+export const Default: Story = {
+  args: { children: 'Badge', color: 'gray' },
+}
+
+export const AllColors: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
+      {(['brand', 'blue', 'green', 'yellow', 'red', 'orange', 'purple', 'pink', 'teal', 'gray'] as const).map(c => (
+        <Badge key={c} color={c}>{c}</Badge>
+      ))}
+    </div>
+  ),
+}
+
+export const AllSizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'center' }}>
+      <Badge size="xs" color="blue">XS</Badge>
+      <Badge size="sm" color="blue">SM</Badge>
+      <Badge size="md" color="blue">MD</Badge>
+    </div>
+  ),
+}
+
+export const WithIcon: Story = {
+  args: { children: 'Secured', color: 'green', icon: Shield },
+}
+
+export const WithIconWarning: Story = {
+  args: { children: 'Warning', color: 'yellow', icon: AlertTriangle },
+}
+
+export const CreateBadgeVariantExample: Story = {
+  render: () => {
+    const SeverityBadge = createBadgeVariant({
+      colorMap: { critical: 'red', warning: 'yellow', info: 'blue', ok: 'green' },
+      labelMap: { critical: 'Critical', warning: 'Warning', info: 'Info', ok: 'OK' },
+    })
+    return (
+      <div style={{ display: 'flex', gap: '0.5rem' }}>
+        <SeverityBadge value="critical" />
+        <SeverityBadge value="warning" />
+        <SeverityBadge value="info" />
+        <SeverityBadge value="ok" />
+      </div>
+    )
+  },
+}

package/src/components/badge.tsx

@@ -0,0 +1,97 @@
+'use client'
+
+import { cn } from '../utils'
+import type { LucideIcon } from 'lucide-react'
+
+// ── Theme-safe color presets ────────────────────────────────────────────────
+// All colors use CSS custom properties for dark/light mode compliance.
+
+export type BadgeColor =
+  | 'brand' | 'blue' | 'green' | 'yellow' | 'red' | 'orange'
+  | 'purple' | 'pink' | 'teal' | 'gray'
+
+const COLOR_MAP: Record<BadgeColor, string> = {
+  brand:  'bg-[hsl(var(--brand-primary))]/10 text-[hsl(var(--brand-primary))]',
+  blue:   'bg-[hsl(var(--brand-secondary))]/10 text-[hsl(var(--brand-secondary))]',
+  green:  'bg-[hsl(var(--status-ok))]/10 text-[hsl(var(--status-ok))]',
+  yellow: 'bg-[hsl(var(--status-warning))]/10 text-[hsl(var(--status-warning))]',
+  red:    'bg-[hsl(var(--status-critical))]/10 text-[hsl(var(--status-critical))]',
+  orange: 'bg-[hsl(var(--status-warning))]/15 text-[hsl(var(--status-warning))]',
+  purple: 'bg-[hsl(270,60%,60%)]/10 text-[hsl(270,60%,65%)]',
+  pink:   'bg-[hsl(330,60%,60%)]/10 text-[hsl(330,60%,65%)]',
+  teal:   'bg-[hsl(180,60%,40%)]/10 text-[hsl(180,60%,55%)]',
+  gray:   'bg-[hsl(var(--bg-overlay))] text-[hsl(var(--text-secondary))]',
+}
+
+export interface BadgeProps {
+  children: React.ReactNode
+  /** Color preset for the badge. */
+  color?: BadgeColor
+  /** Optional icon displayed before the label. */
+  icon?: LucideIcon
+  /** Size variant. */
+  size?: 'xs' | 'sm' | 'md'
+  className?: string
+}
+
+/**
+ * @description A themed pill badge with color presets and optional icon.
+ * Supports xs, sm, and md sizes with dark/light mode via CSS tokens.
+ */
+export function Badge({
+  children, color = 'gray', icon: Icon, size = 'sm', className,
+}: BadgeProps) {
+  return (
+    <span className={cn(
+      'inline-flex items-center gap-1 rounded-full font-medium whitespace-nowrap',
+      size === 'xs' && 'px-1.5 py-0.5 text-[10px]',
+      size === 'sm' && 'px-2 py-0.5 text-xs',
+      size === 'md' && 'px-2.5 py-1 text-xs',
+      COLOR_MAP[color],
+      className,
+    )}>
+      {Icon && <Icon className={cn(size === 'xs' ? 'size-2.5' : 'size-3')} />}
+      {children}
+    </span>
+  )
+}
+
+// ── Badge variant factory ──────────────────────────────────────────────────
+
+export interface BadgeVariantConfig<T extends string> {
+  /** Map from value to BadgeColor. */
+  colorMap: Partial<Record<T, BadgeColor>>
+  /** Map from value to display label. Falls back to the value itself. */
+  labelMap?: Partial<Record<T, string>>
+  /** Default color when value is not found in colorMap. */
+  defaultColor?: BadgeColor
+  /** Default size for the badge. */
+  defaultSize?: 'xs' | 'sm' | 'md'
+}
+
+/**
+ * @description Factory function to create domain-specific badge components.
+ * Accepts a color map and optional label map, returns a typed Badge component.
+ *
+ * @example
+ * ```tsx
+ * const SeverityBadge = createBadgeVariant({
+ *   colorMap: { critical: 'red', warning: 'yellow', info: 'blue' },
+ *   labelMap: { critical: 'Critical', warning: 'Warning', info: 'Info' },
+ * })
+ * // Usage: <SeverityBadge value="critical" />
+ * ```
+ */
+export function createBadgeVariant<T extends string>(config: BadgeVariantConfig<T>) {
+  const { colorMap, labelMap, defaultColor = 'gray', defaultSize = 'xs' } = config
+
+  return function VariantBadge({ value, className }: { value: T; className?: string }) {
+    const color = colorMap[value] ?? defaultColor
+    const label = labelMap?.[value] ?? value.replace(/_/g, ' ')
+    return (
+      <Badge color={color} size={defaultSize} className={className}>
+        {label}
+      </Badge>
+    )
+  }
+}

package/src/components/button.stories.tsx

@@ -0,0 +1,101 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Download, Plus, Trash2 } from 'lucide-react'
+import { Button } from './button'
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'danger', 'outline', 'ghost'],
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'icon'],
+    },
+    loading: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Button>
+
+export const Default: Story = {
+  args: { children: 'Button' },
+}
+
+export const Primary: Story = {
+  args: { variant: 'primary', children: 'Primary' },
+}
+
+export const Secondary: Story = {
+  args: { variant: 'secondary', children: 'Secondary' },
+}
+
+export const Danger: Story = {
+  args: { variant: 'danger', children: 'Delete' },
+}
+
+export const Outline: Story = {
+  args: { variant: 'outline', children: 'Outline' },
+}
+
+export const Ghost: Story = {
+  args: { variant: 'ghost', children: 'Ghost' },
+}
+
+export const Small: Story = {
+  args: { size: 'sm', children: 'Small' },
+}
+
+export const Large: Story = {
+  args: { size: 'lg', children: 'Large' },
+}
+
+export const IconSize: Story = {
+  args: { size: 'icon', children: <Plus className="h-4 w-4" /> },
+}
+
+export const Loading: Story = {
+  args: { loading: true, children: 'Saving...' },
+}
+
+export const Disabled: Story = {
+  args: { disabled: true, children: 'Disabled' },
+}
+
+export const WithIcon: Story = {
+  args: { children: <><Download className="h-4 w-4" /> Export</> },
+}
+
+export const DangerWithIcon: Story = {
+  args: {
+    variant: 'danger',
+    children: <><Trash2 className="h-4 w-4" /> Delete</>,
+  },
+}
+
+export const AllVariants: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.75rem', flexWrap: 'wrap', alignItems: 'center' }}>
+      <Button variant="primary">Primary</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="danger">Danger</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="ghost">Ghost</Button>
+    </div>
+  ),
+}
+
+export const AllSizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.75rem', alignItems: 'center' }}>
+      <Button size="sm">Small</Button>
+      <Button size="md">Medium</Button>
+      <Button size="lg">Large</Button>
+      <Button size="icon"><Plus className="h-4 w-4" /></Button>
+    </div>
+  ),
+}