@expokit/cli 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,9 @@
 # @expokit/cli
 
 [![npm](https://img.shields.io/npm/v/@expokit/cli.svg)](https://www.npmjs.com/package/@expokit/cli)
+[![CI](https://github.com/Anshkaran7/expokit/actions/workflows/ci.yml/badge.svg)](https://github.com/Anshkaran7/expokit/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Anshkaran7/expokit/badge)](https://scorecard.dev/viewer/?uri=github.com/Anshkaran7/expokit)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
 The CLI for **[ExpoKit](https://expokit.karandev.in)** — animated UI components for Expo and React Native. It copies
@@ -28,6 +31,17 @@ See every component: `npx @expokit/cli@latest add --list`
 Everything else — live previews, props, installation, theming, Pro, AI / MCP setup and help — is on
 **[expokit.karandev.in](https://expokit.karandev.in/docs)**.
 
+## Security
+
+- **No dependencies, no install scripts, no telemetry.**
+- **Writes only inside your app** — `components.json`, the `@/*` alias in `tsconfig.json` and the component files.
+  `--dry-run` shows every change first; `add` never overwrites a file you changed unless you pass `--force`.
+- **Free components need no network** — they ship inside this package. Pro components are downloaded over HTTPS from
+  expokit.karandev.in; your token is stored readable only by you, sent only to that site and never through a redirect.
+- **Runs one command:** `npx expo install` for the packages a component needs.
+
+Report a vulnerability privately: [SECURITY.md](https://github.com/Anshkaran7/expokit/blob/main/SECURITY.md).
+
 ## License
 
 MIT

package/bin/expo-kit.js

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
+import { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
 import {
   CliError,
@@ -36,6 +37,8 @@ const REGISTRY_DIR = path.join(PACKAGE_ROOT, 'registry');
 /** Website that serves Pro items (GET /api/registry/<name>) and issues CLI tokens (/account). */
 const SITE_URL = (process.env.EXPO_KIT_URL || DEFAULT_SITE_URL).replace(/\/+$/, '');
 const CREDENTIALS_DIR = path.join(os.homedir(), '.expo-kit');
+/** How users run the CLI. Bare `expo-kit` only works once installed, and `npx expo-kit` would fetch an unrelated npm package. */
+const RUN = 'npx @expokit/cli@latest';
 const CREDENTIALS_PATH = path.join(CREDENTIALS_DIR, 'credentials.json');
 
 const DEFAULT_ALIASES = {
@@ -295,7 +298,7 @@ async function loadRegistryItem(name) {
   const resolved = resolveRegistryName(name);
   const meta = isValidItemName(resolved) ? readMeta(resolved) : null;
   if (!meta) {
-    if (!isValidItemName(resolved)) fail(`Unknown item "${name}". Run: expo-kit add --list`);
+    if (!isValidItemName(resolved)) fail(`Unknown item "${name}". Run: ${RUN} add --list`);
     // Not in this package's registry — it may be newer than this CLI. Ask the site before giving up.
     const remoteMeta = { name: resolved, title: resolved, tier: 'pro', dependencies: [], unknownLocally: true };
     return stageRemoteItem(remoteMeta, resolved);
@@ -317,7 +320,7 @@ function listRegistry() {
     console.log(`  • ${meta.name.padEnd(18)} ${tag}${meta.title}`);
   }
   console.log('');
-  if (pro) log(`PRO items need an ExpoKit Pro plan — run \`expo-kit login\` (tokens: ${SITE_URL}/account).\n`);
+  if (pro) log(`PRO items need an ExpoKit Pro plan — run \`${RUN} login\` (tokens: ${SITE_URL}/account).\n`);
 }
 
 // ---------------------------------------------------------------------------
@@ -342,9 +345,9 @@ function assertTokenTarget(creds) {
   const target = new URL(SITE_URL).origin;
   throw new CliError(
     creds.fromEnv
-      ? `Refusing to send EXPO_KIT_TOKEN to ${target} (only ${DEFAULT_SITE_URL} or localhost receive it). Unset EXPO_KIT_URL, or run \`expo-kit login\` against that site.`
+      ? `Refusing to send EXPO_KIT_TOKEN to ${target} (only ${DEFAULT_SITE_URL} or localhost receive it). Unset EXPO_KIT_URL, or run \`${RUN} login\` against that site.`
       : `Your saved token was created for ${creds.url ?? DEFAULT_SITE_URL}, so it won't be sent to ${target}. ` +
-        `Unset EXPO_KIT_URL, or run \`expo-kit login\` with EXPO_KIT_URL=${target} to save a token for that site.`
+        `Unset EXPO_KIT_URL, or run \`${RUN} login\` with EXPO_KIT_URL=${target} to save a token for that site.`
   );
 }
 
@@ -361,6 +364,8 @@ async function apiGet(pathname, token) {
   try {
     res = await fetch(url, {
       headers: { Accept: 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      // A request that carries the token never follows a redirect: the token goes to SITE_URL's origin only.
+      redirect: token ? 'manual' : 'follow',
       signal: AbortSignal.timeout(20000),
     });
   } catch (e) {
@@ -369,6 +374,14 @@ async function apiGet(pathname, token) {
         'Check your connection (or EXPO_KIT_URL) and try again.'
     );
   }
+  if (token && res.status >= 300 && res.status < 400) {
+    const location = res.headers.get('location');
+    fail(
+      `${SITE_URL} answered with a redirect (HTTP ${res.status}${location ? ` to ${location}` : ''}). ` +
+        `Your token is only sent to ${new URL(SITE_URL).origin} directly, so nothing was sent on. ` +
+        'Check EXPO_KIT_URL, or update the CLI: npx @expokit/cli@latest'
+    );
+  }
   let body = null;
   try {
     body = await res.json();
@@ -388,7 +401,7 @@ async function fetchRemoteItem(name, { unknownLocally = false } = {}) {
   assertTokenTarget(creds);
   const { status, ok, body } = await apiGet(`/api/registry/${encodeURIComponent(name)}`, creds?.token);
   if (ok && body && Array.isArray(body.files)) return body;
-  if (status === 404 && unknownLocally) fail(`Unknown item "${name}". Run: expo-kit add --list`);
+  if (status === 404 && unknownLocally) fail(`Unknown item "${name}". Run: ${RUN} add --list`);
   if (status >= 500) failServerError(status, `downloading "${name}"`);
   if (status === 401 && !creds) {
     fail(
@@ -398,7 +411,7 @@ async function fetchRemoteItem(name, { unknownLocally = false } = {}) {
     );
   }
   if (status === 401) {
-    fail(`Your token (${creds.source}) is invalid or was revoked. Create a new one at ${SITE_URL}/account and run \`expo-kit login\`.`);
+    fail(`Your token (${creds.source}) is invalid or was revoked. Create a new one at ${SITE_URL}/account and run \`${RUN} login\`.`);
   }
   if (status === 403) {
     fail(`"${name}" needs ExpoKit Pro, and your account doesn't have it yet. Upgrade at ${SITE_URL}/pricing.`);
@@ -484,11 +497,20 @@ async function stageRemoteItem(meta, resolved) {
   return { meta: { ...meta, title, dependencies, sharedFiles: [...shared] }, filesRoot: tmp, resolved };
 }
 
-function prompt(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+/** Reads one line from the terminal without echoing it (for tokens), so it stays off the screen and out of scrollback. */
+function promptSecret(question) {
+  process.stdout.write(question);
+  const muted = new Writable({ write: (_chunk, _encoding, done) => done() });
+  const rl = readline.createInterface({ input: process.stdin, output: muted, terminal: true });
   return new Promise((resolve) => {
-    rl.question(question, (answer) => {
+    rl.on('SIGINT', () => {
+      rl.close();
+      process.stdout.write('\n');
+      process.exit(130);
+    });
+    rl.question('', (answer) => {
       rl.close();
+      process.stdout.write('\n');
       resolve(answer.trim());
     });
   });
@@ -498,9 +520,9 @@ async function cmdLogin(args) {
   const i = args.findIndex((a) => a === '--token' || a.startsWith('--token='));
   let token = i === -1 ? '' : args[i].includes('=') ? args[i].slice('--token='.length) : args[i + 1] ?? '';
   if (!token) {
-    log(`Create a CLI token at ${SITE_URL}/account (signed in), then paste it here.`);
-    if (!process.stdin.isTTY) fail('No token given. Use: expo-kit login --token <token>');
-    token = await prompt('Token: ');
+    log(`Create a CLI token at ${SITE_URL}/account (signed in), then paste it here (it won't be shown).`);
+    if (!process.stdin.isTTY) fail(`No token given. Use: ${RUN} login --token <token>`);
+    token = await promptSecret('Token: ');
   }
   token = token.trim();
   if (!token) fail('No token given.');
@@ -532,7 +554,7 @@ function cmdLogout() {
 
 async function cmdWhoami() {
   const creds = readCredentials();
-  if (!creds) fail(`Not logged in. Run: expo-kit login (tokens: ${SITE_URL}/account)`);
+  if (!creds) fail(`Not logged in. Run: ${RUN} login (tokens: ${SITE_URL}/account)`);
   assertTokenTarget(creds);
   const { status, ok, body } = await apiGet('/api/cli/whoami', creds.token);
   if (status === 401) fail(`Your token (${creds.source}) is invalid or was revoked. Create a new one at ${SITE_URL}/account.`);
@@ -740,9 +762,43 @@ function runExpoInstall(projectRoot, packages, dryRun) {
   return true;
 }
 
-function cmdInit(cwd, flags) {
+/** Folder names `init <dir>` will create: no paths, no spaces, nothing a shell could misread. */
+const SAFE_APP_DIR = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** `init my-app`: a new Expo app (create-expo-app) in ./my-app, then the usual init inside it. */
+function createExpoApp(cwd, dir, flags) {
+  if (!SAFE_APP_DIR.test(dir)) fail(`"${dir}" is not a valid folder name (letters, numbers, ".", "_" and "-").`);
+  const target = path.join(cwd, dir);
+  if (fs.existsSync(target) && fs.readdirSync(target).length) fail(`./${dir} already exists and is not empty.`);
+  if (flags.dryRun) {
+    log(`Would run: npx create-expo-app@latest ${dir} --yes`);
+    log(`Would then set up ExpoKit in ./${dir}`);
+    return null;
+  }
+  log(`Creating a new Expo app in ./${dir}…`);
+  const result = spawnSync('npx', ['create-expo-app@latest', dir, '--yes'], {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  if (result.status !== 0 || !fs.existsSync(path.join(target, 'package.json'))) {
+    fail(`create-expo-app failed. Create the app yourself (npx create-expo-app@latest ${dir}), then run ${RUN} init inside it.`);
+  }
+  return target;
+}
+
+function cmdInit(cwd, flags, dir) {
+  if (dir) {
+    // Already inside an Expo app: `init <dir>` still means "create a new one there".
+    const target = createExpoApp(cwd, dir, flags);
+    if (!target) return;
+    cmdInit(target, flags);
+    log('');
+    log(`Next: cd ${dir} && npx expo start — then scan the QR with Expo Go.`);
+    return;
+  }
   const projectRoot = findProjectRoot(cwd);
-  if (!projectRoot) fail('Not inside an Expo project (expo dependency not found).');
+  if (!projectRoot) fail(`Not inside an Expo project (expo dependency not found). Start a new app with: ${RUN} init my-app`);
 
   const configPath = path.join(projectRoot, 'components.json');
   if (fs.existsSync(configPath)) {
@@ -777,7 +833,7 @@ function cmdInit(cwd, flags) {
   log(`Created components.json (${layout} layout)`);
 
   ensureExpoRouterMain(projectRoot, false);
-  log('Done. Add items with: npx @expokit/cli add <name>');
+  log(`Done. Add items with: ${RUN} add <name>`);
 }
 
 async function cmdAdd(args, cwd) {
@@ -891,7 +947,7 @@ async function cmdAdd(args, cwd) {
   if (resolved === 'liquidglass-tab') {
     log('Next steps:');
     console.log('  • Edit src/lib/tabs.ts — labels, icon presets, colors, screen text');
-    console.log('  • Run: npx expo-kit doctor');
+    console.log(`  • Run: ${RUN} doctor`);
     console.log('  • Build a dev client: npx expo run:ios (iOS 26 shows real Liquid Glass,');
     console.log('    iOS 18 and older, Android and web get the glass fallback bar)');
     console.log('  • After package updates: npx @expokit/cli@latest update');
@@ -977,7 +1033,7 @@ function cmdDoctor(cwd) {
   log('Checking project…\n');
 
   if (!fs.existsSync(config.configPath)) {
-    warn('Missing components.json — run: expo-kit init');
+    warn(`Missing components.json — run: ${RUN} init`);
     issues += 1;
   } else {
     log('  ✓ components.json');
@@ -996,7 +1052,7 @@ function cmdDoctor(cwd) {
   const usesLiquidGlass = fs.existsSync(tabsPath) || config.installed?.['liquidglass-tab'];
   if (usesLiquidGlass) {
     if (!fs.existsSync(tabsPath)) {
-      warn('No src/lib/tabs.ts — run: expo-kit add liquidglass-tab');
+      warn(`No src/lib/tabs.ts — run: ${RUN} add liquidglass-tab`);
       issues += 1;
     } else {
       log('  ✓ src/lib/tabs.ts');
@@ -1018,7 +1074,7 @@ function cmdDoctor(cwd) {
         const routePath = path.join(tabsDir, fileName);
         if (!fs.existsSync(routePath)) {
           warn(`Missing route for tab "${tabName}": ${path.relative(projectRoot, routePath)}`);
-          console.log(`    Fix: add the file or run expo-kit add liquidglass-tab --force`);
+          console.log(`    Fix: add the file or run ${RUN} add liquidglass-tab --force`);
           issues += 1;
         } else {
           log(`  ✓ route ${path.relative(projectRoot, routePath)}`);
@@ -1073,7 +1129,7 @@ async function cmdMcp(args, cwd) {
   const i = args.findIndex((a) => a === '--client' || a.startsWith('--client='));
   const client = i < 0 ? undefined : args[i].includes('=') ? args[i].split('=')[1] : args[i + 1];
   const names = [...Object.keys(MCP_CLIENTS), 'codex'].join('|');
-  if (!client) fail(`Pick a client: expo-kit mcp init --client <${names}>`);
+  if (!client) fail(`Pick a client: ${RUN} mcp init --client <${names}>`);
 
   if (client === 'codex') {
     log('Codex reads MCP servers from ~/.codex/config.toml (shared by every project). Add:\n');
@@ -1117,7 +1173,7 @@ function printHelp() {
 expo-kit — copy-paste Expo UI (shadcn-style)
 
 Usage:
-  npx @expokit/cli@latest init
+  npx @expokit/cli@latest init [my-app] [--dry-run]
   npx @expokit/cli@latest add <name...> [--dry-run] [--force]
   npx @expokit/cli@latest update [name] [--dry-run] [--force]
   npx @expokit/cli@latest doctor
@@ -1129,6 +1185,7 @@ Usage:
   npx @expokit/cli@latest mcp init --client <claude|cursor|vscode|codex>
 
 Examples:
+  npx @expokit/cli@latest init my-app        new Expo app with ExpoKit set up
   npx @expokit/cli@latest add liquidglass-tab --dry-run
   npx @expokit/cli@latest add liquidglass-tab --force
   npx @expokit/cli@latest update
@@ -1159,10 +1216,15 @@ Config: components.json (created by init)
 async function main(command, rest) {
   switch (command) {
     case 'init': {
-      const { flags } = parseFlags(rest);
-      cmdInit(process.cwd(), flags);
+      const { flags, positional } = parseFlags(rest);
+      if (positional.length > 1) fail(`init takes one folder name: ${RUN} init my-app`);
+      cmdInit(process.cwd(), flags, positional[0]);
       break;
     }
+    case '--version':
+    case '-v':
+      console.log(getPackageVersion());
+      break;
     case 'add':
       await cmdAdd(rest, process.cwd());
       break;

package/bin/mcp.mjs

@@ -179,7 +179,7 @@ function searchItems(catalog, { query }) {
 function viewItem(catalog, registryDir, { name, include_source: includeSource = false }) {
   const it = requireItem(catalog, name);
   const doc = catalog.docs.get(it.name);
-  const out = [`# ${it.title} (${it.name})`, '', it.description, ''];
+  const out = [`# ${it.title} (${it.name})`, '', ...(doc?.summary ? [doc.summary, ''] : []), it.description, ''];
   out.push(`Type: ${it.type} · Tier: ${it.tier === 'pro' ? 'PRO (needs an ExpoKit Pro plan)' : 'free'}${doc?.category ? ` · Category: ${doc.category}` : ''}`);
   if (doc?.aliases?.length) out.push(`Aliases: ${doc.aliases.join(', ')}`);
   out.push('', `Add: \`${addCommand([it.name])}\``);
@@ -195,6 +195,13 @@ function viewItem(catalog, registryDir, { name, include_source: includeSource =
     for (const [prop, type, def, desc] of doc.props) out.push(`| ${cell(prop)} | ${cell(type)} | ${cell(def)} | ${cell(desc)} |`);
   }
 
+  if (doc?.behavior?.length) {
+    out.push('', '## Behaviour & accessibility', '');
+    for (const [label, text] of doc.behavior) out.push(`- **${label}:** ${text}`);
+  }
+
+  if (doc?.usage) out.push('', '## Usage', '', '```tsx', doc.usage.trimEnd(), '```');
+
   if (doc?.examples?.length) {
     out.push('', '## Examples');
     for (const ex of doc.examples) out.push('', `### ${ex.title}`, '', '```tsx', ex.code.trimEnd(), '```');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expokit/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "shadcn-style CLI for Expo — add native UI blocks and components to your app",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,8 @@
     "bin",
     "registry",
     "schema",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "expo",
@@ -35,7 +36,11 @@
   "bugs": {
     "url": "https://github.com/Anshkaran7/expokit/issues"
   },
-  "author": "anshkaran7",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Anshkaran7"
+  },
+  "author": "Karan (anshkaran7) <work@karandev.in>",
   "publishConfig": {
     "access": "public"
   },

package/registry/_docs/accordion.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/accordion.tsx"
   ],
+  "summary": "Sections spring open to their measured height while the chevron turns.",
   "props": [
     [
       "type",
@@ -74,6 +75,21 @@
       "Style for the Accordion's root view (the card in the bordered variant); AccordionItem takes its own."
     ]
   ],
+  "behavior": [
+    [
+      "Touch",
+      "Tap a header to open or close its section. In single mode, opening one closes the other; disabled items don't respond."
+    ],
+    [
+      "Motion",
+      "Content height springs to its measured size, so any content animates smoothly. The chevron turns 180° on the native driver."
+    ],
+    [
+      "Screen readers",
+      "Each header is a button with expanded and disabled state. Content of closed sections is hidden from assistive tech."
+    ]
+  ],
+  "usage": "import { Accordion, AccordionItem } from '@/components/ui/accordion';\n\n<Accordion defaultValue={['shipping']}>\n  <AccordionItem value=\"shipping\" title=\"How long does shipping take?\">\n    Orders leave our warehouse within 24 hours.\n  </AccordionItem>\n  <AccordionItem value=\"returns\" title=\"Can I return an item?\">\n    You have 30 days to send anything back for a full refund.\n  </AccordionItem>\n</Accordion>",
   "examples": [
     {
       "name": "Default",

package/registry/_docs/action-sheet.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/action-sheet.tsx"
   ],
+  "summary": "An iOS-style action sheet that follows your finger and flings away to dismiss.",
   "props": [
     [
       "open / defaultOpen",
@@ -80,6 +81,33 @@
       "Sheet container style."
     ]
   ],
+  "behavior": [
+    [
+      "Touch",
+      "Drag anywhere on the sheet. Pull past a third of its height or flick down to dismiss; pulling up rubber-bands."
+    ],
+    [
+      "Motion",
+      "Springs up over a fading scrim. The exit is quicker than the entry and keeps a fling's momentum."
+    ],
+    [
+      "Reduced motion",
+      "The sheet fades in and out in place instead of sliding up from the bottom."
+    ],
+    [
+      "Haptics",
+      "A light impact when it opens and a selection tick when you pick an action. Turn off with haptics={false}."
+    ],
+    [
+      "Screen readers",
+      "The sheet is a modal view, the title is a header and each row is a button with its label and disabled state."
+    ],
+    [
+      "Keyboard",
+      "Escape closes it on web; the Android back button closes it too."
+    ]
+  ],
+  "usage": "import { useState } from 'react';\nimport { ActionSheet } from '@/components/ui/action-sheet';\n\nconst [open, setOpen] = useState(false);\n<ActionSheet\n  open={open}\n  onOpenChange={setOpen}\n  title=\"Profile photo\"\n  actions={[{ label: 'Take photo' }, { label: 'Remove photo', destructive: true }]}\n/>",
   "examples": [
     {
       "name": "Photo",

package/registry/_docs/alert.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/alert.tsx"
   ],
+  "summary": "An inline banner whose icon draws itself inside a halo, with an optional draining timer.",
   "props": [
     [
       "variant",
@@ -92,6 +93,33 @@
       "Style for the outer animated wrapper (its height collapses on dismiss)."
     ]
   ],
+  "behavior": [
+    [
+      "Motion",
+      "On appear the icon outline draws, the glyph springs in and the halo ripples once. Dismissing collapses the height so content below glides up."
+    ],
+    [
+      "Touch",
+      "With duration set, a hairline drains along the bottom to show the time left. Pressing the alert pauses it."
+    ],
+    [
+      "Reduced motion",
+      "The icon draw, glyph pop and halo ripple jump straight to their finished state."
+    ],
+    [
+      "Haptics",
+      "Success, warning and danger alerts play the matching notification haptic when they appear; info stays silent."
+    ],
+    [
+      "Screen readers",
+      "The card has the alert role in a polite live region. The close button is labelled Dismiss and actions are buttons named by their label."
+    ],
+    [
+      "Web",
+      "Hovering also pauses the auto-dismiss timer."
+    ]
+  ],
+  "usage": "import { Alert } from '@/components/ui/alert';\n\n<Alert\n  variant=\"warning\"\n  title=\"Storage almost full\"\n  description=\"You've used 9.4 GB of your 10 GB plan.\"\n  dismissible\n/>",
   "examples": [
     {
       "name": "Soft",

package/registry/_docs/avatar.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/avatar.tsx"
   ],
+  "summary": "A photo over hashed-colour initials, with presence dots and badges cut into the edge.",
   "props": [
     [
       "src",
@@ -158,6 +159,29 @@
       "Style for the avatar root; AvatarGroup applies it to its row."
     ]
   ],
+  "behavior": [
+    [
+      "Motion",
+      "The photo fades in over the initials, a story ring cross-fades to a hairline once seen, and AvatarGroup springs its faces in with a stagger."
+    ],
+    [
+      "Touch",
+      "With onPress it becomes a button that springs down while pressed."
+    ],
+    [
+      "Reduced motion",
+      "The status pulse, ring spin, press squish and group stagger are skipped, and the seen cross-fade is instant."
+    ],
+    [
+      "Haptics",
+      "A light impact on press when onPress is set. Turn off with haptics={false}."
+    ],
+    [
+      "Screen readers",
+      "Read as an image (or a button when pressable) labelled with the name plus verified, status, notification and story details. A group reads its first names and \"and N more\"."
+    ]
+  ],
+  "usage": "import { Avatar, AvatarGroup } from '@/components/ui/avatar';\n\n<Avatar name=\"Ava Rossi\" src=\"https://i.pravatar.cc/240?img=47\" size=\"lg\" status=\"online\" />\n<AvatarGroup max={3} total={12}>\n  <Avatar name=\"Noah Kim\" />\n  <Avatar name=\"Priya Patel\" />\n  <Avatar name=\"Diego Alvarez\" />\n</AvatarGroup>",
   "examples": [
     {
       "name": "ProfileHeader",

package/registry/_docs/badge.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/badge.tsx"
   ],
+  "summary": "Status pills in four styles that roll, pop and re-tint when their status changes.",
   "props": [
     [
       "variant",
@@ -49,6 +50,12 @@
       "false",
       "Pulsing dot for live states (dot variant)."
     ],
+    [
+      "animateChanges",
+      "boolean",
+      "true",
+      "Roll the label, pop the icon, cross-fade colours and spring the width when they change. Never on mount."
+    ],
     [
       "NotificationBadge.count",
       "number",
@@ -92,26 +99,50 @@
       "Style for the badge pill; NotificationBadge applies it to the anchor wrapper or bare bubble wrapper."
     ]
   ],
+  "behavior": [
+    [
+      "Motion",
+      "On a change the old label rolls up and out as the new one rolls in (per letter for short Latin text), the icon swaps with a scale-and-rotate pop and the pill width springs to fit. Rolls and pops use the native driver; colour and width run on the JS driver on separate views. Nothing animates on mount; animateChanges={false} swaps instantly."
+    ],
+    [
+      "Reduced motion",
+      "Changes swap instantly: no roll, pop, colour fade or width spring. The dot variant's pulse still loops."
+    ],
+    [
+      "Screen readers",
+      "Text labels are one accessible element whose label is always the current text; on Android it is a polite live region so status changes are announced."
+    ],
+    [
+      "Platforms",
+      "React Native Animated and react-native-svg only — iOS, Android, Expo Go and web."
+    ]
+  ],
+  "usage": "import { Badge } from '@/components/ui/badge';\n\nexport function BuildStatus({ done }: { done: boolean }) {\n  return (\n    <Badge tone={done ? 'success' : 'warning'}>{done ? 'Deployed' : 'Building'}</Badge>\n  );\n}",
   "examples": [
     {
       "name": "Variants",
       "title": "Variants",
-      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\n\nconst TONES = ['neutral', 'accent', 'success', 'warning', 'danger'] as const;\n\nexport default function Variants() {\n  return (\n    <View style={{ gap: 10 }}>\n      {(['solid', 'soft', 'outline', 'dot'] as const).map((variant) => (\n        <View key={variant} style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 6 }}>\n          {TONES.map((tone) => (\n            <Badge key={tone} variant={variant} tone={tone}>\n              {tone[0].toUpperCase() + tone.slice(1)}\n            </Badge>\n          ))}\n        </View>\n      ))}\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\n\nconst TONES = ['neutral', 'accent', 'success', 'warning', 'danger'] as const;\n\nexport default function Variants() {\n  return (\n    <View style={{ gap: 10 }}>\n      {(['solid', 'soft', 'outline', 'dot'] as const).map((variant) => (\n        <View key={variant} style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 6 }}>\n          {TONES.map((tone) => (\n            <Badge key={tone} variant={variant} tone={tone}>\n              {tone[0].toUpperCase() + tone.slice(1)}\n            </Badge>\n          ))}\n        </View>\n      ))}\n    </View>\n  );\n}\n"
     },
     {
       "name": "Statuses",
       "title": "Statuses",
-      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Statuses() {\n  const { colors } = useKit();\n  return (\n    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }}>\n      <Badge variant=\"dot\" tone=\"success\" pulse>Live</Badge>\n      <Badge variant=\"soft\" tone=\"success\" icon={<BadgeIcon name=\"package\" color={colors.success} size={14} />}>Paid</Badge>\n      <Badge variant=\"soft\" tone=\"warning\">Pending review</Badge>\n      <Badge variant=\"outline\" tone=\"danger\">Overdue</Badge>\n      <Badge variant=\"solid\" tone=\"accent\" shape=\"rounded\">PRO</Badge>\n      <Badge variant=\"soft\" tone=\"accent\" icon={<BadgeIcon name=\"heart\" color={colors.accent} size={14} />}>Saved</Badge>\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Statuses() {\n  const { colors } = useKit();\n  return (\n    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }}>\n      <Badge variant=\"dot\" tone=\"success\" pulse>Live</Badge>\n      <Badge variant=\"soft\" tone=\"success\" icon={<BadgeIcon name=\"package\" color={colors.success} size={14} />}>Paid</Badge>\n      <Badge variant=\"soft\" tone=\"warning\">Pending review</Badge>\n      <Badge variant=\"outline\" tone=\"danger\">Overdue</Badge>\n      <Badge variant=\"solid\" tone=\"accent\" shape=\"rounded\">PRO</Badge>\n      <Badge variant=\"soft\" tone=\"accent\" icon={<BadgeIcon name=\"heart\" color={colors.accent} size={14} />}>Saved</Badge>\n    </View>\n  );\n}\n"
+    },
+    {
+      "name": "LiveStatus",
+      "title": "Live Status",
+      "code": "import React, { useEffect, useState } from 'react';\nimport { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nconst DEPLOY: { label: string; tone: BadgeTone; icon: BadgeIconName }[] = [\n  { label: 'Queued', tone: 'neutral', icon: 'clock' },\n  { label: 'Building', tone: 'warning', icon: 'refresh' },\n  { label: 'Deployed', tone: 'success', icon: 'check' },\n  { label: 'Failed', tone: 'danger', icon: 'alert' },\n];\n\nexport default function LiveStatus() {\n  const { colors } = useKit();\n  const [step, setStep] = useState(0);\n  useEffect(() => {\n    const id = setInterval(() => setStep((i) => (i + 1) % DEPLOY.length), 1800);\n    return () => clearInterval(id);\n  }, []);\n  const { label, tone, icon } = DEPLOY[step];\n  const tint = { neutral: colors.mutedForeground, accent: colors.accent, success: colors.success, warning: colors.warning, danger: colors.danger }[tone];\n  return (\n    <View style={{ gap: 12 }}>\n      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 10 }}>\n        <Text style={{ fontSize: 15, color: colors.foreground }}>web-checkout #482</Text>\n        <Badge tone={tone} icon={<BadgeIcon name={icon} color={tint} size={14} />}>\n          {label}\n        </Badge>\n      </View>\n      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 10 }}>\n        <Text style={{ fontSize: 15, color: colors.foreground }}>api-gateway #117</Text>\n        <Badge variant=\"solid\" tone={tone} size=\"lg\">\n          {label}\n        </Badge>\n        <Badge variant=\"dot\" tone={tone} pulse={tone === 'warning'}>\n          {label}\n        </Badge>\n      </View>\n    </View>\n  );\n}\n"
     },
     {
       "name": "Sizes",
       "title": "Sizes",
-      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\n\nexport default function Sizes() {\n  return (\n    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>\n      <Badge size=\"sm\" tone=\"accent\">Small</Badge>\n      <Badge size=\"md\" tone=\"accent\">Medium</Badge>\n      <Badge size=\"lg\" tone=\"accent\">Large</Badge>\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\n\nexport default function Sizes() {\n  return (\n    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>\n      <Badge size=\"sm\" tone=\"accent\">Small</Badge>\n      <Badge size=\"md\" tone=\"accent\">Medium</Badge>\n      <Badge size=\"lg\" tone=\"accent\">Large</Badge>\n    </View>\n  );\n}\n"
     },
     {
       "name": "Notifications",
       "title": "Notifications",
-      "code": "import React, { useState } from 'react';\nimport { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Notifications() {\n  const { colors, radius } = useKit();\n  const [count, setCount] = useState(3);\n  return (\n    <View style={{ gap: 18 }}>\n      <View style={{ flexDirection: 'row', gap: 26 }}>\n        <NotificationBadge count={count}>\n          <BadgeIconTile name=\"bell\" backgroundColor={alpha(colors.accent, 0.12)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count * 37} tone=\"accent\">\n          <BadgeIconTile name=\"message\" backgroundColor={alpha(colors.accent, 0.1)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count} dot tone=\"success\">\n          <BadgeIconTile name=\"package\" backgroundColor={alpha(colors.success, 0.12)} color={colors.success} />\n        </NotificationBadge>\n      </View>\n      <View style={{ flexDirection: 'row', gap: 10 }}>\n        {[\n          ['+ New', () => setCount((c) => c + 1)],\n          ['Mark all read', () => setCount(0)],\n        ].map(([label, onPress]) => (\n          <Pressable\n            key={label as string}\n            onPress={onPress as () => void}\n            style={{ paddingHorizontal: 14, height: 36, borderRadius: radius.capsule(36), justifyContent: 'center', backgroundColor: colors.muted }}\n          >\n            <Text style={{ fontWeight: '400', color: colors.foreground }}>{label as string}</Text>\n          </Pressable>\n        ))}\n      </View>\n    </View>\n  );\n}\n"
+      "code": "import React, { useEffect, useState } from 'react';\nimport { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Notifications() {\n  const { colors, radius } = useKit();\n  const [count, setCount] = useState(3);\n  return (\n    <View style={{ gap: 18 }}>\n      <View style={{ flexDirection: 'row', gap: 26 }}>\n        <NotificationBadge count={count}>\n          <BadgeIconTile name=\"bell\" backgroundColor={alpha(colors.accent, 0.12)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count * 37} tone=\"accent\">\n          <BadgeIconTile name=\"message\" backgroundColor={alpha(colors.accent, 0.1)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count} dot tone=\"success\">\n          <BadgeIconTile name=\"package\" backgroundColor={alpha(colors.success, 0.12)} color={colors.success} />\n        </NotificationBadge>\n      </View>\n      <View style={{ flexDirection: 'row', gap: 10 }}>\n        {[\n          ['+ New', () => setCount((c) => c + 1)],\n          ['Mark all read', () => setCount(0)],\n        ].map(([label, onPress]) => (\n          <Pressable\n            key={label as string}\n            onPress={onPress as () => void}\n            style={{ paddingHorizontal: 14, height: 36, borderRadius: radius.capsule(36), justifyContent: 'center', backgroundColor: colors.muted }}\n          >\n            <Text style={{ fontWeight: '400', color: colors.foreground }}>{label as string}</Text>\n          </Pressable>\n        ))}\n      </View>\n    </View>\n  );\n}\n"
     }
   ]
 }

package/registry/_docs/bottom-nav.json

@@ -10,6 +10,7 @@
   "files": [
     "src/components/ui/bottom-nav.tsx"
   ],
+  "summary": "A tab bar whose indicator stretches between tabs, leading edge first.",
   "props": [
     [
       "items",
@@ -84,6 +85,29 @@
       "Style of the bar (the outer shadow view for `floating`)."
     ]
   ],
+  "behavior": [
+    [
+      "Touch",
+      "Tap a tab to select it. Items marked action call onAction instead and never become the active tab."
+    ],
+    [
+      "Motion",
+      "The indicator springs its leading edge first and the trailing edge catches up. Icons morph from outline to filled and badges pop in."
+    ],
+    [
+      "Reduced motion",
+      "The indicator glides with a short timing and no stretch, and icon changes use quick timings instead of springs."
+    ],
+    [
+      "Haptics",
+      "A selection tick on tab change and a light impact on the action button. Turn off with haptics={false}."
+    ],
+    [
+      "Screen readers",
+      "The bar is a tablist and each tab carries selected state, with the badge count in its label. Action items are buttons."
+    ]
+  ],
+  "usage": "import { useState } from 'react';\nimport { BottomNav } from '@/components/ui/bottom-nav';\n\nconst [tab, setTab] = useState('home');\n<BottomNav\n  items={[{ key: 'home', label: 'Home', icon: 'home' }, { key: 'inbox', label: 'Inbox', icon: 'inbox', badge: 3 }]}\n  value={tab}\n  onValueChange={setTab}\n/>",
   "examples": [
     {
       "name": "MinimalClean",