@bfrs/agentic-components 0.3.7 → 0.3.9

package/BFRS_AGENTIC_COMPONENTS.md

@@ -36,7 +36,31 @@ import "@bfrs/agentic-components/fonts.css";
 Import components by name:
 
 ```tsx
-import { BfrsProvider, Button, Input, Slider, ColorPicker, ColorSwatchGroup, OptionCardGroup, NumberStepper, SuggestInput, FileDropzone, RevealField, RevealAndCopy, Modal, DataTable, DateRangePicker, ToastProvider, useToast } from "@bfrs/agentic-components";
+import {
+  BfrsProvider,
+  Button,
+  FormField,
+  Input,
+  Slider,
+  ColorPicker,
+  ColorSwatchGroup,
+  OptionCardGroup,
+  SelectableChipGroup,
+  NumberStepper,
+  SuggestInput,
+  FileDropzone,
+  RevealField,
+  RevealAndCopy,
+  HorizontalStepper,
+  Modal,
+  DataTable,
+  TableColumnVisibility,
+  TableSaveView,
+  TableToolbar,
+  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.
@@ -119,9 +143,9 @@ Registered tags cover the documented component surface, including
 `bfrs-button-group`, `bfrs-toast-provider`, `bfrs-table-toolbar`,
 `bfrs-table-empty-state`, `bfrs-table-error-state`, `bfrs-table-skeleton`,
 `bfrs-table-row-actions`, `bfrs-table-bulk-actions`, and
-`bfrs-table-column-visibility` in addition to the existing component tags.
+`bfrs-table-column-visibility`, and `bfrs-table-save-view` in addition to the existing component tags.
 Existing form and pattern tags include `bfrs-date-range-picker`,
-`bfrs-multi-select`, `bfrs-step-progress-card`, `bfrs-data-table`,
+`bfrs-multi-select`, `bfrs-horizontal-stepper`, `bfrs-step-progress-card`, `bfrs-data-table`,
 `bfrs-modal`, `bfrs-tabs`, and the rest of the documented `bfrs-*` surface.
 
 ReactNode-based composition is exposed through native named slots. Angular
@@ -162,9 +186,9 @@ Mount `bfrs-toast-provider` once when Angular needs the equivalent of
 
 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)`, `(cell-action)`, `(cell-event)`, `(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)`, `(step-select)`, `(confirm)`, `(cancel)`, `(cell-action)`, `(cell-event)`, `(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`.
+For validated forms, keep client validation, API validation, and submit side effects in the consuming app. In React, wrap controls in `FormField`, pass field errors through `errorText`, and set the control's `error` prop when supported. In Angular, wrap controls that do not render their own label in `bfrs-form-field`; pass `error-text` and `helper-text` there, listen to the control's `(value-change)`, and manage success/failure notifications with `bfrs-toast-manager`.
 
 ```html
 <bfrs-select
@@ -398,7 +422,7 @@ Square button for icon-only actions. Always provide `aria-label`.
 
 ### Forms
 
-> **Rule:** Always wrap form controls in `FormField` — it handles label, helper text, error text, and aria wiring automatically.
+> **Rule:** Always wrap form controls in `FormField` — it handles label, helper text, error text, consistent spacing, and aria wiring automatically.
 
 ---
 
@@ -406,6 +430,8 @@ Square button for icon-only actions. Always provide `aria-label`.
 
 Wraps any form control with label, helper, and error text. Connects them via `aria-describedby`.
 
+The label always renders on its own block row with a `6px` vertical gap before the control. This applies consistently to full-width controls such as `Input` and inline controls such as `NumberStepper`; do not add manual margins between the label and control.
+
 ```tsx
 <FormField
   label="Email address"
@@ -415,6 +441,28 @@ Wraps any form control with label, helper, and error text. Connects them via `ar
 >
   <Input type="email" value={email} onChange={…} />
 </FormField>
+
+<FormField label="Quantity">
+  <NumberStepper
+    value={quantity}
+    min={1}
+    max={10}
+    onValueChange={setQuantity}
+  />
+</FormField>
+```
+
+Angular / Custom Elements:
+
+```html
+<bfrs-form-field label="Quantity" helper-text="Choose between 1 and 10 items.">
+  <bfrs-number-stepper
+    [value]="quantity"
+    min="1"
+    max="10"
+    (value-change)="quantity = $event.detail.value">
+  </bfrs-number-stepper>
+</bfrs-form-field>
 ```
 
 | Prop | Type | Default |
@@ -548,6 +596,7 @@ const [range, setRange] = useState<DateRangeValue>({
 | `maxRangeDays` | `number` | — |
 | `months` | `1 \| 2` | `2` |
 | `open` / `onOpenChange` | controlled popover state | — |
+| `defaultOpen` | `boolean` | `false` |
 
 Keep API date formatting, route updates, and business limits in the consuming app.
 
@@ -580,6 +629,7 @@ Combobox with search. Use when options list is long (10+).
 | `disabled` | `boolean` | `false` |
 | `error` | `boolean` | `false` |
 | `clearable` | `boolean` | `true` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
 
 ---
 
@@ -621,6 +671,7 @@ Angular custom element:
 | `error` | `boolean` | `false` |
 | `clearable` | `boolean` | `true` |
 | `maxVisibleValues` | `number` | `2` |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
 
 ---
 
@@ -657,25 +708,73 @@ Angular: `<bfrs-selectable-chip-group multiple [props]="{ options, value }" (val
 
 #### `NumberStepper`
 
-Quantity input rendered as decrement, value, increment controls.
+Quantity input rendered as decrement, value, increment controls. It is an inline-width control, so use `FormField` for its visible label and consistent label-to-control spacing.
 
 ```tsx
-<NumberStepper value={quantity} min={1} max={10} onValueChange={setQuantity} />
+<FormField label="Quantity">
+  <NumberStepper
+    value={quantity}
+    min={1}
+    max={10}
+    step={1}
+    onValueChange={setQuantity}
+  />
+</FormField>
 ```
 
-Angular: `<bfrs-number-stepper [value]="quantity" min="1" max="10" (value-change)="quantity = $event.detail.value"></bfrs-number-stepper>`.
+| Prop | Type | Default |
+|------|------|---------|
+| `value` | `number` | — |
+| `defaultValue` | `number` | `0` |
+| `onValueChange` | `(value: number) => void` | — |
+| `min` | `number` | — |
+| `max` | `number` | — |
+| `step` | `number` | `1` |
+| `size` | `"sm" \| "md"` | `"md"` |
+| `error` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+Angular:
+
+```html
+<bfrs-form-field label="Quantity">
+  <bfrs-number-stepper
+    [value]="quantity"
+    min="1"
+    max="10"
+    step="1"
+    (value-change)="quantity = $event.detail.value">
+  </bfrs-number-stepper>
+</bfrs-form-field>
+```
 
 ---
 
 #### `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.
+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. Wrap it in `FormField` when it needs a visible label, helper text, or validation message.
 
 ```tsx
-<SuggestInput value={city} suggestions={citySuggestions} onValueChange={setCity} onSuggestionSelect={setSelectedCity} />
+<FormField label="City">
+  <SuggestInput
+    value={city}
+    suggestions={citySuggestions}
+    onValueChange={setCity}
+    onSuggestionSelect={setSelectedCity}
+  />
+</FormField>
 ```
 
-Angular: `<bfrs-suggest-input [props]="{ suggestions, value }" (value-change)="value = $event.detail.value"></bfrs-suggest-input>`.
+Angular:
+
+```html
+<bfrs-form-field label="City">
+  <bfrs-suggest-input
+    [props]="{ suggestions: citySuggestions, value: city }"
+    (value-change)="city = $event.detail.value">
+  </bfrs-suggest-input>
+</bfrs-form-field>
+```
 
 ---
 
@@ -703,6 +802,82 @@ Angular: `<bfrs-reveal-field label="Phone" value="9876543210"></bfrs-reveal-fiel
 
 ---
 
+#### Additional form controls composition
+
+Use `FormField` around controls that do not own a label. This keeps Quantity and City aligned in the same grid and preserves the standard `6px` label-to-control gap without demo-specific margins.
+
+```tsx
+<Stack gap={5}>
+  <OptionCardGroup
+    value={fulfillmentMode}
+    onValueChange={setFulfillmentMode}
+    options={fulfillmentOptions}
+  />
+
+  <SelectableChipGroup
+    multiple
+    value={channels}
+    options={channelOptions}
+    addAction={{ label: "Add" }}
+    onValueChange={setChannels}
+  />
+
+  <Grid columns={2} gap={4}>
+    <FormField label="Quantity">
+      <NumberStepper
+        value={quantity}
+        min={1}
+        max={10}
+        onValueChange={setQuantity}
+      />
+    </FormField>
+
+    <FormField label="City">
+      <SuggestInput
+        value={city}
+        suggestions={citySuggestions}
+        onValueChange={setCity}
+      />
+    </FormField>
+  </Grid>
+
+  <FileDropzone
+    title="Upload invoice"
+    onFilesChange={setFiles}
+  />
+
+  <RevealField
+    label="Masked account field"
+    value="9876543210"
+    allowCopy
+  />
+</Stack>
+```
+
+Angular / Custom Elements:
+
+```html
+<bfrs-grid columns="2" gap="4">
+  <bfrs-form-field label="Quantity">
+    <bfrs-number-stepper
+      [value]="quantity"
+      min="1"
+      max="10"
+      (value-change)="quantity = $event.detail.value">
+    </bfrs-number-stepper>
+  </bfrs-form-field>
+
+  <bfrs-form-field label="City">
+    <bfrs-suggest-input
+      [props]="{ suggestions: citySuggestions, value: city }"
+      (value-change)="city = $event.detail.value">
+    </bfrs-suggest-input>
+  </bfrs-form-field>
+</bfrs-grid>
+```
+
+---
+
 #### `Slider`
 
 Controlled numeric range control. Use instead of raw `<input type="range">`.
@@ -866,20 +1041,22 @@ Radio group. Renders a list of mutually exclusive options.
   value={plan}
   onValueChange={setPlan}
   options={[
-    { value: "free", label: "Free" },
-    { value: "pro", label: "Pro" },
-    { value: "enterprise", label: "Enterprise" },
+    { value: "free", label: "Free", description: "For testing basic workflows." },
+    { value: "pro", label: "Pro", description: "For growing teams that need automation." },
+    { value: "enterprise", label: "Enterprise", description: "For custom limits and support." },
   ]}
 />
 ```
 
 | Prop | Type | Default |
 |------|------|---------|
-| `options` | `{ value: string; label: string }[]` | **required** |
+| `options` | `{ value: string; label: ReactNode; description?: ReactNode; disabled?: boolean }[]` | **required** |
 | `value` | `string` | — |
 | `onValueChange` | `(value: string) => void` | — |
 | `error` | `boolean` | `false` |
 
+Each option renders `label` as the primary text and optional `description` as secondary text below it, matching the Checkbox label stack.
+
 ---
 
 #### `Switch`
@@ -915,6 +1092,12 @@ Small inline status label.
 <Badge tone="warning">Pending</Badge>
 <Badge tone="danger">Blocked</Badge>
 <Badge count={3} aria-label="3 active filters" />
+
+{/* Sizes: xs | sm (default) | md | lg */}
+<Badge size="xs" tone="success">xs</Badge>
+<Badge size="sm" tone="success">sm</Badge>
+<Badge size="md" tone="success">md</Badge>
+<Badge size="lg" tone="success">lg</Badge>
 ```
 
 | Prop | Type | Default |
@@ -941,6 +1124,12 @@ Removable tag. Use in filter bars and multi-select UIs.
 >
   Status: Active
 </Chip>
+
+{/* Sizes: xs | sm (default) | md | lg */}
+<Chip size="xs" tone="primary">xs</Chip>
+<Chip size="sm" tone="primary">sm</Chip>
+<Chip size="md" tone="primary">md</Chip>
+<Chip size="lg" tone="primary">lg</Chip>
 ```
 
 | Prop | Type | Default |
@@ -949,10 +1138,13 @@ Removable tag. Use in filter bars and multi-select UIs.
 | `tone` | `"neutral" \| "primary" \| "brand" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` |
 | `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"sm"` |
 | `leftIcon` | `ReactNode` | — |
+| `rightIcon` | `ReactNode` | — |
 | `removable` | `boolean` | `false` |
 | `onRemove` | `() => void` | — |
 | `removeLabel` | `string` | `"Remove"` |
 
+Angular: use `left-icon="package"` / `right-icon="arrow-right"` for named Phosphor icons, or use named slots `<span slot="left-icon">…</span>`.
+
 ---
 
 #### `Alert`
@@ -967,11 +1159,18 @@ Contextual message banner. Auto-selects an icon based on tone.
 >
   Upgrade to keep access to all features.
 </Alert>
+
+{/* Sizes: xs | sm | md (default) | lg */}
+<Alert size="xs" tone="info" title="XSmall">Ultra-compact inline alert.</Alert>
+<Alert size="sm" tone="info" title="Small">Compact alert for dense layouts.</Alert>
+<Alert size="md" tone="info" title="Medium">Default alert size.</Alert>
+<Alert size="lg" tone="info" title="Large">Spacious alert for prominent messages.</Alert>
 ```
 
 | Prop | Type | Default |
 |------|------|---------|
 | `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` |
+| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` |
 | `title` | `ReactNode` | — |
 | `action` | `ReactNode` | — |
 | `icon` | `ReactNode` | auto (from tone) |
@@ -1130,6 +1329,11 @@ Centered modal. Use for confirmations, forms, and focused tasks.
 | `size` | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` |
 | `open` | `boolean` | — |
 | `onOpenChange` | `(open: boolean) => void` | — |
+| `contentClassName` | `string` | — |
+| `headerClassName` | `string` | — |
+| `footerClassName` | `string` | — |
+
+Angular: `content-class-name`, `header-class-name`, `footer-class-name` attributes.
 
 `Dialog` is a deprecated compatibility alias. Use `Modal` in new code.
 
@@ -1160,6 +1364,11 @@ Slide-out panel. Use for detail views, settings, and secondary flows.
 | `description` | `ReactNode` | — |
 | `open` | `boolean` | — |
 | `onOpenChange` | `(open: boolean) => void` | — |
+| `contentClassName` | `string` | — |
+| `headerClassName` | `string` | — |
+| `footerClassName` | `string` | — |
+
+Angular: `content-class-name`, `header-class-name`, `footer-class-name` attributes.
 
 ---
 
@@ -1204,6 +1413,7 @@ Floating label on hover. Provide `content` as the tooltip text.
 | `children` | `ReactNode` | **required** |
 | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` |
 | `delayDuration` | `number` | `350` |
+| `disabled` | `boolean` | `false` |
 
 ---
 
@@ -1228,6 +1438,43 @@ Floating content panel. Use for filters, pickers, and inline forms.
 
 ---
 
+#### `FilterDrawer`
+
+Slide-out drawer pre-wired for filter forms. Manages its own Apply / Reset footer; the consumer owns filter state and the apply logic.
+
+```tsx
+<FilterDrawer
+  title="Filter shipments"
+  open={filtersOpen}
+  onOpenChange={setFiltersOpen}
+  onApply={handleApply}
+  onReset={handleReset}
+  activeFiltersCount={activeCount}
+  footerActions={<Button variant="ghost">Save as preset</Button>}
+>
+  <StatusFilter />
+  <DateFilter />
+</FilterDrawer>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `open` | `boolean` | — |
+| `onOpenChange` | `(open: boolean) => void` | — |
+| `onApply` | `() => void` | — |
+| `onReset` | `() => void` | — |
+| `title` | `ReactNode` | `"Filters"` |
+| `description` | `ReactNode` | — |
+| `applyLabel` | `ReactNode` | `"Apply filters"` |
+| `resetLabel` | `ReactNode` | `"Reset all"` |
+| `activeFiltersCount` | `number` | `0` |
+| `applying` | `boolean` | `false` |
+| `footerActions` | `ReactNode` | — |
+
+Angular: `(apply)`, `(reset)`, `(close)` events; `<span slot="footer-actions">…</span>` for extra footer content.
+
+---
+
 ### Data Display
 
 ---
@@ -1259,12 +1506,13 @@ User avatar with image, initials fallback, and online status.
 
 #### `TablePagination`
 
-Table page navigation. Handles ellipsis, edge pages, and optional page-size controls.
+Table page navigation. Handles ellipsis, edge pages, optional page-size controls, and two navigation variants: `indexed` (Prev, page indexes like `1 2 3 ... 10`, Next) and `simple` (Prev / Next only).
 
 ```tsx
 <TablePagination
   page={currentPage}
   totalPages={totalPages}
+  variant="indexed"
   pageSize={pageSize}
   onPageChange={setCurrentPage}
   onPageSizeChange={setPageSize}
@@ -1276,8 +1524,14 @@ Table page navigation. Handles ellipsis, edge pages, and optional page-size cont
 | `page` | `number` | **required** |
 | `totalPages` | `number` | **required** |
 | `onPageChange` | `(page: number) => void` | **required** |
+| `variant` | `"indexed" \| "simple"` | `"indexed"` |
 | `pageSize` | `number` | — |
 | `onPageSizeChange` | `(pageSize: number) => void` | — |
+| `itemsPerPageLabel` | `string` | `"Items per page:"` |
+
+Angular: `items-per-page-label` attribute.
+
+> Pass `pagination={{ page, totalPages, variant: "simple", onPageChange }}` to `DataTable` when the built-in footer should show only Prev and Next.
 
 ---
 
@@ -1320,6 +1574,11 @@ Generic data table with sorting, loading skeleton, row actions, selection, pagin
 | `density` | `"compact" \| "default" \| "comfortable"` | `"default"` |
 | `emptyTitle` | `ReactNode` | `"No records found"` |
 | `emptyDescription` | `ReactNode` | — |
+| `defaultSorting` | `{ columnId: string; direction: "asc" \| "desc" } \| null` | `null` |
+| `maxHeight` | `number \| string` | — |
+| `stickyHeader` | `boolean` | `true` |
+
+Angular: pass `sorting` as JSON attribute `[sorting]='{"columnId":"name","direction":"asc"}'`; `default-sorting`, `max-height`, `sticky-header` attributes are fully supported. `show-all-label` and `(show-all)` event are supported on `bfrs-table-column-visibility`.
 
 `DataTableColumn<T>`:
 ```ts
@@ -1337,6 +1596,33 @@ 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.
 
+Use `TableSaveView` with `TableColumnVisibility` when the user changes columns or filters and needs to save the draft as a named view. It opens the "Save this view" modal, collects the view name, summarizes settings like hidden columns, and calls `onSave({ name, visibleColumnIds, hiddenColumnCount, filtersCount, appliedSettingLabels })`; persistence remains app-owned.
+
+```tsx
+<TableToolbar
+  title="Orders"
+  actions={
+    <div className="bfrs-flex bfrs-items-center bfrs-gap-2">
+      {dirty && (
+        <TableSaveView
+          columns={visibilityColumns}
+          visibleColumnIds={visibleColumnIds}
+          onSave={({ visibleColumnIds: nextSavedIds }) => setSavedColumnIds(nextSavedIds)}
+        />
+      )}
+      <TableColumnVisibility
+        columns={visibilityColumns}
+        visibleColumnIds={visibleColumnIds}
+        onVisibleColumnIdsChange={setVisibleColumnIds}
+        onReset={() => setVisibleColumnIds(savedColumnIds)}
+      />
+    </div>
+  }
+/>
+```
+
+Angular custom-element consumers can use `<bfrs-table-save-view>` and listen for `(save-view)` with the same payload.
+
 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
@@ -1429,6 +1715,68 @@ not rendered. Listed custom-element events are re-emitted as `cell-event` with
 
 ---
 
+#### `TableColumnVisibility`
+
+Column show/hide control used inside `TableToolbar`. Emits `visible-column-ids-change` and exposes a "Show all" reset button.
+
+```tsx
+<TableColumnVisibility
+  columns={visibilityColumns}
+  visibleColumnIds={visibleColumnIds}
+  onVisibleColumnIdsChange={setVisibleColumnIds}
+  onReset={() => setVisibleColumnIds(savedColumnIds)}
+  showAllLabel="Show all columns"
+/>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `columns` | `{ id: string; label: string }[]` | **required** |
+| `visibleColumnIds` | `string[]` | — |
+| `onVisibleColumnIdsChange` | `(ids: string[]) => void` | — |
+| `onReset` | `() => void` | — |
+| `onShowAll` | `() => void` | — |
+| `showAllLabel` | `string` | `"Show all"` |
+| `resetLabel` | `string` | `"Reset"` |
+| `label` | `ReactNode` | `"Columns"` |
+
+Angular: `show-all-label` attribute; `(show-all)` event.
+
+---
+
+#### `MetricCard`
+
+KPI display card with trend indicator, optional subtitle, description, icon slot, and action slot.
+
+```tsx
+<MetricCard
+  title="Total shipments"
+  value="12,480"
+  trendValue="+8.2%"
+  trendDirection="up"
+  subtitle="vs last month"
+  icon={<Icon icon={Package} />}
+  action={<Button size="sm" variant="ghost">View all</Button>}
+/>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `title` | `ReactNode` | `"Metric"` |
+| `value` | `ReactNode` | — |
+| `subtitle` | `ReactNode` | — |
+| `description` | `ReactNode` | — |
+| `trendValue` | `ReactNode` | — |
+| `trendDirection` | `"up" \| "down" \| "neutral"` | `"neutral"` |
+| `icon` | `ReactNode` | — |
+| `action` | `ReactNode` | — |
+| `loading` | `boolean` | `false` |
+| `compact` | `boolean` | `false` |
+
+Angular: `icon="package"` for a named Phosphor icon; use `<span slot="action">…</span>` for the action slot.
+
+---
+
 ### Navigation
 
 ---
@@ -1742,7 +2090,7 @@ Grouped expandable sections. Use `type="single"` (default) to keep one panel ope
 
 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.
+Angular: `<bfrs-accordion type="single" value="pickup" [props]="{ items: sections }" (value-change)="openSection = $event.detail.value"></bfrs-accordion>`. The `value` attribute supports controlled mode; use a JSON array string for `type="multiple"`. Pass each item's `content` as a string in custom-element usage.
 
 ---
 
@@ -1888,6 +2236,72 @@ Built-in loading behavior:
 
 ---
 
+#### `HorizontalStepper`
+
+Compact horizontal flow stepper matching the activation-panel layout: optional announcement banner, centered connected steps, and heading/subheading copy below. Uses semantic theme tokens instead of hardcoded screenshot colors. Actions remain parent-owned: React passes `onClose` / `onStepSelect`; custom elements emit `(close)` / `(step-select)`.
+
+For custom elements, add `selectable` when steps should be clickable and emit `(step-select)`.
+
+Variants:
+- `primary` — default theme-colored activation or plan-selection flow.
+- `success` — completed or positive-confirmation flows.
+- `info` — informational setup or guidance flows.
+- `warning` — pending verification or caution flows.
+- `neutral` — low-emphasis wizard progress where status color should stay quiet.
+
+```tsx
+<HorizontalStepper
+  announcement="Great Choice! Early COD Remittance activation in progress.."
+  closeButton
+  onClose={handleClose}
+  currentStep={0}
+  title="Select a Plan"
+  subheading="Get guaranteed remittance from the shipment delivered date."
+  size="sm"
+  variant="primary"
+  steps={[
+    { label: "Select Plan", secondaryText: "Choose payout speed" },
+    { label: "Verify OTP", secondaryText: "Confirm activation" },
+  ]}
+/>
+```
+
+```html
+<bfrs-horizontal-stepper
+  announcement="Great Choice! Early COD Remittance activation in progress.."
+  title="Select a Plan"
+  subheading="Get guaranteed remittance from the shipment delivered date."
+  current-step="0"
+  close-button
+  size="sm"
+  selectable
+  variant="primary"
+  [props]="{ steps: remittanceSteps }"
+  (close)="dismissStepper()"
+  (step-select)="selectStep($event.detail)">
+</bfrs-horizontal-stepper>
+```
+
+| Prop | Type | Default |
+|------|------|---------|
+| `steps` | `{ label: ReactNode; secondaryText?: ReactNode; description?: ReactNode; status?: "done" \| "active" \| "pending" \| "disabled"; disabled?: boolean }[]` | **required** |
+| `currentStep` | `number` | `0` |
+| `title` | `ReactNode` | — |
+| `subheading` | `ReactNode` | — |
+| `description` | `ReactNode` | — alias for `subheading` |
+| `announcement` | `ReactNode` | — |
+| `closeButton` | `boolean` | `false` |
+| `closeLabel` | `string` | `"Close"` |
+| `onClose` | `() => void` | — |
+| `onStepSelect` | `(step, index) => void` | — |
+| `size` | `"sm" \| "md"` | `"sm"` |
+| `surface` | `"card" \| "plain"` | `"card"` |
+| `variant` | `"primary" \| "success" \| "info" \| "warning" \| "neutral"` | `"primary"` |
+
+Each step renders `label` as the primary text and optional `secondaryText` below it. `description` is kept as a backwards-compatible alias for `secondaryText`.
+
+---
+
 #### `StepProgressCard`
 
 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.
@@ -1954,7 +2368,7 @@ Step-by-step progress indicator. Calculates `done` / `active` / `pending` state
       loading={isLoading}
       sorting={sorting}
       onSortingChange={setSorting}
-      pagination={{ page, totalPages, onPageChange: setPage }}
+      pagination={{ page, totalPages, variant: "indexed", onPageChange: setPage }}
     />
   </Card>
 </Container>
@@ -2002,6 +2416,6 @@ Step-by-step progress indicator. Calculates `done` / `active` / `pending` state
 
 - Do not use raw Tailwind classes for spacing, color, or typography — use `Stack`, `Text`, and component props instead
 - Do not build custom modals, drawers, or dropdowns — use `Modal`, `ConfirmDialog`, `Drawer`, and `ActionMenu`
-- Do not render form labels manually — use `FormField` which wires aria attributes automatically
+- Do not render form labels or add label margins manually — use `FormField`, which keeps labels on their own row, applies the standard gap, and wires aria attributes automatically
 - Do not use `<h1>`–`<h6>` or `<p>` directly — use `<Text variant="h1">` etc.
 - Do not add `loading` spinners manually — all interactive components accept a `loading` prop