@teamblind-chorus/ui 1.0.0

package/agents/usage.json

@@ -0,0 +1,422 @@
+{
+  "generated": "by packages/ui/scripts/build-usage.mjs — DO NOT EDIT. Run `npm run build-usage`.",
+  "purpose": "Authoritative family → React usage map. Every `import` below is parity-checked against packages/ui/src/index.js at build time, so 'is this family exported?' is answered HERE, never guessed. Read the per-sub `access`: a `variant` sub is reached with the `variant` prop on its parent import (there is no separate export for it — e.g. NO `<Fab>`, NO `<ListItem>`); a `named` sub is its own export. A failed `import { X }` for ONE component never means the catalog is unreliable — look the component up here.",
+  "from": "@teamblind-chorus/ui",
+  "families": {
+    "badge": {
+      "import": "Badge",
+      "from": "@teamblind-chorus/ui",
+      "note": "Both forms are the single `Badge` export selected by the `variant` prop — there is NO `<UpdateBadge>` or `<RoleBadge>` export. Default variant is `update`: count via children or `count`; render a dot (no number) with a `dot-*` size — there is no separate `Dot` element.",
+      "subs": {
+        "update": {
+          "access": "variant",
+          "on": "Badge",
+          "variant": "update",
+          "example": "<Badge size=\"medium\" count={3} />"
+        },
+        "role": {
+          "access": "variant",
+          "on": "Badge",
+          "variant": "role",
+          "example": "<Badge variant=\"role\">Verified</Badge>"
+        }
+      }
+    },
+    "banner": {
+      "import": "Banner",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "Alert"
+      ],
+      "note": "Body text is children, not a `body` prop; `action` is an object with `label` + `href`/`onClick`.",
+      "example": "<Banner appearance=\"default\" action={{ label, href }}>…</Banner>"
+    },
+    "bottom-sheet": {
+      "import": "BottomSheet",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "Sheet",
+        "Drawer"
+      ],
+      "note": "Controlled via `open` + `onClose`; actions are objects (`primaryAction`/`secondaryAction`), not children.",
+      "example": "<BottomSheet open onClose={close} title=\"…\" body=\"…\" primaryAction={{ label, onClick }} secondaryAction={{ label, onClick }} />"
+    },
+    "bubble": {
+      "import": "Bubble",
+      "from": "@teamblind-chorus/ui",
+      "note": "Label is children; ships no positioning — the host anchors it. `tailSide`/`tailAlign` pick the tail; there is no separate tail element.",
+      "example": "<Bubble tailSide=\"top\" tailAlign=\"center\">…</Bubble>"
+    },
+    "button": {
+      "import": "Button",
+      "from": "@teamblind-chorus/ui",
+      "note": "All button roles are the single `Button` export selected by the `variant` prop — there is NO `<Fab>`, `<IconButton>`, `<ToggleButton>`, or `<Toolbar>` export. An `import { Fab }` failure does NOT mean the family is missing; reach for `<Button variant=\"fab\">`.",
+      "subs": {
+        "standard": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "standard",
+          "example": "<Button variant=\"standard\" … />"
+        },
+        "fab": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "fab",
+          "example": "<Button variant=\"fab\" appearance=\"primary\" icon={<EditIcon />}>글쓰기</Button>"
+        },
+        "icon": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "icon",
+          "example": "<Button variant=\"icon\" aria-label=\"…\" icon={<MoreIcon />} />"
+        },
+        "text": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "text",
+          "example": "<Button variant=\"text\" … />"
+        },
+        "check": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "check",
+          "example": "<Button variant=\"check\" … />"
+        },
+        "toggle": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "toggle",
+          "example": "<Button variant=\"toggle\" … />"
+        },
+        "toolbar": {
+          "access": "variant",
+          "on": "Button",
+          "variant": "toolbar",
+          "example": "<Button variant=\"toolbar\" … />"
+        }
+      }
+    },
+    "suggestion-list": {
+      "import": "SuggestionList",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "ChannelList"
+      ],
+      "note": "Also exported as the deprecated alias `ChannelList`. Rows carry `name`/`followers`/`description`, not `label`.",
+      "example": "<SuggestionList label=\"…\" headerAction={{ label, href }} items={[{ value, name, followers, description, thumbnail, active, onToggle }]} />"
+    },
+    "avatar-rail": {
+      "import": "AvatarRail",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "ChannelRail"
+      ],
+      "note": "Also exported as the deprecated alias `ChannelRail`. Items route via `href`; the update dot lives on `thumbnail.updateDot`.",
+      "example": "<AvatarRail aria-label=\"…\" items={[{ value, label, href, thumbnail }]} trailingAction={{ label, href }} />"
+    },
+    "chip": {
+      "import": "Chip",
+      "from": "@teamblind-chorus/ui",
+      "note": "Both forms are the single `Chip` export selected by the `variant` prop — there is NO `<FilterChip>` or `<Tag>` export.",
+      "subs": {
+        "filter": {
+          "access": "variant",
+          "on": "Chip",
+          "variant": "filter",
+          "example": "<Chip variant=\"filter\" selected leadingIcon={<CheckedIcon />}>Selected</Chip>"
+        },
+        "tag": {
+          "access": "variant",
+          "on": "Chip",
+          "variant": "tag",
+          "example": "<Chip variant=\"tag\" trailingIcon={<XIcon />}>Newsletter</Chip>"
+        }
+      }
+    },
+    "dialog": {
+      "import": "Dialog",
+      "from": "@teamblind-chorus/ui",
+      "note": "Actions are `primaryAction` / `secondaryAction` descriptor objects ({ label, onClick }) — there are NO Button children.",
+      "example": "<Dialog open={open} onClose={() => setOpen(false)} title=\"…\" body=\"…\" primaryAction={{ label, onClick }} secondaryAction={{ label, onClick }} />"
+    },
+    "divider": {
+      "import": "Divider",
+      "from": "@teamblind-chorus/ui",
+      "example": "<Divider />"
+    },
+    "directory-list": {
+      "import": "DirectoryList",
+      "from": "@teamblind-chorus/ui",
+      "note": "Rows are an `items` array of descriptors (name/followers/description/thumbnail/active/onToggle) — there are NO List or row children.",
+      "example": "<DirectoryList label=\"…\" items={[{ value, name, followers, description, thumbnail: { src, alt }, active, onToggle }]} />"
+    },
+    "feed": {
+      "import": "Feed",
+      "from": "@teamblind-chorus/ui",
+      "note": "`feed / post` IS the `Feed` export; `feed / ad` is a separate `FeedAd` export. Every affordance threads through props — there is NO `<FeedItem>` child element.",
+      "subs": {
+        "post": {
+          "access": "named",
+          "import": "Feed",
+          "example": "<Feed channel=\"…\" thumbnail={{ src }} title=\"…\" body=\"…\" onClick={() => router.push(href)} />"
+        },
+        "ad": {
+          "access": "named",
+          "import": "FeedAd",
+          "example": "<FeedAd brand=\"…\" title=\"…\" media={{ src }} cta={…} />"
+        }
+      }
+    },
+    "form-field": {
+      "import": "FormField",
+      "from": "@teamblind-chorus/ui",
+      "note": "Each variant is also exposed as a convenience named export (Input / Textarea / SearchBar / Select), all backed by `FormField`.",
+      "subs": {
+        "input": {
+          "access": "named",
+          "import": "Input",
+          "example": "<Input label=\"…\" value={v} onChange={setV} />"
+        },
+        "textarea": {
+          "access": "named",
+          "import": "Textarea",
+          "example": "<Textarea label=\"…\" value={v} onChange={setV} />"
+        },
+        "search": {
+          "access": "named",
+          "import": "SearchBar",
+          "example": "<SearchBar value={q} onChange={setQ} />"
+        },
+        "select": {
+          "access": "named",
+          "import": "Select",
+          "example": "<Select label=\"…\" value={v} onChange={setV} options={[…]} />"
+        }
+      }
+    },
+    "header": {
+      "import": "Header",
+      "from": "@teamblind-chorus/ui",
+      "subs": {
+        "main": {
+          "access": "named",
+          "import": "Header",
+          "example": "<Header label=\"Recommended channels\" headerAction={{ label: 'See all', href: '#all' }} />"
+        },
+        "sub": {
+          "access": "named",
+          "import": "SubHeader",
+          "example": "<SubHeader label=\"Following\" />"
+        }
+      }
+    },
+    "list": {
+      "import": "List",
+      "from": "@teamblind-chorus/ui",
+      "note": "Rows are an `items` descriptor *array* on `<List>` — there is NO `<ListItem>` export. A styled `<button>` row or a hand-rolled flex row is a reinvention of `list / entry`. `accordion` is the one sub that takes `<Accordion>` children.",
+      "subs": {
+        "standard": {
+          "access": "variant",
+          "on": "List",
+          "variant": "standard",
+          "example": "<List variant=\"standard\" items={[{ label, leadingIcon, trailing, onClick }]} />"
+        },
+        "radio": {
+          "access": "variant",
+          "on": "List",
+          "variant": "radio",
+          "example": "<List variant=\"radio\" value={v} onChange={setV} items={[{ label, value }]} />"
+        },
+        "entry": {
+          "access": "variant",
+          "on": "List",
+          "variant": "entry",
+          "example": "<List variant=\"entry\" items={[{ thumbnail, label, secondary, description, trailing, onClick }]} />"
+        },
+        "accordion": {
+          "access": "named",
+          "import": "Accordion",
+          "example": "<Accordion><Accordion.Item title=\"…\">…</Accordion.Item></Accordion>"
+        }
+      }
+    },
+    "metadata": {
+      "import": "Metadata",
+      "from": "@teamblind-chorus/ui",
+      "note": "Both shapes are the single `Metadata` export — the one-line comment shape is `variant=\"compact\"`, NOT a separate `<MetadataCompact>`. Leading thumbnail is the `avatar` prop (NOT `thumbnail`); the secondary line is either a `subtitle` string or a `meta` string array — not children.",
+      "subs": {
+        "standard": {
+          "access": "named",
+          "import": "Metadata",
+          "example": "<Metadata avatar={{ src, alt }} name=\"…\" nameHref=\"#\" timestamp=\"2h\" meta={[\"…\"]} />"
+        },
+        "compact": {
+          "access": "variant",
+          "on": "Metadata",
+          "variant": "compact",
+          "example": "<Metadata variant=\"compact\" meta={[\"Maple Mill Bakery\", \"ryestarter\"]} timestamp=\"35m\" />"
+        }
+      }
+    },
+    "nav-card": {
+      "import": "NavCard",
+      "from": "@teamblind-chorus/ui",
+      "note": "The trailing drill-in chevron comes from `variant=\"nav\"`, not a trailing child; `leading` takes a node (Icon / Thumbnail).",
+      "example": "<NavCard variant=\"nav\" label=\"…\" supportingText=\"…\" leading={<Icon />} href=\"#\" />"
+    },
+    "nav-list": {
+      "import": "NavList",
+      "from": "@teamblind-chorus/ui",
+      "note": "Rows are a label-only `items` array (value/label + href or onClick) — no thumbnail key, and no List or row children; the trailing chevron is automatic.",
+      "example": "<NavList label=\"…\" items={[{ value, label, href }]} />"
+    },
+    "navigation-bar": {
+      "import": "NavigationBar",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "AppBar"
+      ],
+      "note": "All three bars are the single `NavigationBar` export selected by the `variant` prop — pass `onBack` to a `main` bar to turn it into a content-detail drill-in. Also exported as the alias `AppBar`.",
+      "subs": {
+        "main": {
+          "access": "variant",
+          "on": "NavigationBar",
+          "variant": "main",
+          "example": "<NavigationBar variant=\"main\" title=\"Home\" trailingActions={[{ icon, 'aria-label' }]} />"
+        },
+        "sub": {
+          "access": "variant",
+          "on": "NavigationBar",
+          "variant": "sub",
+          "example": "<NavigationBar variant=\"sub\" title=\"Edit profile\" leading={{ icon, 'aria-label' }} trailing={<Button variant=\"toolbar\">Save</Button>} />"
+        },
+        "search": {
+          "access": "variant",
+          "on": "NavigationBar",
+          "variant": "search",
+          "example": "<NavigationBar variant=\"search\" placeholder=\"Search by keyword\" onBack={() => {}} />"
+        }
+      }
+    },
+    "page-shell": {
+      "import": "PageShell",
+      "from": "@teamblind-chorus/ui",
+      "note": "Compose the bars INTO the shell — do NOT hand-roll a flex column, and do NOT add position:sticky/fixed to the bars (that double-applies their safe-area insets). The dev-only usePinnedBarGuard warns when a bar is rendered inside a scrolling region instead.",
+      "example": "<PageShell nav={<NavigationBar variant=\"home\" … />} tabBar={<TabBar … />}>… scrolling screen content …</PageShell>"
+    },
+    "profile-header": {
+      "import": "ProfileHeader",
+      "from": "@teamblind-chorus/ui",
+      "note": "Paints its own overlay NavigationBar — don't wrap one yourself; opt out with nav={false}. value props are strings.",
+      "example": "<ProfileHeader name=\"…\" avatar={{ src, alt }} cover={{ src, alt }} visibility=\"public\" followers=\"…\" />"
+    },
+    "progress": {
+      "import": "Progress",
+      "from": "@teamblind-chorus/ui",
+      "note": "value is a 0–1 ratio, not a 0–100 percent. Determinate only; the label lives on the host surface.",
+      "example": "<Progress value={0.4} aria-label=\"…\" />"
+    },
+    "carousel": {
+      "import": "Carousel",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "Section"
+      ],
+      "note": "Carousel is the labelled section *wrapper* (heading + see-all link). The cards are a separate export per sub — there is NO `<CarouselItem>`. Also exported as the deprecated alias `Section`.",
+      "subs": {
+        "post": {
+          "access": "named",
+          "import": "PostCarousel",
+          "example": "<Carousel label=\"…\"><PostCarousel items={[{ avatar, channel, title, body, views, onClick }]} /></Carousel>"
+        },
+        "profile": {
+          "access": "named",
+          "import": "ProfileCarousel",
+          "example": "<Carousel label=\"…\"><ProfileCarousel items={[{ avatar, name, meta, onFollowChange }]} /></Carousel>"
+        }
+      }
+    },
+    "side-sheet": {
+      "import": "SideSheet",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "SideDrawer"
+      ],
+      "note": "Portal-rendered; controlled via open/onClose. Free-form children — group canonical Header + List(entry) stacks in SideSheetGroup.",
+      "example": "<SideSheet open onClose={close} aria-label=\"…\" footer={…}><SideSheetGroup>…</SideSheetGroup></SideSheet>"
+    },
+    "skeleton": {
+      "import": "Skeleton",
+      "from": "@teamblind-chorus/ui",
+      "note": "shape defaults to text; width/height are consumer-supplied. Stack multiples in SkeletonGroup to mirror the loading content's rhythm.",
+      "example": "<Skeleton shape=\"block\" height={120} />"
+    },
+    "status-tag": {
+      "import": "StatusTag",
+      "from": "@teamblind-chorus/ui",
+      "note": "Decorative — never interactive. Takes label text as children; not a Chip and not a button.",
+      "example": "<StatusTag appearance=\"error\">Rejected</StatusTag>"
+    },
+    "switch": {
+      "import": "Switch",
+      "from": "@teamblind-chorus/ui",
+      "note": "Change handler is `onCheckedChange` (not `onChange`); instant commit, no confirmation step. Whole pill is the target — the thumb is decorative.",
+      "example": "<Switch checked={on} onCheckedChange={setOn} aria-label=\"…\" />"
+    },
+    "tab-bar": {
+      "import": "TabBar",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "BottomNav"
+      ],
+      "note": "Export is `TabBar`; destinations thread through the `items` array (each `{ value, label, icon, activeIcon }`) — there is NO `<Tab>` child element.",
+      "example": "<TabBar aria-label=\"…\" value={value} onChange={setValue} items={[{ value, label, icon, activeIcon }]} />"
+    },
+    "tabs": {
+      "import": "Tabs",
+      "from": "@teamblind-chorus/ui",
+      "note": "`<Tabs>` selects chrome by the `variant` prop; every tab MUST be a `<Tab value=…>` child (compound) — there is no per-variant tab export and bare text / raw <button> children do not work.",
+      "subs": {
+        "underline": {
+          "access": "variant",
+          "on": "Tabs",
+          "variant": "underline",
+          "example": "<Tabs variant=\"underline\" value={v} onChange={setV}><Tab value=\"a\">A</Tab><Tab value=\"b\">B</Tab></Tabs>"
+        },
+        "rounded": {
+          "access": "variant",
+          "on": "Tabs",
+          "variant": "rounded",
+          "example": "<Tabs variant=\"rounded\" … />"
+        },
+        "segmented": {
+          "access": "variant",
+          "on": "Tabs",
+          "variant": "segmented",
+          "example": "<Tabs variant=\"segmented\" … />"
+        }
+      }
+    },
+    "thumbnail": {
+      "import": "Thumbnail",
+      "from": "@teamblind-chorus/ui",
+      "aliases": [
+        "Avatar"
+      ],
+      "note": "Pure circular image primitive (the channel/author avatar) — badges ride via the `updateDot` / `logoBadge` props, not children; carries no label of its own.",
+      "example": "<Thumbnail size={48} src=\"…\" alt=\"…\" />"
+    },
+    "toast": {
+      "import": "Toast",
+      "from": "@teamblind-chorus/ui",
+      "note": "Message is children, not a `message` prop; an action / dismiss control goes in the `trailing` slot (an inverse-appearance Button).",
+      "example": "<Toast trailing={<Button variant=\"text\" appearance=\"inverse\" onClick={() => {}}>Undo</Button>}>…</Toast>"
+    },
+    "tooltip": {
+      "import": "Tooltip",
+      "from": "@teamblind-chorus/ui",
+      "note": "Hint text is children, not a `text` prop; an optional action goes in the `action` slot (a node) — `placement` anchors the caret to the trigger.",
+      "example": "<Tooltip placement=\"top\" action={<Button variant=\"text\" appearance=\"onPrimary\" onClick={() => {}}>Got it</Button>}>…</Tooltip>"
+    }
+  }
+}