handy-fluentui 0.1.1 → 1.0.0

package/README.md

@@ -7,7 +7,7 @@ Opinionated React components built on top of [FluentUI v9](https://react.fluentu
 - Imperative `useToast`, `useSpinner`, `useDialog` APIs
 - i18n-ready label overrides through the provider
 
-**Live showcase:** [kc2wong.github.io/handy-fluentui](https://kc2wong.github.io/handy-fluentui/)
+An equivalent library built on [shadcn/ui](https://ui.shadcn.com/) instead of FluentUI, mirroring the same component API surface under a `Hui*` prefix, is available at [kc2wong/handy-shadcnui](https://github.com/kc2wong/handy-shadcnui).
 
 ---
 
@@ -90,6 +90,7 @@ Component-specific labels (`FuiTable` pagination text, `FuiImageCarousel` toolti
 |------|---------|-------------|
 | `useTheme()` | `{ currentTheme, switchTheme }` | Read and change the active theme |
 | `useIsMobile()` | `boolean` | True when viewport ≤ `mobileBreakpoint` |
+| `useBreadcrumb()` | `{ items, isCollapsed, toggleCollapsed, start, append, peek, popTill }` | Read and update the trail rendered by `FuiBreadcrumb` |
 | `useToast()` | `{ success, error, info, warning }` | Show toast notifications |
 | `useSpinner()` | `{ show, hide }` | Show/hide the global overlay spinner |
 | `useDialog()` | `{ openDialog }` | Show an imperative confirmation dialog |
@@ -142,7 +143,7 @@ type LocalDate = {
 
 ## Common field props (`FieldLayoutProps`)
 
-Every `input-*` component inherits these props from the `withInputField` HOC:
+Every form input component (`FuiInputText`, `FuiInputDate`, `FuiRadioGroup`, ...) inherits these props from the `withInputField` HOC:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -189,6 +190,8 @@ Text input with optional show/hide toggle for passwords.
 | `value` | `string \| null` | Yes | Current value |
 | `onChange` | `(value: string \| null) => void` | Yes | Change callback |
 | `type` | `'text' \| 'email' \| 'password'` | No | Defaults to `'text'`. Password adds show/hide toggle; email blocks duplicate `@`. |
+| `contentBefore` | `ReactElement` | No | Content rendered inside the input, left-aligned (e.g. an icon) |
+| `contentAfter` | `ReactElement` | No | Content rendered inside the input, right-aligned (e.g. an icon button). Ignored when `type` is `'password'`. |
 
 ---
 
@@ -211,6 +214,8 @@ Multi-line text area with optional character counter.
 | `value` | `string \| null` | Yes | Current value |
 | `onChange` | `(value: string \| null) => void` | Yes | Change callback |
 | `maxLength` | `number` | No | Automatically appends a counter (`n / max`) unless `additionalMessage` is set |
+| `rows` | `number` | No | Number of visible text lines. Defaults to `4`. |
+| `readOnly` | `boolean` | No | Native HTML read-only attribute, forwarded as-is to the `<textarea>` |
 
 ---
 
@@ -251,6 +256,8 @@ Number input with keystroke filtering and optional SpinButton mode.
 | `max` | `number` | No | Maximum value |
 | `allowNegative` | `boolean` | No | When `false`, blocks the minus key. Defaults to `true`. |
 | `formatter` | `(value: number) => string` | No | Formats the display value when the field is unfocused |
+| `appearance` | `'outline' \| 'underline' \| 'filled-darker' \| 'filled-lighter' \| 'filled-darker-shadow' \| 'filled-lighter-shadow'` | No | Visual appearance of the underlying `Input`/`SpinButton` |
+| `size` | `'small' \| 'medium' \| 'large'` | No | Input size |
 
 ---
 
@@ -270,8 +277,10 @@ Date picker. Renders a FluentUI `DatePicker` on desktop and a bottom-sheet calen
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `value` | `Date \| null` | Yes | Selected date |
-| `onChange` | `(date: Date \| null \| undefined) => void` | Yes | Change callback |
+| `onChange` | `(date: Date \| null) => void` | Yes | Change callback |
 | `formatter` | `(date: Date \| null) => string` | No | Custom date format function. Defaults to `toLocaleDateString()`. |
+| `placeholder` | `string` | No | Placeholder text shown when empty |
+| `disabled` | `boolean` | No | Disables interaction |
 | `readOnly` | `boolean` | No | Suppresses the calendar popup/drawer. Desktop renders a plain read-only `Input`; mobile hides the calendar icon and ignores clicks. |
 
 ---
@@ -281,7 +290,7 @@ Date picker. Renders a FluentUI `DatePicker` on desktop and a bottom-sheet calen
 Time picker with up/down arrow buttons. Clicking an arrow increments or decrements the time segment under the cursor. On mobile the arrows are laid out in a horizontal row with larger icons.
 
 ```tsx
-import { FuiInputTime, FuiTime } from './components/input-time';
+import { FuiInputTime, FuiTime } from './components/fui-input-time';
 
 const [shiftStart, setShiftStart] = useState<FuiTime | null>(null);
 
@@ -366,12 +375,17 @@ const options = [
 |------|------|----------|-------------|
 | `value` | `string \| string[] \| null` | Yes | Selected value(s) |
 | `onChange` | `(value: string \| string[] \| null) => void` | Yes | Change callback |
-| `options` | `InputDropdownOption[]` | Yes | Option list |
-| `multiselect` | `boolean` | No | Enable multi-select mode |
+| `options` | `FuiInputDropdownOption[]` | Yes | Option list |
+| `multiselect` | `boolean` | No | Enable multi-select mode. Defaults to `false`. |
+| `placeholder` | `string` | No | Placeholder text shown when empty |
+| `disabled` | `boolean` | No | Disables interaction |
 | `readOnly` | `boolean` | No | Silently ignores selection changes |
-| `listbox` | `ListboxProps` | No | Props forwarded to the inner `Listbox`. Use `style.maxHeight` to constrain dropdown height. Must pass `positioning={{ autoSize: false }}` alongside this, otherwise Floating UI overrides inline `max-height`. |
+| `className` | `string` | No | Custom CSS class for the dropdown root |
+| `style` | `CSSProperties` | No | Custom CSS styles for the dropdown root |
+| `listbox` | `{ style?: CSSProperties }` | No | Style passthrough for the inner `Listbox`. Use `style.maxHeight` to constrain dropdown height. Must pass `positioning={{ autoSize: false }}` alongside this, otherwise Floating UI overrides inline `max-height`. |
+| `positioning` | `{ autoSize?: boolean }` | No | Positioning passthrough for the dropdown popup |
 
-**`InputDropdownOption`**
+**`FuiInputDropdownOption`**
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
@@ -382,58 +396,75 @@ const options = [
 
 ---
 
-### `FuiInputRadio`
+### `FuiRadioGroup` / `FuiRadio`
 
-Radio group with a shared label.
+Radio group with a shared label. `FuiRadio` items are independent components (not raw Fluent `<Radio>` elements).
 
 ```tsx
-<FuiInputRadio
+<FuiRadioGroup
   label="Gender"
   value={gender}
-  onChange={(data) => setGender(data.value)}
-  direction="horizontal"
+  onChange={setGender}
+  layout="horizontal"
 >
-  <Radio label="Male" value="male" />
-  <Radio label="Female" value="female" />
-  <Radio label="Other" value="other" />
-</FuiInputRadio>
+  <FuiRadio label="Male" value="male" />
+  <FuiRadio label="Female" value="female" />
+  <FuiRadio label="Other" value="other" />
+</FuiRadioGroup>
 ```
 
+**`FuiRadioGroup` props**
+
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `onChange` | `(data: RadioGroupOnChangeData) => void` | No | Change callback |
-| `layout` | `'vertical' \| 'horizontal'` | No | Radio button layout direction |
+| `value` | `string` | No | Controlled selected value |
+| `defaultValue` | `string` | No | Uncontrolled initial value |
+| `name` | `string` | No | Shared name for the underlying radio inputs on form submission |
+| `onChange` | `(value: string) => void` | No | Change callback |
+| `disabled` | `boolean` | No | Disables the entire group |
+| `required` | `boolean` | No | Marks the group mandatory |
+| `readOnly` | `boolean` | No | Silently ignores changes |
+| `layout` | `'vertical' \| 'horizontal'` | No | Radio button layout direction. `horizontal-stacked` is not supported. |
 
-`horizontal-stacked` layout is not supported.
+**`FuiRadio` props**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `value` | `string` | Yes | Value submitted when this option is selected |
+| `label` | `string` | Yes | Label rendered next to the radio button |
+| `disabled` | `boolean` | No | Disables interaction |
+| `id` | `string` | No | Optional id override; auto-generated when omitted |
 
 ---
 
-### `FuiInputCheckbox`
+### `FuiCheckbox`
 
 Checkbox with optional read-only mode.
 
 ```tsx
-<FuiInputCheckbox
+<FuiCheckbox
   label="I agree to the terms"
-  labelPosition="after"
   checked={agreed}
-  onChange={(data) => setAgreed(!!data.checked)}
+  onChange={setAgreed}
 />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `onChange` | `(data: CheckboxOnChangeData) => void` | No | Change callback |
+| `label` | `string` | Yes | Text label rendered next to the checkbox |
+| `checked` | `boolean` | No | Checked state. Defaults to `false`. |
+| `onChange` | `(checked: boolean) => void` | Yes | Change callback — receives `boolean` directly |
+| `disabled` | `boolean` | No | Disables interaction |
 | `readOnly` | `boolean` | No | Visually interactive but ignores changes |
 
 ---
 
-### `FuiInputSwitch`
+### `FuiSwitch`
 
 Toggle switch. `onChange` delivers a `boolean` directly.
 
 ```tsx
-<FuiInputSwitch
+<FuiSwitch
   label="Receive notifications"
   checked={notifications}
   onChange={setNotifications}
@@ -442,14 +473,18 @@ Toggle switch. `onChange` delivers a `boolean` directly.
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
+| `label` | `string` | Yes | Text displayed next to the switch |
+| `checked` | `boolean` | No | Checked state. Defaults to `false`. |
+| `defaultChecked` | `boolean` | No | Initial value for uncontrolled usage |
 | `onChange` | `(value: boolean) => void` | Yes | Change callback — receives `boolean` directly |
+| `disabled` | `boolean` | No | Disables interaction |
 | `readOnly` | `boolean` | No | Silently ignores changes |
 
 ---
 
 ### `FuiInputMultiLangText`
 
-Text input for multi-language values. A translate icon opens a drawer with one field per configured language (up to 3). Language names are set via the `inputMultiLang.label.languages` provider config.
+Text input for multi-language values. A translate icon opens a drawer with one field per configured language (up to 3).
 
 ```tsx
 <FuiInputMultiLangText
@@ -474,8 +509,8 @@ type MultiLangText = {
 | `value` | `MultiLangText \| null` | Yes | Multi-language text value |
 | `onChange` | `(value: MultiLangText \| null) => void` | Yes | Change callback |
 | `label` | `string` | Yes | Field label — also used as the drawer title |
-| `languages` | `string[]` | No | Names of each language slot shown in the drawer (up to 3). When fewer than 2 are provided, the translate icon is hidden. |
-| `textComponent` | `ComponentType<InputTextProps>` | No | Overrides the inner text component. Defaults to `FuiInputText`. |
+| `langLabel` | `{ languages: string[] }` | No | Names of each language slot shown in the drawer (up to 3). When fewer than 2 are provided, the translate icon is hidden. |
+| `textComponent` | `ComponentType<FuiInputTextProps>` | No | Overrides the inner text component. Defaults to `FuiInputText`. |
 
 ---
 
@@ -601,7 +636,7 @@ Tabbed panel. On mobile the tab bar becomes horizontally scrollable. Vertical la
 
 ### `FuiImageCarousel`
 
-Circular image carousel with autoplay and navigation controls. Tooltip labels are read from `component.imageCarousell.label` in the provider config.
+Circular image carousel with autoplay and navigation controls.
 
 ```tsx
 <FuiImageCarousel
@@ -637,6 +672,270 @@ Flex row of action buttons. Collapses to full-width stacked column on mobile.
 
 ---
 
+### `FuiButton` / `FuiIconButton`
+
+Button with appearance/size/icon. `FuiIconButton` is a thin wrapper that always renders icon-only (no children) and defaults to a `subtle` appearance, for toolbar/close-button usage.
+
+```tsx
+<FuiButton appearance="primary" onClick={onSave}>Save</FuiButton>
+
+<FuiIconButton aria-label="Close" icon={<DismissRegular />} onClick={onClose} />
+```
+
+**`FuiButton` props**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `appearance` | `'primary' \| 'outline' \| 'subtle' \| 'transparent' \| 'secondary'` | No | Defaults to `'secondary'` |
+| `size` | `'small' \| 'medium' \| 'large'` | No | Defaults to `'medium'` |
+| `icon` | `ReactElement` | No | Icon rendered alongside the label |
+| `iconPosition` | `'before' \| 'after'` | No | Side of the label the icon is rendered on. Defaults to `'before'`. |
+| `children` | `ReactNode` | No | Button label |
+
+`FuiIconButton` takes the same props minus `children`/`iconPosition`, with `icon` and `aria-label` required.
+
+---
+
+### `FuiToggle`
+
+Pressable toggle button (`ToggleButton`).
+
+```tsx
+<FuiToggle checked={bold} icon={<TextBoldRegular />} onClick={() => setBold((v) => !v)} />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `checked` | `boolean` | No | Controlled pressed state |
+| `defaultChecked` | `boolean` | No | Initial pressed state for uncontrolled usage. Defaults to `false`. |
+| `appearance` | `'primary' \| 'outline' \| 'subtle' \| 'transparent' \| 'secondary'` | No | Defaults to `'secondary'` |
+| `size` | `'small' \| 'medium' \| 'large'` | No | Defaults to `'medium'` |
+| `icon` | `ReactElement` | No | Icon rendered alongside the label |
+| `iconPosition` | `'before' \| 'after'` | No | Defaults to `'before'` |
+
+---
+
+### `FuiDivider`
+
+Thin horizontal rule used to separate page sections, with an optional centered label.
+
+```tsx
+<FuiDivider>Section Title</FuiDivider>
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `ReactNode` | No | Optional label rendered centered on the divider line |
+
+---
+
+### `FuiText` and typography variants
+
+Typography element covering FluentUI's Label/Title1/Title2/Subtitle1/Subtitle2/Body1/Body2/Caption1/Caption2. `FuiLabel`, `FuiTitle1`, `FuiTitle2`, `FuiSubTitle1`, `FuiSubTitle2`, `FuiBody1`, `FuiBody2`, `FuiCaption1`, `FuiCaption2` are `FuiText` fixed to the matching `type`.
+
+```tsx
+<FuiTitle1>Page heading</FuiTitle1>
+<FuiText type="body2" text="Body copy" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | Yes | Text content to display |
+| `type` | `'label' \| 'title1' \| 'title2' \| 'subTitle1' \| 'subTitle2' \| 'body1' \| 'body2' \| 'caption1' \| 'caption2'` | No | Defaults to `'label'`. Ignored on the fixed-type variants. |
+| `italic` | `boolean` | No | Defaults to `false` |
+| `bold` | `boolean` | No | Overrides the type's default weight. Defaults to `false`. |
+| `block` | `boolean` | No | Renders as a block-level element instead of inline. Defaults to `false`. |
+
+---
+
+### `FuiTooltip`
+
+Wraps arbitrary content with a small message shown on hover (a `Tooltip`) or on click (a `Popover`, since Fluent's `Tooltip` has no click-triggered mode). If the wrapped element is itself disabled (`disabled` or `aria-disabled`), no affordance is added and the message never shows.
+
+```tsx
+<FuiTooltip text="Delete this record">
+  <FuiIconButton aria-label="Delete" icon={<DeleteRegular />} onClick={onDelete} />
+</FuiTooltip>
+
+<FuiTooltip showOn="click" text="Copied!" position="top">
+  <FuiButton onClick={copyToClipboard}>Copy</FuiButton>
+</FuiTooltip>
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | Yes | Text shown in the tooltip/popover |
+| `children` | `ReactElement` | Yes | A single element to wrap |
+| `showOn` | `'hover' \| 'click'` | No | Defaults to `'hover'` |
+| `dismissMs` | `number` | No | When `showOn` is `'click'`, ms of inactivity before auto-dismiss. Defaults to `2000`. |
+| `position` | `'top' \| 'bottom' \| 'left' \| 'right'` | No | Defaults to the underlying component's own placement |
+
+---
+
+### `FuiAccordion` / `FuiAccordionItem`
+
+Groups collapsible `FuiAccordionItem` panels, controlling which are expanded — single- or multi-expand.
+
+```tsx
+<FuiAccordion value={openItem} onChange={setOpenItem} collapsible>
+  <FuiAccordionItem header="Details" value="details">
+    <DetailsForm />
+  </FuiAccordionItem>
+  <FuiAccordionItem header="Preferences" value="preferences">
+    <PreferencesForm />
+  </FuiAccordionItem>
+</FuiAccordion>
+```
+
+**`FuiAccordion` props**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `value` / `onChange` | `string` / `(value: string) => void` | Yes | Controlled expanded value (single mode, default) |
+| `value` / `onChange` (when `multiple`) | `string[]` / `(value: string[]) => void` | Yes | Controlled expanded values (multi mode) |
+| `multiple` | `boolean` | No | Allow more than one panel open at once. Defaults to `false`. |
+| `collapsible` | `boolean` | No | When the open panel can be collapsed to leave none open. Not applicable when `multiple`. Defaults to `false`. |
+| `expandIcon` | `ReactElement` | No | Overrides the default expand/collapse icon for every item |
+| `expandIconPosition` | `'start' \| 'end'` | No | Defaults to `'start'` |
+| `withDivider` | `boolean` | No | Renders a divider between panels. Defaults to `true`. |
+
+**`FuiAccordionItem` props**
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `value` | `string` | Yes | Unique identifier for this panel |
+| `header` | `ReactNode` | Yes | Clickable header content |
+| `disabled` | `boolean` | No | Disables toggling this item |
+| `expandIcon` | `ReactElement` | No | Per-item icon override, falls back to the parent's `expandIcon` |
+
+---
+
+### `FuiCard` / `FuiCardHeader` / `FuiCardPreview` / `FuiCardFooter`
+
+Content-display container for a single topic's header, preview and footer.
+
+```tsx
+<FuiCard>
+  <FuiCardHeader header="Quarterly Report" description="Q2 2026" />
+  <FuiCardPreview>
+    <img alt="" src="/report-preview.png" />
+  </FuiCardPreview>
+  <FuiCardFooter>
+    <FuiButton onClick={onView}>View</FuiButton>
+  </FuiCardFooter>
+</FuiCard>
+```
+
+| Prop (`FuiCard`) | Type | Required | Description |
+|-------------------|------|----------|-------------|
+| `appearance` | `'filled' \| 'filled-alternative' \| 'outline' \| 'subtle'` | No | Defaults to `'filled'` |
+| `orientation` | `'horizontal' \| 'vertical'` | No | Defaults to `'vertical'` |
+| `size` | `'small' \| 'medium' \| 'large'` | No | Controls border radius and inner spacing. Defaults to `'medium'`. |
+
+| Prop (`FuiCardHeader`) | Type | Description |
+|-------------------------|------|-------------|
+| `image` | `ReactElement \| string \| number` | Image or avatar related to the card |
+| `header` | `ReactElement \| string \| number` | Main header title |
+| `description` | `ReactElement \| string \| number` | Short description related to the title |
+| `action` | `ReactElement \| string \| number` | Content at the far end, e.g. an overflow menu button |
+
+| Prop (`FuiCardPreview`) | Type | Description |
+|---------------------------|------|-------------|
+| `logo` | `ReactElement \| string \| number` | Small badge overlaid on the preview content |
+| `children` | `ReactNode` | The preview image or content itself |
+
+| Prop (`FuiCardFooter`) | Type | Description |
+|--------------------------|------|-------------|
+| `action` | `ReactElement \| string \| number` | Content at the far end, e.g. a single icon button |
+| `children` | `ReactNode` | Main footer content, e.g. action buttons |
+
+---
+
+### `FuiDrawer` / `FuiDrawerHeader` / `FuiDrawerBody`
+
+Panel that hosts supplementary content or a management experience, dismissible ('overlay') or stacked with the page ('inline'). Forced to a bottom position on mobile regardless of `position`.
+
+```tsx
+<FuiDrawer open={open} onOpenChange={setOpen} position="end">
+  <FuiDrawerHeader
+    title="Filters"
+    action={<FuiIconButton aria-label="Close" icon={<DismissRegular />} onClick={() => setOpen(false)} />}
+  />
+  <FuiDrawerBody>
+    <FiltersForm />
+  </FuiDrawerBody>
+</FuiDrawer>
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `open` | `boolean` | Yes | Controlled open state |
+| `onOpenChange` | `(open: boolean) => void` | Yes | Fires on Escape, backdrop click, etc. |
+| `position` | `'start' \| 'end' \| 'bottom'` | No | Defaults to `'start'`. Ignored (always `'bottom'`) on mobile. |
+| `size` | `'small' \| 'medium' \| 'large' \| 'full'` | No | Defaults to `'small'` |
+| `type` | `'overlay' \| 'inline'` | No | Defaults to `'overlay'` |
+| `modalType` | `'modal' \| 'non-modal' \| 'alert'` | No | Overlay-only. Defaults to `'modal'`. |
+| `separator` | `boolean` | No | Inline-only. Defaults to `false`. |
+
+`FuiDrawerHeader` takes `title`/`action`; `FuiDrawerBody` renders scrollable main content.
+
+---
+
+### `FuiMenuBar`
+
+A horizontal bar of dropdown menus, e.g. a desktop-app-style File/Edit/View menu.
+
+```tsx
+<FuiMenuBar>
+  <FuiMenuBarMenu label="File">
+    <FuiMenuBarItem icon={<DocumentAddRegular />} shortcut="Ctrl+N" onClick={onNew}>
+      New
+    </FuiMenuBarItem>
+    <FuiMenuBarSeparator />
+    <FuiMenuBarCheckboxItem checked={autosave} onCheckedChange={setAutosave}>
+      Autosave
+    </FuiMenuBarCheckboxItem>
+    <FuiMenuBarSub label="Export as">
+      <FuiMenuBarRadioGroup value={format} onValueChange={setFormat}>
+        <FuiMenuBarRadioItem value="pdf">PDF</FuiMenuBarRadioItem>
+        <FuiMenuBarRadioItem value="csv">CSV</FuiMenuBarRadioItem>
+      </FuiMenuBarRadioGroup>
+    </FuiMenuBarSub>
+  </FuiMenuBarMenu>
+</FuiMenuBar>
+```
+
+| Component | Key props |
+|---|---|
+| `FuiMenuBar` | `children`: one or more `FuiMenuBarMenu` |
+| `FuiMenuBarMenu` | `label`, `disabled` |
+| `FuiMenuBarItem` | `icon`, `shortcut`, `disabled`, `onClick` |
+| `FuiMenuBarCheckboxItem` | `checked`, `onCheckedChange`, `disabled`, `shortcut` |
+| `FuiMenuBarRadioGroup` | `value`, `onValueChange` — wraps `FuiMenuBarRadioItem` children |
+| `FuiMenuBarRadioItem` | `value`, `disabled` |
+| `FuiMenuBarSeparator` | `className` |
+| `FuiMenuBarLabel` | Non-interactive group heading |
+| `FuiMenuBarSub` | `label`, `disabled` — nested dropdown, triggered from within a parent menu |
+
+---
+
+### `FuiBreadcrumb`
+
+Renders the current trail from `useBreadcrumb()`. The last item is shown as the current page; earlier items without an action are non-interactive labels. Once there are at least 3 items, clicking the last item toggles a collapsed first > … > last view.
+
+```tsx
+const breadcrumb = useBreadcrumb();
+
+breadcrumb.start({ label: () => 'Home', action: () => navigate('/') });
+breadcrumb.append({ label: () => 'Settings', action: () => navigate('/settings') });
+
+<FuiBreadcrumb />
+```
+
+`FuiBreadcrumb` takes no props — it's entirely driven by `useBreadcrumb()`.
+
+---
+
 ## Toast notifications
 
 Use the `useToast()` hook to show non-blocking feedback.