@nexub/mcp 8.6.0 → 8.8.0

package/dist/skill/references/components/app-shell.md

@@ -0,0 +1,62 @@
+# App Shell
+
+Full-height application frame: a header row over a body with a sidebar slot and a scrolling main region.
+
+- Package: `@nexub/react` · Category: Layout · Status: stable
+- Import: `import { AppShell } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/app-shell
+
+## When to use
+
+- The outer frame of a product or dashboard: header, side navigation, content
+
+## When not to use
+
+- Marketing or content pages: use `Section` and `Container`
+- A single panel inside a page: use `Grid` or `Flex`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `AppShell.Root` | `compound` |  | Viewport-height grid (`h-screen`): header row, then the body. Override the height with `className` when it is not the whole page. |
+| `AppShell.Header` | `compound` |  | First row, e.g. a `TopNav.Root`. |
+| `AppShell.Body` | `compound` |  | Second row: lays out the sidebar and main side by side. |
+| `AppShell.Sidebar` | `compound` |  | Fixed-width column that scrolls on its own, e.g. a `Sidebar.Root`. |
+| `AppShell.Main` | `compound` |  | The `<main>` landmark: takes the remaining width, scrolls on its own, padded by default. |
+| `...props` | `React.HTMLAttributes<HTMLDivElement>` |  | Every part forwards its ref and HTML attributes. |
+
+## Example: Header, sidebar and main
+
+```tsx
+import { AppShell, Logo, Sidebar, Text, TopNav } from '@nexub/react';
+import { BarChart3, Home, Settings } from '@nexub/icons';
+
+export default function Example() {
+  return (
+    <AppShell.Root className="h-[360px] w-full rounded-shape-container border border-[var(--color-outline-variant)]">
+      <AppShell.Header>
+        <TopNav.Root className="static">
+          <TopNav.Logo><Logo size="sm" /></TopNav.Logo>
+        </TopNav.Root>
+      </AppShell.Header>
+      <AppShell.Body>
+        <AppShell.Sidebar>
+          <Sidebar.Root aria-label="Workspace">
+            <Sidebar.Group>
+              <Sidebar.Item href="#" icon={<Home size="sm" />} active>Overview</Sidebar.Item>
+              <Sidebar.Item href="#" icon={<BarChart3 size="sm" />}>Reports</Sidebar.Item>
+              <Sidebar.Item href="#" icon={<Settings size="sm" />}>Settings</Sidebar.Item>
+            </Sidebar.Group>
+          </Sidebar.Root>
+        </AppShell.Sidebar>
+        <AppShell.Main>
+          <Text size="body-sm" tone="muted">Page content scrolls here, under a fixed header and sidebar.</Text>
+        </AppShell.Main>
+      </AppShell.Body>
+    </AppShell.Root>
+  );
+}
+```
+
+Related: [top-nav](top-nav.md), [sidebar](sidebar.md), [page-header](page-header.md)

package/dist/skill/references/components/aspect-ratio.md

@@ -0,0 +1,60 @@
+# Aspect Ratio
+
+Keeps its content at a fixed width-to-height ratio, for images, video and embeds.
+
+- Package: `@nexub/react` · Category: Layout · Status: stable
+- Import: `import { AspectRatio } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/aspect-ratio
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ratio` | `number` |  | Width divided by height, e.g. `16 / 9` or `1`. Common ratios (1, 16/9, 4/3, 3/2, 21/9, 9/16, 3/4, 2/3) use a class and are strict-CSP safe; any other ratio sets an inline `aspect-ratio` style. |
+| `children` | `ReactNode` |  | Fills the box; give an image `h-full w-full object-cover`. |
+
+## Example: Image
+
+```tsx
+import { AspectRatio } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="w-full max-w-[400px]">
+      <AspectRatio ratio={16 / 9} className="rounded-shape-container">
+        <div className="flex h-full w-full items-center justify-center bg-[var(--color-primary-container)] text-[var(--color-on-primary-container)] text-label-lg">
+          16 : 9
+        </div>
+      </AspectRatio>
+    </div>
+  );
+}
+```
+
+## Example: Ratios
+
+```tsx
+import { AspectRatio } from '@nexub/react';
+
+const ratios = [
+  { ratio: 1, label: '1 : 1' },
+  { ratio: 4 / 3, label: '4 : 3' },
+  { ratio: 3 / 4, label: '3 : 4' },
+];
+
+export default function Example() {
+  return (
+    <div className="grid w-full max-w-[480px] grid-cols-3 items-start gap-3">
+      {ratios.map(({ ratio, label }) => (
+        <AspectRatio key={label} ratio={ratio} className="rounded-shape-container">
+          <div className="flex h-full w-full items-center justify-center bg-[var(--color-surface-container-high)] text-label-md text-[var(--color-on-surface-variant)]">
+            {label}
+          </div>
+        </AspectRatio>
+      ))}
+    </div>
+  );
+}
+```
+
+Related: [media-card](media-card.md), [box](box.md)

package/dist/skill/references/components/check-list.md

@@ -0,0 +1,53 @@
+# Check List
+
+A list with a success tick before each item, for features, plan inclusions and requirements met.
+
+- Package: `@nexub/react` · Category: Data Display · Status: stable
+- Import: `import { CheckList } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/check-list
+
+## When to use
+
+- Listing what a plan or feature includes
+- Confirming requirements that are already met
+
+## When not to use
+
+- Tasks the user can tick off: use `Checkbox`
+- Steps with progress or failures: use `PlanTracker` or `Stepper`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `string[]` |  | Plain-text items. Shorthand for one `CheckListItem` each. |
+| `children` | `ReactNode` |  | `CheckListItem`s, for items with markup. Rendered after `items`. |
+| `CheckListItem children` (required) | `ReactNode` |  | The item text. The tick is decorative (hidden from screen readers). |
+
+## Example: From items
+
+```tsx
+import { CheckList } from '@nexub/react';
+
+export default function Example() {
+  return <CheckList items={['Unlimited projects', 'Priority support', 'Single sign-on (SAML)']} />;
+}
+```
+
+## Example: With CheckListItem
+
+```tsx
+import { CheckList, CheckListItem } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <CheckList aria-label="Password requirements">
+      <CheckListItem>At least 12 characters</CheckListItem>
+      <CheckListItem>One number <span className="text-[var(--color-on-surface-muted)]">(0–9)</span></CheckListItem>
+      <CheckListItem>Not used on another account</CheckListItem>
+    </CheckList>
+  );
+}
+```
+
+Related: [plan-tracker](plan-tracker.md)

package/dist/skill/references/components/command-palette.md

@@ -0,0 +1,108 @@
+# Command Palette
+
+A searchable command menu in a modal dialog (cmdk), with nested pages, recents and an optional Cmd+K shortcut.
+
+- Package: `@nexub/react` · Category: Navigation · Status: stable
+- Import: `import { CommandPalette } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/command-palette
+
+## When to use
+
+- Power users jumping to pages or running actions by name
+- A global Cmd+K entry point in an app
+
+## When not to use
+
+- Filtering a single list on the page: use `SearchInput` or `Combobox`
+- The only way to reach an action: keep it in the visible UI too
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open / onOpenChange` | `boolean / (open: boolean) => void` |  | Controlled open state. |
+| `defaultOpen` | `boolean` |  | Uncontrolled initial open state. |
+| `shortcut` | `string` |  | A letter that toggles the palette with Cmd (macOS) or Ctrl anywhere on the page, e.g. `'k'`. |
+| `label` | `string` |  | Accessible name of the dialog. Defaults to the localised "Command palette". |
+| `shouldFilter` | `boolean` |  | Set `false` when the items are already filtered, e.g. async search results. |
+| `loading` | `boolean` |  | Shows a loading row and hides `Empty`. |
+| `pages / defaultPages / onPagesChange` | `string[]` |  | The open page stack (ids of `CommandPalette.Page`), deepest last. Empty = the root page. |
+| `recentKey / recentLimit` | `string / number` |  | Opt-in recents: the last picks on the root page are kept in localStorage under this key and shown while the query is empty. |
+| `scrollLock` | `'class' \| 'style'` |  | `'class'` (strict-CSP safe) or Radix's style-tag lock. |
+| `CommandPalette.Input / List / Empty / Group / Separator` | `compound` |  | Search field, results list, no-results row, a headed group (`heading`), and a decorative divider. |
+| `CommandPaletteItem page` | `string` |  | Opens the `CommandPalette.Page` with this id when selected. Other props are cmdk `Command.Item` props (`onSelect`, `value`, `keywords`, `disabled`). |
+| `CommandPalettePage id / title` | `string` |  | Content shown only while this page is on top. No `id` = the root page; `title` shows in the input breadcrumb. Backspace on an empty query goes back. |
+
+## Example: Default
+
+```tsx
+import * as React from 'react';
+import { Button, CommandPalette } from '@nexub/react';
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <>
+      <Button variant="outlined" onClick={() => setOpen(true)}>Open command palette</Button>
+      <CommandPalette.Root open={open} onOpenChange={setOpen}>
+        <CommandPalette.Input placeholder="Type a command or search…" />
+        <CommandPalette.List>
+          <CommandPalette.Empty>No results found.</CommandPalette.Empty>
+          <CommandPalette.Group heading="Go to">
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Dashboard</CommandPalette.Item>
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Reports</CommandPalette.Item>
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Settings</CommandPalette.Item>
+          </CommandPalette.Group>
+          <CommandPalette.Separator />
+          <CommandPalette.Group heading="Actions">
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Create project</CommandPalette.Item>
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Invite a teammate</CommandPalette.Item>
+          </CommandPalette.Group>
+        </CommandPalette.List>
+      </CommandPalette.Root>
+    </>
+  );
+}
+```
+
+## Example: Nested pages
+
+```tsx
+import * as React from 'react';
+import { Button, CommandPalette } from '@nexub/react';
+
+export default function Example() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <>
+      <Button variant="outlined" onClick={() => setOpen(true)}>Switch project</Button>
+      <CommandPalette.Root open={open} onOpenChange={setOpen}>
+        <CommandPalette.Input placeholder="Search…" />
+        <CommandPalette.List>
+          <CommandPalette.Empty>No results found.</CommandPalette.Empty>
+          <CommandPalette.Page>
+            <CommandPalette.Item page="projects">Projects…</CommandPalette.Item>
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Export report</CommandPalette.Item>
+          </CommandPalette.Page>
+          <CommandPalette.Page id="projects" title="Projects">
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Billing service</CommandPalette.Item>
+            <CommandPalette.Item onSelect={() => setOpen(false)}>Mobile app</CommandPalette.Item>
+          </CommandPalette.Page>
+        </CommandPalette.List>
+      </CommandPalette.Root>
+    </>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: dialog, combobox, listbox, option
+- `Cmd/Ctrl + shortcut`: Toggles the palette when `shortcut` is set.
+- `Arrow Up / Down`: Moves through items (wraps).
+- `Enter`: Runs the highlighted item.
+- `Backspace`: On an empty query, goes back a page.
+- `Escape`: Closes the palette.
+- Focus moves to the input on open and returns to the previously focused element on close.
+
+Related: [keyboard-shortcut](keyboard-shortcut.md), [dialog](dialog.md), [search-input](search-input.md)

package/dist/skill/references/components/container.md

@@ -0,0 +1,50 @@
+# Container
+
+Centres content at a maximum width with responsive side padding.
+
+- Package: `@nexub/react` · Category: Layout · Status: stable
+- Import: `import { Container } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/container
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'nexub' \| 'marketing' \| 'prose'` |  | Maximum width, from the `--container-*` tokens. `prose` is 65ch for reading. |
+| `paddingX` | `boolean` |  | Responsive horizontal padding (16, 24, 32 px). |
+| `asChild` | `boolean` |  | Apply the container classes to the child element (e.g. `<main>`) instead of a `<div>`. |
+
+## Example: Default
+
+```tsx
+import { Container, Text } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="w-full bg-[var(--color-surface-container-low)] py-4">
+      <Container size="sm" className="rounded-shape-container bg-[var(--color-surface)] py-4">
+        <Text size="body-sm">Centred at up to 640 px, with responsive side padding.</Text>
+      </Container>
+    </div>
+  );
+}
+```
+
+## Example: Prose width
+
+```tsx
+import { Container, Heading, Text } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <Container size="prose" paddingX={false}>
+      <Heading level={3}>Release notes</Heading>
+      <Text size="body-sm" tone="secondary" className="mt-2">
+        The prose size caps lines at about 65 characters, a comfortable measure for reading long text.
+      </Text>
+    </Container>
+  );
+}
+```
+
+Related: [section](section.md), [box](box.md), [stack](stack.md)

package/dist/skill/references/components/context-menu.md

@@ -0,0 +1,62 @@
+# Context Menu
+
+A menu that opens at the pointer on right-click (or long-press), built on Radix.
+
+- Package: `@nexub/react` · Category: Overlays · Status: stable
+- Import: `import { ContextMenu } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/context-menu
+
+## When to use
+
+- Shortcuts to actions on an item: rename, duplicate, delete
+
+## When not to use
+
+- The only way to reach an action: right-click is hard to discover and needs a visible alternative, such as a `DropdownMenu`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ContextMenu.Root` | `compound` |  | Holds the open state (`onOpenChange`, `modal`). |
+| `ContextMenu.Trigger` | `compound` |  | The area that opens the menu on right-click. Use `asChild` to make your element the area. |
+| `ContextMenu.Portal / Content` | `compound` |  | Renders the floating menu in a portal. |
+| `ContextMenu.Item` | `compound` |  | An action (`onSelect`, `disabled`). |
+| `ContextMenu.CheckboxItem / RadioGroup / RadioItem` | `compound` |  | Toggle and single-choice items (`checked`, `onCheckedChange`; `value`, `onValueChange`). |
+| `ContextMenu.Label / Group / Separator` | `compound` |  | Section heading, grouping and divider. |
+| `ContextMenu.Sub / SubTrigger / SubContent` | `compound` |  | A nested submenu. |
+
+## Example: Default
+
+```tsx
+import { ContextMenu } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger className="flex h-32 w-64 select-none items-center justify-center rounded-shape-container border-2 border-dashed border-[var(--color-outline-variant)] text-body-sm text-[var(--color-on-surface-muted)]">
+        Right-click here
+      </ContextMenu.Trigger>
+      <ContextMenu.Portal>
+        <ContextMenu.Content>
+          <ContextMenu.Item>Rename</ContextMenu.Item>
+          <ContextMenu.Item>Duplicate</ContextMenu.Item>
+          <ContextMenu.Item>Copy link</ContextMenu.Item>
+          <ContextMenu.Separator />
+          <ContextMenu.Item>Move to trash</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Portal>
+    </ContextMenu.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: menu, menuitem, menuitemcheckbox, menuitemradio
+- `Shift + F10 / Menu key`: Opens the menu from the focused trigger.
+- `Arrow Up / Down`: Moves between items.
+- `Enter / Space`: Activates the item.
+- `Escape`: Closes the menu.
+
+Related: [dropdown-menu](dropdown-menu.md), [menubar](menubar.md)

package/dist/skill/references/components/country-badge.md

@@ -0,0 +1,49 @@
+# Country Badge
+
+A pill with a country flag and its name or code.
+
+- Package: `@nexub/react` · Category: Labels & Badges · Status: stable
+- Import: `import { CountryBadge } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/country-badge
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `code` | `string` |  | ISO 3166-1 alpha-2 country code, e.g. `SG`. |
+| `label` | `string` |  | Text after the flag. Defaults to `code`. |
+| `size` | `'sm' \| 'md' \| 'lg'` |  | Size of the pill and flag. |
+
+## Example: Default
+
+```tsx
+import { CountryBadge } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex flex-wrap gap-2">
+      <CountryBadge code="SG" label="Singapore" />
+      <CountryBadge code="DE" label="Germany" />
+      <CountryBadge code="BR" label="Brazil" />
+    </div>
+  );
+}
+```
+
+## Example: Sizes
+
+```tsx
+import { CountryBadge } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <CountryBadge code="JP" size="sm" />
+      <CountryBadge code="JP" size="md" />
+      <CountryBadge code="JP" size="lg" />
+    </div>
+  );
+}
+```
+
+Related: [flag](flag.md), [badge](badge.md)

package/dist/skill/references/components/dropdown-menu.md

@@ -0,0 +1,99 @@
+# Dropdown Menu
+
+A menu of actions opened from a button, built on Radix.
+
+- Package: `@nexub/react` · Category: Overlays · Status: stable
+- Import: `import { DropdownMenu } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/dropdown-menu
+
+## When to use
+
+- Secondary actions behind a "More" button
+- A short set of options that change a view
+
+## When not to use
+
+- Picking a form value: use `Select`
+- Site navigation: use `NavigationMenu` or `TopNav`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `DropdownMenu.Root` | `compound` |  | Holds the open state (`open`, `onOpenChange`, `defaultOpen`, `modal`). |
+| `DropdownMenu.Trigger` | `compound` |  | The button that opens the menu. Use `asChild` with a `Button` or `IconButton`. |
+| `DropdownMenu.Portal / Content` | `compound` |  | Renders the floating menu in a portal (`side`, `align`, `sideOffset` default 4). |
+| `DropdownMenu.Item` | `compound` |  | An action (`onSelect`, `disabled`). |
+| `DropdownMenu.CheckboxItem / RadioGroup / RadioItem` | `compound` |  | Toggle and single-choice items (`checked`, `onCheckedChange`; `value`, `onValueChange`). |
+| `DropdownMenu.Label / Group / Separator` | `compound` |  | Section heading, grouping and divider. |
+| `DropdownMenu.Sub / SubTrigger / SubContent` | `compound` |  | A nested submenu. |
+
+## Example: Default
+
+```tsx
+import { DropdownMenu, IconButton } from '@nexub/react';
+import { MoreHorizontal } from '@nexub/icons';
+
+export default function Example() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger asChild>
+        <IconButton variant="ghost" label="More actions"><MoreHorizontal size="sm" /></IconButton>
+      </DropdownMenu.Trigger>
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content align="end">
+          <DropdownMenu.Label>Project</DropdownMenu.Label>
+          <DropdownMenu.Item>Rename</DropdownMenu.Item>
+          <DropdownMenu.Item>Duplicate</DropdownMenu.Item>
+          <DropdownMenu.Item disabled>Transfer ownership</DropdownMenu.Item>
+          <DropdownMenu.Separator />
+          <DropdownMenu.Item>Archive</DropdownMenu.Item>
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  );
+}
+```
+
+## Example: Checkbox and radio items
+
+```tsx
+import * as React from 'react';
+import { Button, DropdownMenu } from '@nexub/react';
+
+export default function Example() {
+  const [showArchived, setShowArchived] = React.useState(false);
+  const [sort, setSort] = React.useState('updated');
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger asChild>
+        <Button variant="outlined">View options</Button>
+      </DropdownMenu.Trigger>
+      <DropdownMenu.Portal>
+        <DropdownMenu.Content>
+          <DropdownMenu.CheckboxItem checked={showArchived} onCheckedChange={setShowArchived}>
+            Show archived
+          </DropdownMenu.CheckboxItem>
+          <DropdownMenu.Separator />
+          <DropdownMenu.Label>Sort by</DropdownMenu.Label>
+          <DropdownMenu.RadioGroup value={sort} onValueChange={setSort}>
+            <DropdownMenu.RadioItem value="updated">Last updated</DropdownMenu.RadioItem>
+            <DropdownMenu.RadioItem value="name">Name</DropdownMenu.RadioItem>
+            <DropdownMenu.RadioItem value="owner">Owner</DropdownMenu.RadioItem>
+          </DropdownMenu.RadioGroup>
+        </DropdownMenu.Content>
+      </DropdownMenu.Portal>
+    </DropdownMenu.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: menu, menuitem, menuitemcheckbox, menuitemradio
+- `Enter / Space / Arrow Down`: Opens the menu from the trigger.
+- `Arrow Up / Down`: Moves between items.
+- `Arrow Right / Left`: Opens or closes a submenu.
+- `Escape`: Closes the menu and returns focus to the trigger.
+
+Related: [split-button](split-button.md), [context-menu](context-menu.md), [popover](popover.md)

package/dist/skill/references/components/file-upload.md

@@ -0,0 +1,73 @@
+# File Upload
+
+A drop zone and file list: pick, drop or paste files, with type, size and count checks and per-file progress.
+
+- Package: `@nexub/react` · Category: Form Controls · Status: stable
+- Import: `import { FileUpload } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/file-upload
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `accept` | `string[]` |  | MIME types or extensions, e.g. `['image/*', '.pdf']`. Other files are rejected with a message. |
+| `maxFiles` | `number` |  | Most files kept; extras are rejected. |
+| `maxSize` | `number` |  | Largest file in bytes. |
+| `onFilesChange` | `(files: File[]) => void` |  | The accepted files after every add or remove. Your app does the upload. |
+| `onReject` | `(rejections: FileRejection[]) => void` |  | Files turned away, with the reason (`type`, `size`, `count` or `custom`). |
+| `validate` | `(file: File) => string \| null \| undefined` |  | Your own check: return a message to reject the file. Validate again on the server. |
+| `FileUpload.Dropzone` | `compound` |  | A `<label>` around the native file input: click, Enter, Space, drop or paste. Children replace the default prompt. Rejection messages are announced. |
+| `FileUpload.List` | `compound` |  | Renders nothing until there are files. |
+| `FileUploadItem index` | `number` |  | Which accepted file this row shows. Rows past the file count render nothing. |
+| `FileUploadItem progress / onCancel` | `number / () => void` |  | Upload progress 0–100; below 100 shows a bar and, with `onCancel`, a cancel button. |
+| `FileUploadItem error` | `string` |  | Why this file failed; shown under its name. |
+
+## Example: Default
+
+```tsx
+import { FileUpload } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <FileUpload.Root accept={['image/*', '.pdf']} maxFiles={3} className="w-full max-w-[480px]">
+      <FileUpload.Dropzone />
+      <FileUpload.List>
+        {[0, 1, 2].map((i) => <FileUpload.Item key={i} index={i} />)}
+      </FileUpload.List>
+    </FileUpload.Root>
+  );
+}
+```
+
+## Example: Custom prompt and limits
+
+```tsx
+import { FileUpload, Text } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <FileUpload.Root
+      accept={['.csv']}
+      maxFiles={1}
+      maxSize={5 * 1024 * 1024}
+      validate={(file) => (file.name.includes(' ') ? 'Rename the file without spaces.' : null)}
+      className="w-full max-w-[480px]"
+    >
+      <FileUpload.Dropzone>
+        <Text size="body-sm"><span className="font-semibold text-[var(--color-primary)]">Choose a CSV</span> or drop it here</Text>
+        <Text size="caption" tone="muted">One file, up to 5 MB</Text>
+      </FileUpload.Dropzone>
+      <FileUpload.List>
+        <FileUpload.Item index={0} />
+      </FileUpload.List>
+    </FileUpload.Root>
+  );
+}
+```
+
+## Accessibility
+
+- `Enter / Space`: Opens the file picker from the focused drop zone.
+- Rejected files are listed in a live region (`role="alert"`) tied to the input with `aria-describedby`.
+
+Related: [form-field](form-field.md), [progress](progress.md)

package/dist/skill/references/components/flag.md

@@ -0,0 +1,38 @@
+# Flag
+
+A country flag from its ISO code, drawn with the system emoji font.
+
+- Package: `@nexub/react` · Category: Labels & Badges · Status: stable
+- Import: `import { Flag } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/flag
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `code` | `string` |  | ISO 3166-1 alpha-2 country code, e.g. `JP`. Also the accessible name unless you pass `aria-label`. |
+| `size` | `'sm' \| 'md' \| 'lg'` |  | Font size of the flag. |
+| `aria-label` | `string` |  | A readable name, e.g. "Japan". Defaults to the code. |
+
+## Example: Default
+
+```tsx
+import { Flag } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex items-center gap-3">
+      <Flag code="JP" size="sm" aria-label="Japan" />
+      <Flag code="IN" aria-label="India" />
+      <Flag code="FR" size="lg" aria-label="France" />
+    </div>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: img
+- Windows has no flag emoji and shows the two letters instead. Pair the flag with the country name where it matters.
+
+Related: [country-badge](country-badge.md)