@bfrs/agentic-components 0.2.8 → 0.3.1

package/BFRS_AGENTIC_COMPONENTS.md

@@ -24,10 +24,19 @@ import "@bfrs/agentic-components/styles";
 
 The stylesheet is safe to import globally. It does not ship Tailwind preflight, page-level resets, font-face declarations, unprefixed utilities, or generic keyframes.
 
+The main stylesheet references the SF Pro family by name only (`--bfrs-font-sans`) and ships no font files. To have the library download and apply SF Pro across the **whole app**, additionally import the opt-in font stylesheet:
+
+```tsx
+import "@bfrs/agentic-components/styles";
+import "@bfrs/agentic-components/fonts.css";
+```
+
+`fonts.css` bundles the SF Pro Display webfont (relative URLs, so any base path works), defines `--bfrs-font-sans` at the document root, and applies it to `html, body`. Angular consumers import it the same way (`@import "@bfrs/agentic-components/fonts.css";` in `styles.scss`, or add `dist/fonts.css` to the `angular.json` styles array). Skip it if the host app provides its own font.
+
 Import components by name:
 
 ```tsx
-import { BfrsProvider, Button, Input, Slider, ColorPicker, ColorSwatchGroup, RevealAndCopy, Modal, DataTable, DateRangePicker, ToastProvider, useToast } from "@bfrs/agentic-components";
+import { BfrsProvider, Button, Input, Slider, ColorPicker, ColorSwatchGroup, OptionCardGroup, NumberStepper, SuggestInput, FileDropzone, RevealField, RevealAndCopy, Modal, DataTable, DateRangePicker, ToastProvider, useToast } from "@bfrs/agentic-components";
 ```
 
 React consumers should wrap BFRS surfaces in `BfrsProvider`; the provider owns `--bfrs-*` variables, color scheme, and portal inheritance.
@@ -106,11 +115,11 @@ Use native Angular DOM event bindings for interactions. Do not pass React-style
 <bfrs-paper (click)="openDetails()">Open details</bfrs-paper>
 ```
 
-Registered tags cover the documented component surface: `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`, `bfrs-grid`, `bfrs-text`, `bfrs-icon`, `bfrs-button`, `bfrs-icon-button`, `bfrs-form-field`, `bfrs-label`, `bfrs-input`, `bfrs-slider`, `bfrs-color-picker`, `bfrs-color-swatch-group`, `bfrs-textarea`, `bfrs-select`, `bfrs-date-range-picker`, `bfrs-searchable-select`, `bfrs-checkbox`, `bfrs-radio`, `bfrs-switch`, `bfrs-badge`, `bfrs-chip`, `bfrs-alert`, `bfrs-toast-manager`, `bfrs-spinner`, `bfrs-skeleton`, `bfrs-empty-state`, `bfrs-error-state`, `bfrs-loading-state`, `bfrs-modal`, `bfrs-drawer`, `bfrs-confirm-dialog`, `bfrs-dropdown`, `bfrs-tooltip`, `bfrs-popover`, `bfrs-avatar`, `bfrs-metric-card`, `bfrs-table-pagination`, `bfrs-data-table`, `bfrs-tabs`, `bfrs-breadcrumbs`, `bfrs-action-menu`, `bfrs-page-header`, `bfrs-section-header`, `bfrs-layout-shell`, `bfrs-form-section`, `bfrs-filter-bar`, `bfrs-filter-drawer`, `bfrs-chat-bubble`, `bfrs-chat-composer`, `bfrs-full-page-loader`, `bfrs-business-info-display-card`, `bfrs-reveal-and-copy`, and `bfrs-step-progress-card`.
+Registered tags cover the documented component surface: `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`, `bfrs-grid`, `bfrs-text`, `bfrs-icon`, `bfrs-button`, `bfrs-icon-button`, `bfrs-form-field`, `bfrs-label`, `bfrs-input`, `bfrs-slider`, `bfrs-color-picker`, `bfrs-color-swatch-group`, `bfrs-textarea`, `bfrs-select`, `bfrs-date-range-picker`, `bfrs-searchable-select`, `bfrs-multi-select`, `bfrs-suggest-input`, `bfrs-option-card-group`, `bfrs-selectable-chip-group`, `bfrs-number-stepper`, `bfrs-file-dropzone`, `bfrs-reveal-field`, `bfrs-checkbox`, `bfrs-radio`, `bfrs-switch`, `bfrs-badge`, `bfrs-chip`, `bfrs-alert`, `bfrs-info-card`, `bfrs-tip`, `bfrs-toast-manager`, `bfrs-spinner`, `bfrs-skeleton`, `bfrs-empty-state`, `bfrs-error-state`, `bfrs-loading-state`, `bfrs-modal`, `bfrs-drawer`, `bfrs-confirm-dialog`, `bfrs-dropdown`, `bfrs-tooltip`, `bfrs-popover`, `bfrs-avatar`, `bfrs-metric-card`, `bfrs-table-pagination`, `bfrs-data-table`, `bfrs-tabs`, `bfrs-breadcrumbs`, `bfrs-action-menu`, `bfrs-page-header`, `bfrs-section-header`, `bfrs-layout-shell`, `bfrs-form-section`, `bfrs-filter-bar`, `bfrs-filter-drawer`, `bfrs-chat-bubble`, `bfrs-chat-composer`, `bfrs-full-page-loader`, `bfrs-business-info-display-card`, `bfrs-collapsible`, `bfrs-accordion`, `bfrs-summary-bar`, `bfrs-entity-display-card`, `bfrs-reveal-and-copy`, and `bfrs-step-progress-card`.
 
 Use attributes for simple props: `variant`, `size`, `tone`, `label`, `loading`, `disabled`, `required`, `error-message`, `error-text`, `helper-text`, `prefix`, `suffix`, `min`, `max`, `step`, and `value`. Use `[props]` or the `props` JSON attribute for structured props like `options`, palette arrays, `items`, `columns`, `data`, `sections`, `steps`, and `toasts`.
 
-Common component events: `(value-change)`, `(checked-change)`, `(open-change)`, `(reveal-change)`, `(copy)`, `(copy-error)`, `(close)`, `(confirm)`, `(cancel)`, `(row-click)`, `(sort-change)`, `(page-change)`, `(page-size-change)`, `(action-select)`, `(dropdown-select)`, `(date-range-change)`, `(search-change)`, `(open-filters)`, `(apply)`, `(reset)`, and `(submit)`. Payloads are available on `$event.detail`.
+Common component events: `(value-change)`, `(checked-change)`, `(open-change)`, `(reveal-change)`, `(copy)`, `(copy-error)`, `(close)`, `(confirm)`, `(cancel)`, `(cell-action)`, `(row-click)`, `(sort-change)`, `(page-change)`, `(page-size-change)`, `(action-select)`, `(dropdown-select)`, `(date-range-change)`, `(search-change)`, `(open-filters)`, `(apply)`, `(reset)`, and `(submit)`. Payloads are available on `$event.detail`.
 
 For validated forms, keep client validation, API validation, and submit side effects in the consuming app. In React, pass field errors through `FormField errorText` and set `Input error`. In Angular, use `bfrs-input` with `[attr.error]` and `[attr.error-message]`, listen to `(value-change)`, and manage success/failure notifications with `bfrs-toast-manager`.
 
@@ -138,7 +147,7 @@ For validated forms, keep client validation, API validation, and submit side eff
 - All interactive components forward refs and spread native HTML props
 - Styling uses **Tailwind CSS** + **CVA** with the `bfrs-` utility prefix. Use classes such as `bfrs-flex`, `hover:bfrs-bg-primary`, and `bfrs-animate-shimmer` when you intentionally depend on library utilities. Unprefixed classes are treated as host-app classes.
 - Use the `cn()` utility from the library for conditional class merging; it merges prefixed BFRS utilities and preserves unprefixed host classes.
-- **Card surface standard** — all card-like components (`Card`, `MetricCard`, `FormSection`, `BusinessInfoDisplayCard`, and `StepProgressCard` when `surface="card"`) share the same surface style: `border-radius: 12px`, a faded green-grey gradient stroke (`bfrs-faded-card-border`), `background: linear-gradient(168deg, #FFF 8.6%, #FFFFFD 97.41%)`, `box-shadow: 0 0 21.7px 0 rgba(24, 240, 64, 0.03)`. Do not override these properties unless intentionally switching to a `muted` or `soft` variant.
+- **Card surface standard** — default/elevated card-like components (`Card`, `MetricCard`, `FormSection`, `BusinessInfoDisplayCard`, and `StepProgressCard` when `surface="card"`) use the faded green-grey gradient stroke (`bfrs-faded-card-border`) and tokenized white surface. `Card variant="bordered"` and `Paper variant="outlined"` intentionally use the plain reference card spec: `border-radius: 12px`, `border: 1px solid hsl(var(--bfrs-color-border))`, `background: surface`, `box-shadow: none`, and default medium padding of `18px 22px`.
 
 ```tsx
 import { cn } from "@bfrs/agentic-components";
@@ -219,7 +228,7 @@ Flexbox layout. Use instead of writing flex utility classes directly.
 
 #### `Grid`
 
-Responsive CSS grid layout.
+Responsive CSS grid layout. Use numeric shortcuts for common responsive grids or pass a custom CSS template/min column width for form layouts.
 
 ```tsx
 <Grid columns={3} gap="md">
@@ -227,11 +236,16 @@ Responsive CSS grid layout.
   <Card />
   <Card />
 </Grid>
+
+<Grid templateColumns="2fr 1fr" />
+<Grid minColumnWidth="220px" />
 ```
 
 | Prop | Type | Default |
 |------|------|---------|
-| `columns` | `1 \| 2 \| 3 \| 4` | `3` |
+| `columns` | `1 \| 2 \| 3 \| 4 \| string` | `3` |
+| `templateColumns` | `string` | — |
+| `minColumnWidth` | `string` | — |
 | `gap` | `"sm" \| "md" \| "lg"` | `"md"` |
 
 ---
@@ -243,14 +257,19 @@ Semantic typography. Always use this instead of raw `<p>`, `<h1>`, `<span>` for
 ```tsx
 <Text variant="h2">Welcome back</Text>
 <Text variant="body" tone="muted">Last seen 2 hours ago</Text>
+<Text variant="caption" weight="bold">Bold small label</Text>
+<Text variant="h1" weight="normal">Light large heading</Text>
 ```
 
 | Prop | Type | Default |
 |------|------|---------|
-| `variant` | `"display" \| "h1" \| "h2" \| "h3" \| "title" \| "body" \| "body-sm" \| "caption" \| "label"` | `"body"` |
+| `variant` | `"display" \| "h1" \| "h2" \| "h3" \| "title" \| "body" \| "body-sm" \| "body-xs" \| "caption" \| "label"` | `"body"` |
 | `tone` | `"primary" \| "secondary" \| "muted" \| "disabled" \| "danger" \| "success" \| "accent"` | `"primary"` |
+| `weight` | `"normal" \| "medium" \| "semibold" \| "bold"` | per variant |
 | `as` | `ElementType` | inferred from variant |
 
+Each variant ships a sensible default weight; pass `weight` to override it — e.g. make a small `caption`/`body-xs` bold, or a large `h1`/`display` normal.
+
 ---
 
 #### `Icon`
@@ -458,6 +477,8 @@ Single-value dropdown. Options are `{ value: string; label: string }`.
 | `disabled` | `boolean` | `false` |
 | `error` | `boolean` | `false` |
 
+The selected value never wraps: it truncates with an ellipsis when it is too long for the trigger, and the full value appears in a tooltip on hover.
+
 ---
 
 #### `DateRangePicker`
@@ -519,6 +540,126 @@ Combobox with search. Use when options list is long (10+).
 
 ---
 
+#### `MultiSelect`
+
+Searchable multi-value select. Use for channel/category filters or any bounded list where more than one option can be selected.
+
+```tsx
+<MultiSelect
+  options={channels}
+  value={selectedChannels}
+  onValueChange={setSelectedChannels}
+  placeholder="Select channels"
+  searchPlaceholder="Search channels..."
+/>
+```
+
+Angular custom element:
+
+```html
+<bfrs-multi-select
+  placeholder="Select channels"
+  [props]="{ options: channelOptions, value: channels }"
+  (value-change)="channels = $event.detail.value">
+</bfrs-multi-select>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `options` | `{ value: string; label: string; disabled?: boolean }[]` | **required** |
+| `value` | `string[]` | — |
+| `defaultValue` | `string[]` | `[]` |
+| `onValueChange` | `(value: string[]) => void` | — |
+| `placeholder` | `string` | `"Select"` |
+| `searchPlaceholder` | `string` | `"Search..."` |
+| `emptyText` | `string` | `"No results found"` |
+| `loading` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `clearable` | `boolean` | `true` |
+| `maxVisibleValues` | `number` | `2` |
+
+---
+
+#### `OptionCardGroup`
+
+Bordered selectable option cards for radio-style choices. Supports optional description, icon, disabled state, and help tooltip text.
+
+```tsx
+<OptionCardGroup
+  value={mode}
+  onValueChange={setMode}
+  options={[
+    { value: "standard", label: "Standard", description: "Lowest cost option.", helpText: "Best for flexible delivery." },
+    { value: "express", label: "Express", description: "Prioritize faster pickup." }
+  ]}
+/>
+```
+
+Angular: `<bfrs-option-card-group [props]="{ options, value }" (value-change)="value = $event.detail.value"></bfrs-option-card-group>`.
+
+---
+
+#### `SelectableChipGroup`
+
+Segmented icon/label chips with selected state and optional trailing add action. Use `multiple` for checkbox-like chip groups.
+
+```tsx
+<SelectableChipGroup multiple value={channels} options={channelOptions} addAction={{ label: "Add" }} onValueChange={setChannels} />
+```
+
+Angular: `<bfrs-selectable-chip-group multiple [props]="{ options, value }" (value-change)="value = $event.detail.value"></bfrs-selectable-chip-group>`.
+
+---
+
+#### `NumberStepper`
+
+Quantity input rendered as decrement, value, increment controls.
+
+```tsx
+<NumberStepper value={quantity} min={1} max={10} onValueChange={setQuantity} />
+```
+
+Angular: `<bfrs-number-stepper [value]="quantity" min="1" max="10" (value-change)="quantity = $event.detail.value"></bfrs-number-stepper>`.
+
+---
+
+#### `SuggestInput`
+
+Free-text input with async-friendly suggestions dropdown. Use when the user may type arbitrary text; use `SearchableSelect` when the final value must be from a bounded option list.
+
+```tsx
+<SuggestInput value={city} suggestions={citySuggestions} onValueChange={setCity} onSuggestionSelect={setSelectedCity} />
+```
+
+Angular: `<bfrs-suggest-input [props]="{ suggestions, value }" (value-change)="value = $event.detail.value"></bfrs-suggest-input>`.
+
+---
+
+#### `FileDropzone`
+
+Drag/drop file selection area. Uploading, validation, and API side effects remain app-owned.
+
+```tsx
+<FileDropzone title="Upload invoice" accept="application/pdf,image/*" onFilesChange={setFiles} />
+```
+
+Angular: `<bfrs-file-dropzone title="Upload invoice" (files-change)="files = $event.detail.files"></bfrs-file-dropzone>`.
+
+---
+
+#### `RevealField`
+
+Field-level masked value with reveal and optional copy action, built on `RevealAndCopy`.
+
+```tsx
+<RevealField label="Phone" value="9876543210" allowCopy helperText="Only reveal when required." />
+```
+
+Angular: `<bfrs-reveal-field label="Phone" value="9876543210"></bfrs-reveal-field>`.
+
+---
+
 #### `Slider`
 
 Controlled numeric range control. Use instead of raw `<input type="range">`.
@@ -794,6 +935,30 @@ Contextual message banner. Auto-selects an icon based on tone.
 
 ---
 
+#### `InfoCard`
+
+Flexible callout with leading colored icon, title, description, optional actions, and semantic tone.
+
+```tsx
+<InfoCard tone="info" title="Courier allocation is ready" description="Review serviceability before assigning the shipment." />
+```
+
+Angular: `<bfrs-info-card title="Courier allocation is ready" description="Review serviceability before assigning the shipment."></bfrs-info-card>`.
+
+---
+
+#### `Tip`
+
+Small subtle accent pill for hints such as recommended, verified, or review states.
+
+```tsx
+<Tip tone="success">Verified</Tip>
+```
+
+Angular: `<bfrs-tip tone="success">Verified</bfrs-tip>`.
+
+---
+
 #### `ToastProvider`, `useToast`, `ToastManager`
 
 App-wide transient feedback manager. Wrap the app once, then call toast helpers from event handlers.
@@ -1129,6 +1294,30 @@ Generic data table with sorting, loading skeleton, row actions, selection, pagin
 
 When `loading` is true, `DataTable` renders built-in table-row skeleton placeholders rather than a spinner. The consumer app only owns the loading boolean.
 
+Custom-element DataTable action cells must be declarative because Angular/HTML cannot pass React `cell` functions through JSON. Use `cellType: "button"` for one inline button, `cellType: "buttons"` for multiple inline buttons, or `cellType: "actions"` for an action menu. Action clicks emit `cell-action` with `{ actionId, columnId, row, rowId, rowIndex }` and do not trigger `row-click`.
+
+```html
+<bfrs-data-table
+  [props]="{
+    data: orders,
+    columns: [
+      { id: 'orderId', header: 'Order ID', accessorKey: 'orderId' },
+      {
+        id: 'actions',
+        header: 'Actions',
+        cellType: 'buttons',
+        actions: [
+          { id: 'view', label: 'View', variant: 'outline', size: 'sm', iconName: 'eye' },
+          { id: 'ship', label: 'Ship now', variant: 'primary', size: 'sm', disabledKey: 'shipDisabled' }
+        ]
+      }
+    ]
+  }"
+  (cell-action)="handleTableAction($event.detail)"
+  (row-click)="openOrder($event.detail.row)">
+</bfrs-data-table>
+```
+
 ---
 
 ### Navigation
@@ -1244,6 +1433,80 @@ Full-page app shell with sticky header and collapsible sidebar.
 
 ---
 
+#### `WorkspaceHeader`
+
+Slot-based top bar for Agentic Platform workspaces. It preserves the standalone prototype chrome by default: 52px header height, 216px brand rail, 380px chat/workspace rail, 300px search slot, strong dividers, and compact 26px sidebar toggle. Product-specific brand, tab title/collapse controls, search internals, wallet, launcher, and avatar remain app-owned slots.
+
+```tsx
+<WorkspaceHeader
+  brand={<ShiprocketBrand />}
+  onToggleSidebar={toggleSidebar}
+  tabs={<ActiveWorkspaceTab />}
+  search={<HeaderJumpSearch />}
+  actions={<HeaderActions />}
+/>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `brand` | `ReactNode` | — |
+| `brandWidth` | `number` | `216` |
+| `brandCollapsed` | `boolean` | `false` |
+| `collapsedBrandWidth` | `number` | `56` |
+| `onToggleSidebar` | `() => void` | — |
+| `toggleLabel` | `string` | `"Toggle sidebar"` |
+| `tabs` | `ReactNode` | — |
+| `tabsWidth` | `number` | `380` |
+| `tabsCollapsed` | `boolean` | `false` |
+| `collapsedTabsWidth` | `number` | `40` |
+| `search` | `ReactNode` | — |
+| `searchWidth` | `number` | `300` |
+| `actions` | `ReactNode` | — |
+| `children` | `ReactNode` | — |
+| `height` | `number` | `52` |
+
+Use `brandCollapsed` and `tabsCollapsed` to mirror the standalone collapsed sidebar/chat rails. Use explicit widths only when the host app intentionally diverges from the prototype.
+
+---
+
+#### `SideNav`
+
+Collapsible application sidebar navigation. Renders grouped sections of items with active state, badges, and hover flyouts for nested items, plus `header`, `footer`, and `children` slots. All data (labels, icons, handlers) is passed in — the component owns layout and collapse behavior.
+
+```tsx
+<SideNav
+  collapsed={collapsed}
+  sections={[
+    {
+      id: "nav",
+      items: [
+        { id: "orders", label: "Orders", icon: <Icon icon={Package} />, active: true, onSelect: goOrders },
+        { id: "finance", label: "Finance", icon: <Icon icon={Wallet} />, nested: [
+          { id: "cod", label: "COD Remittance", onSelect: goCod },
+        ] },
+      ],
+    },
+  ]}
+  footer={<UserMenu />}
+/>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `sections` | `SideNavSection[]` | **required** |
+| `collapsed` | `boolean` | `false` |
+| `width` | `number` | `240` |
+| `collapsedWidth` | `number` | `56` |
+| `header` | `ReactNode` | — |
+| `children` | `ReactNode` | — |
+| `footer` | `ReactNode` | — |
+
+- `SideNavSection`: `{ id?, title?, items, action? }` — `title` (uppercase) and `action` are hidden when collapsed.
+- `SideNavItem`: `{ id, label, icon?, active?, badge?, nested?, onSelect? }` — `badge` is hidden when collapsed; `nested` opens a hover flyout (expanded only).
+- When `collapsed`, each row hides its `label` and surfaces it as a right-side `Tooltip` on hover, so items stay identifiable by icon alone.
+
+---
+
 #### `ChatBubble`
 
 Chat message bubble. Renders differently for `user`, `assistant`, and `system` senders. Assistant messages support a Figma-derived identity block with an uppercase eyebrow, title, and muted body copy.
@@ -1326,6 +1589,81 @@ Branded full-screen loading screen. Use during auth redirects and account setup.
 
 ---
 
+#### `Collapsible`
+
+Inline expandable section with caret, title, optional description, controlled or uncontrolled open state, and `open-change` custom-element event.
+
+```tsx
+<Collapsible title="Courier rules" description="Expandable inline section">
+  <Text variant="body-sm">Rules and restrictions.</Text>
+</Collapsible>
+```
+
+Angular: `<bfrs-collapsible title="Courier rules" (open-change)="open = $event.detail.open">Rules and restrictions</bfrs-collapsible>`.
+
+---
+
+#### `Accordion`
+
+Grouped expandable sections. Use `type="single"` (default) to keep one panel open at a time, or `type="multiple"` to allow several. Each item is `{ value, title, content, description?, disabled? }`. Use `Collapsible` instead for a single standalone disclosure.
+
+```tsx
+<Accordion
+  type="single"
+  defaultValue="pickup"
+  items={[
+    { value: "pickup", title: "Pickup details", description: "Warehouse and contact", content: <Text variant="body-sm">Plot 42, Sector 18, Gurugram.</Text> },
+    { value: "shipping", title: "Shipping preferences", content: <Text variant="body-sm">Standard delivery.</Text> }
+  ]}
+  onValueChange={setOpenSection}
+/>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `items` | `{ value: string; title: ReactNode; content: ReactNode; description?: ReactNode; disabled?: boolean }[]` | **required** |
+| `type` | `"single" \| "multiple"` | `"single"` |
+| `value` | `string \| string[]` | — |
+| `defaultValue` | `string \| string[]` | — |
+| `onValueChange` | `(value: string \| string[]) => void` | — |
+| `collapsible` | `boolean` | `true` |
+
+For `type="single"`, `value`/`defaultValue`/`onValueChange` use a string; for `type="multiple"` they use a string array.
+
+Angular: `<bfrs-accordion type="single" [props]="{ items: sections }" (value-change)="openSection = $event.detail.value"></bfrs-accordion>`. Pass each item's `content` as a string in custom-element usage.
+
+---
+
+#### `SummaryBar`
+
+Highlighted total/summary row for subtotal, charges, total, and optional note.
+
+```tsx
+<SummaryBar items={[{ label: "Subtotal", value: "₹840" }, { label: "Charges", value: "₹60" }]} totalLabel="Total" totalValue="₹900" />
+```
+
+Angular: `<bfrs-summary-bar total-label="Total" total-value="₹900" [props]="{ items }"></bfrs-summary-bar>`.
+
+---
+
+#### `EntityDisplayCard`
+
+Read-only selected address/entity card with status badge, metadata, and inline edit/action controls.
+
+```tsx
+<EntityDisplayCard
+  title="Dee-doodles warehouse"
+  description="Plot 42, Sector 18, Gurugram, Haryana"
+  status="Verified"
+  actions={[{ id: "edit", label: "Edit" }]}
+  onAction={handleAction}
+/>
+```
+
+Angular: `<bfrs-entity-display-card title="Dee-doodles warehouse" status="Verified" [props]="{ actions }" (entity-action)="handleEntityAction($event.detail.action)"></bfrs-entity-display-card>`.
+
+---
+
 #### `RevealAndCopy`
 
 Masked sensitive-value display with a reveal action and optional clipboard copy. Use for phone numbers, email addresses, tokens, and other values that should not render as plaintext until the user asks to reveal them. The plaintext value is not placed in the DOM while masked.
@@ -1440,7 +1778,7 @@ Built-in loading behavior:
 
 #### `StepProgressCard`
 
-Step-by-step progress indicator. Calculates `done` / `active` / `pending` state automatically from `currentStep` and preserves the animated completed-dot, active-star, and rail-fill transitions. Defaults to the Figma-derived plain progress block; pass `surface="card"` for the standard card wrapper.
+Step-by-step progress indicator. Calculates `done` / `active` / `pending` state automatically from `currentStep` and preserves the green completed-dot, active-star, and rail-fill transitions. Defaults to the Figma-derived plain progress block; pass `surface="card"` for the standard card wrapper.
 
 ```tsx
 <StepProgressCard

package/README.md

@@ -42,6 +42,17 @@ export function Example() {
 
 The stylesheet is safe to import globally: it does not ship Tailwind preflight, page-level resets, global font-face declarations, unprefixed utilities, or generic keyframes. React surfaces should still render inside `BfrsProvider`; the provider owns `--bfrs-*` theme variables and passes the same scope to Radix portals.
 
+### Optional: bundled SF Pro font
+
+The main stylesheet only references the SF Pro family by name (`--bfrs-font-sans`) — it ships no font files, so by default you supply the font. To have the library download and apply SF Pro across your **whole app**, additionally import the opt-in font stylesheet once at your entry point:
+
+```tsx
+import "@bfrs/agentic-components/styles";
+import "@bfrs/agentic-components/fonts.css";
+```
+
+This bundles the SF Pro Display webfont (relative URLs, so any base path works), defines `--bfrs-font-sans` at the document root, and applies it to `html, body`. Keeping it separate means the main stylesheet stays free of global `@font-face`/`html`/`body` rules.
+
 Most DOM-backed components forward compatible React props such as `onClick`, `onKeyDown`, `aria-*`, `data-*`, `className`, `style`, and refs. Controlled components expose explicit callbacks such as `onValueChange`, `onOpenChange`, `onSort`, `onRowClick`, and `onPageChange`.
 
 Library-owned Tailwind utilities are prefixed with `bfrs-`, for example `bfrs-flex`, `hover:bfrs-bg-primary`, and `bfrs-animate-shimmer`. Unprefixed classes passed through `className` are treated as host-app classes.
@@ -60,14 +71,17 @@ import "@bfrs/agentic-components/custom-elements";
 ```scss
 /* styles.scss */
 @import "@bfrs/agentic-components/styles";
+/* Optional — bundled SF Pro, applied to the whole app: */
+@import "@bfrs/agentic-components/fonts.css";
 ```
 
-If Angular does not resolve the package style export, add the built CSS file in `angular.json`:
+If Angular does not resolve the package style export, add the built CSS files in `angular.json`:
 
 ```json
 {
   "styles": [
     "node_modules/@bfrs/agentic-components/dist/style.css",
+    "node_modules/@bfrs/agentic-components/dist/fonts.css",
     "src/styles.scss"
   ]
 }
@@ -113,12 +127,30 @@ Use simple attributes for primitive values and `[props]` for structured values o
 
 <bfrs-data-table
   [props]="{ data: orders, columns: orderColumns, selection: true }"
+  (cell-action)="handleTableAction($event.detail)"
   (row-click)="openOrder($event.detail.row)"
   (sort-change)="sorting = $event.detail.sorting">
 </bfrs-data-table>
 ```
 
-Registered tags include `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`, `bfrs-grid`, `bfrs-text`, `bfrs-icon`, `bfrs-button`, `bfrs-icon-button`, `bfrs-form-field`, `bfrs-label`, `bfrs-input`, `bfrs-slider`, `bfrs-color-picker`, `bfrs-color-swatch-group`, `bfrs-textarea`, `bfrs-select`, `bfrs-date-range-picker`, `bfrs-searchable-select`, `bfrs-checkbox`, `bfrs-radio`, `bfrs-switch`, `bfrs-badge`, `bfrs-chip`, `bfrs-alert`, `bfrs-toast-manager`, `bfrs-spinner`, `bfrs-skeleton`, `bfrs-empty-state`, `bfrs-error-state`, `bfrs-loading-state`, `bfrs-modal`, `bfrs-drawer`, `bfrs-confirm-dialog`, `bfrs-dropdown`, `bfrs-tooltip`, `bfrs-popover`, `bfrs-avatar`, `bfrs-metric-card`, `bfrs-table-pagination`, `bfrs-data-table`, `bfrs-tabs`, `bfrs-breadcrumbs`, `bfrs-action-menu`, `bfrs-page-header`, `bfrs-section-header`, `bfrs-layout-shell`, `bfrs-form-section`, `bfrs-filter-bar`, `bfrs-filter-drawer`, `bfrs-chat-bubble`, `bfrs-chat-composer`, `bfrs-full-page-loader`, `bfrs-business-info-display-card`, `bfrs-reveal-and-copy`, and `bfrs-step-progress-card`.
+For DataTable action cells in Angular, use serializable column configs instead of React `cell` functions:
+
+```ts
+orderColumns = [
+  { id: "orderId", header: "Order ID", accessorKey: "orderId" },
+  {
+    id: "actions",
+    header: "Actions",
+    cellType: "buttons",
+    actions: [
+      { id: "view", label: "View", variant: "outline", size: "sm", iconName: "eye" },
+      { id: "ship", label: "Ship now", variant: "primary", size: "sm", disabledKey: "shipDisabled" }
+    ]
+  }
+];
+```
+
+Registered tags include `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`, `bfrs-grid`, `bfrs-text`, `bfrs-icon`, `bfrs-button`, `bfrs-icon-button`, `bfrs-form-field`, `bfrs-label`, `bfrs-input`, `bfrs-slider`, `bfrs-color-picker`, `bfrs-color-swatch-group`, `bfrs-textarea`, `bfrs-select`, `bfrs-date-range-picker`, `bfrs-searchable-select`, `bfrs-multi-select`, `bfrs-suggest-input`, `bfrs-option-card-group`, `bfrs-selectable-chip-group`, `bfrs-number-stepper`, `bfrs-file-dropzone`, `bfrs-reveal-field`, `bfrs-checkbox`, `bfrs-radio`, `bfrs-switch`, `bfrs-badge`, `bfrs-chip`, `bfrs-alert`, `bfrs-info-card`, `bfrs-tip`, `bfrs-toast-manager`, `bfrs-spinner`, `bfrs-skeleton`, `bfrs-empty-state`, `bfrs-error-state`, `bfrs-loading-state`, `bfrs-modal`, `bfrs-drawer`, `bfrs-confirm-dialog`, `bfrs-dropdown`, `bfrs-tooltip`, `bfrs-popover`, `bfrs-avatar`, `bfrs-metric-card`, `bfrs-table-pagination`, `bfrs-data-table`, `bfrs-tabs`, `bfrs-breadcrumbs`, `bfrs-action-menu`, `bfrs-page-header`, `bfrs-section-header`, `bfrs-layout-shell`, `bfrs-form-section`, `bfrs-filter-bar`, `bfrs-filter-drawer`, `bfrs-chat-bubble`, `bfrs-chat-composer`, `bfrs-full-page-loader`, `bfrs-business-info-display-card`, `bfrs-collapsible`, `bfrs-accordion`, `bfrs-summary-bar`, `bfrs-entity-display-card`, `bfrs-reveal-and-copy`, and `bfrs-step-progress-card`.
 
 ## Theme Overrides
 

package/dist/components/ui/feedback/InfoCard/InfoCard.d.ts

@@ -0,0 +1,16 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { Tone } from '../../../../tokens';
+export type InfoCardProps = Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    tone?: Tone;
+    icon?: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+};
+export declare const InfoCard: import('react').ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+    tone?: Tone;
+    icon?: ReactNode;
+    title: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/ui/feedback/InfoCard/index.d.ts

@@ -0,0 +1,2 @@
+export { InfoCard } from './InfoCard';
+export type { InfoCardProps } from './InfoCard';

package/dist/components/ui/feedback/Tip/Tip.d.ts

@@ -0,0 +1,8 @@
+import { HTMLAttributes } from 'react';
+import { Tone } from '../../../../tokens';
+export type TipProps = HTMLAttributes<HTMLSpanElement> & {
+    tone?: Tone;
+};
+export declare const Tip: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & {
+    tone?: Tone;
+} & import('react').RefAttributes<HTMLSpanElement>>;

package/dist/components/ui/feedback/Tip/index.d.ts

@@ -0,0 +1,2 @@
+export { Tip } from './Tip';
+export type { TipProps } from './Tip';

package/dist/components/ui/forms/FileDropzone/FileDropzone.d.ts

@@ -0,0 +1,21 @@
+import { HTMLAttributes } from 'react';
+export type FileDropzoneProps = Omit<HTMLAttributes<HTMLDivElement>, "onDrop"> & {
+    accept?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    title?: string;
+    description?: string;
+    browseLabel?: string;
+    onFilesChange?: (files: File[]) => void;
+};
+export declare const FileDropzone: import('react').ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "onDrop"> & {
+    accept?: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    title?: string;
+    description?: string;
+    browseLabel?: string;
+    onFilesChange?: (files: File[]) => void;
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/ui/forms/FileDropzone/index.d.ts

@@ -0,0 +1,2 @@
+export { FileDropzone } from './FileDropzone';
+export type { FileDropzoneProps } from './FileDropzone';

package/dist/components/ui/forms/MultiSelect/MultiSelect.d.ts

@@ -0,0 +1,20 @@
+import { SelectOption } from '../Select';
+export type MultiSelectProps = {
+    options: SelectOption[];
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    placeholder?: string;
+    searchPlaceholder?: string;
+    emptyText?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    clearable?: boolean;
+    maxVisibleValues?: number;
+    className?: string;
+    id?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: boolean;
+};
+export declare const MultiSelect: import('react').ForwardRefExoticComponent<MultiSelectProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/components/ui/forms/MultiSelect/index.d.ts

@@ -0,0 +1 @@
+export * from './MultiSelect';

package/dist/components/ui/forms/NumberStepper/NumberStepper.d.ts

@@ -0,0 +1,21 @@
+import { InputHTMLAttributes } from 'react';
+export type NumberStepperProps = Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "size" | "value"> & {
+    value?: number;
+    defaultValue?: number;
+    onValueChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    size?: "sm" | "md";
+    error?: boolean;
+};
+export declare const NumberStepper: import('react').ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange"> & {
+    value?: number;
+    defaultValue?: number;
+    onValueChange?: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    size?: "sm" | "md";
+    error?: boolean;
+} & import('react').RefAttributes<HTMLInputElement>>;

package/dist/components/ui/forms/NumberStepper/index.d.ts

@@ -0,0 +1,2 @@
+export { NumberStepper } from './NumberStepper';
+export type { NumberStepperProps } from './NumberStepper';