@bfrs/agentic-components 0.3.8 → 0.4.0

package/BFRS_AGENTIC_COMPONENTS.md

@@ -51,6 +51,7 @@ import {
   FileDropzone,
   RevealField,
   RevealAndCopy,
+  HorizontalStepper,
   Modal,
   DataTable,
   TableColumnVisibility,
@@ -144,7 +145,7 @@ Registered tags cover the documented component surface, including
 `bfrs-table-row-actions`, `bfrs-table-bulk-actions`, and
 `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
@@ -185,7 +186,7 @@ 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, 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`.
 
@@ -1040,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`
@@ -2233,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.
@@ -2343,6 +2412,121 @@ Step-by-step progress indicator. Calculates `done` / `active` / `pending` state
 
 ---
 
+## Table / Thead / Tbody / Tfoot / Tr / Th / Td
+
+Primitive table components with DataTable-matching styles, density support, and row hover effects. Use these for custom layouts where `DataTable` is too prescriptive.
+
+### React
+
+```tsx
+import { Table, Thead, Tbody, Tfoot, Tr, Th, Td } from "@bfrs/agentic-components";
+
+<Table density="compact" sticky aria-label="Orders">
+  <Thead sticky>
+    <Tr>
+      <Th>Order</Th>
+      <Th align="right">Amount</Th>
+      <Th>Status</Th>
+    </Tr>
+  </Thead>
+  <Tbody>
+    {orders.map((order) => (
+      <Tr key={order.id} onClick={() => navigate(`/orders/${order.id}`)}>
+        <Td>{order.id}</Td>
+        <Td align="right">₹{order.amount}</Td>
+        <Td>{order.status}</Td>
+      </Tr>
+    ))}
+  </Tbody>
+  <Tfoot>
+    <Tr>
+      <Th colSpan={2}>Total</Th>
+      <Th align="right">₹{total}</Th>
+    </Tr>
+  </Tfoot>
+</Table>
+```
+
+#### Table props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `density` | `"compact" \| "default" \| "comfortable"` | `"default"` | Cell padding density — propagates to Th/Td via React context |
+| `maxHeight` | `string \| number` | — | Enables vertical scrolling at this height |
+| `minWidth` | `string \| number` | — | Minimum table width (useful for fixed-layout tables) |
+| `className` | `string` | — | Applied to the outer border wrapper |
+| `tableClassName` | `string` | — | Applied to the `<table>` element |
+| `aria-label` | `string` | `"Table"` | Accessibility label |
+| `children` | `ReactNode` | — | `Thead`, `Tbody`, `Tfoot` elements |
+
+#### Thead props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sticky` | `boolean` | `false` | Sticks the header at the top of the scroll container |
+| `className` | `string` | — | Extra class on `<thead>` |
+
+#### Tr props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onClick` | `() => void` | — | Row click handler; adds `cursor-pointer` automatically |
+| `className` | `string` | — | Extra class on `<tr>` |
+
+#### Th props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `align` | `"left" \| "center" \| "right"` | `"left"` | Text alignment |
+| `colSpan` | `number` | — | HTML colspan |
+| `className` | `string` | — | Extra class on `<th>` |
+
+#### Td props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `align` | `"left" \| "center" \| "right"` | `"left"` | Text alignment |
+| `colSpan` | `number` | — | HTML colspan |
+| `className` | `string` | — | Extra class on `<td>` |
+
+### Angular (custom elements)
+
+Custom elements: `bfrs-table`, `bfrs-thead`, `bfrs-tbody`, `bfrs-tfoot`, `bfrs-tr`, `bfrs-th`, `bfrs-td`.
+
+`bfrs-table` propagates `density` to all descendant `bfrs-th` and `bfrs-td` elements automatically. Row hover transitions the background color of all `bfrs-td` children via JavaScript events.
+
+```html
+<bfrs-table density="compact" max-height="400px" aria-label="Orders">
+  <bfrs-thead sticky>
+    <bfrs-tr>
+      <bfrs-th>Order</bfrs-th>
+      <bfrs-th align="right">Amount</bfrs-th>
+      <bfrs-th>Status</bfrs-th>
+    </bfrs-tr>
+  </bfrs-thead>
+  <bfrs-tbody>
+    <bfrs-tr *ngFor="let order of orders" (click)="navigate(order.id)">
+      <bfrs-td>{{ order.id }}</bfrs-td>
+      <bfrs-td align="right">₹{{ order.amount }}</bfrs-td>
+      <bfrs-td>{{ order.status }}</bfrs-td>
+    </bfrs-tr>
+  </bfrs-tbody>
+</bfrs-table>
+```
+
+| Attribute | Element | Description |
+|-----------|---------|-------------|
+| `density` | `bfrs-table` | `"compact"`, `"default"`, or `"comfortable"` — propagated to all th/td |
+| `max-height` | `bfrs-table` | CSS max-height for scroll container |
+| `min-width` | `bfrs-table` | CSS min-width on the table |
+| `aria-label` | `bfrs-table` | Accessibility label |
+| `sticky` | `bfrs-thead` | Boolean — sticks header at scroll top |
+| `on-click` | `bfrs-tr` | Emits `click` event; adds `cursor-pointer` |
+| `align` | `bfrs-th`, `bfrs-td` | `"left"`, `"center"`, or `"right"` |
+| `density` | `bfrs-th`, `bfrs-td` | Override density per cell (set explicitly; overrides table propagation) |
+
+---
+
 ## What NOT to do
 
 - Do not use raw Tailwind classes for spacing, color, or typography — use `Stack`, `Text`, and component props instead

package/README.md

@@ -262,7 +262,30 @@ The standalone helpers are available as `bfrs-table-toolbar`,
 `bfrs-table-row-actions`, `bfrs-table-bulk-actions`, and
 `bfrs-table-column-visibility`.
 
-Registered tags include `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`, `bfrs-grid`, `bfrs-text`, `bfrs-icon`, `bfrs-button`, `bfrs-button-group`, `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-toast-provider`, `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-table-toolbar`, `bfrs-table-empty-state`, `bfrs-table-error-state`, `bfrs-table-skeleton`, `bfrs-table-row-actions`, `bfrs-table-bulk-actions`, `bfrs-table-column-visibility`, `bfrs-data-table`, `bfrs-tabs`, `bfrs-tabs-list`, `bfrs-tabs-trigger`, `bfrs-tabs-content`, `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`.
+Registered tags include `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`, `bfrs-grid`, `bfrs-text`, `bfrs-icon`, `bfrs-button`, `bfrs-button-group`, `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-toast-provider`, `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-table-toolbar`, `bfrs-table-empty-state`, `bfrs-table-error-state`, `bfrs-table-skeleton`, `bfrs-table-row-actions`, `bfrs-table-bulk-actions`, `bfrs-table-column-visibility`, `bfrs-data-table`, `bfrs-tabs`, `bfrs-tabs-list`, `bfrs-tabs-trigger`, `bfrs-tabs-content`, `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`, `bfrs-horizontal-stepper`, and `bfrs-step-progress-card`.
+
+`HorizontalStepper` provides the compact horizontal flow layout with an optional announcement banner and parent-owned `onClose` / `onStepSelect` behavior:
+
+```tsx
+import { HorizontalStepper } from "@bfrs/agentic-components";
+
+<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" }
+  ]}
+/>
+```
+
+Use `variant="primary" | "success" | "info" | "warning" | "neutral"` for semantic color treatment, and `size="sm" | "md"` for compact or roomier layouts.
 
 ## Theme Overrides
 
@@ -357,10 +380,10 @@ function SaveButton() {
 
 ### Checkbox
 
-Use `Checkbox` for independent true/false decisions or multi-select choices. It renders as a square checklist control, while `Radio` renders circular options for single-choice groups.
+Use `Checkbox` for independent true/false decisions or multi-select choices. It renders as a square checklist control, while `Radio` renders circular options for single-choice groups. Both support primary text plus secondary description text.
 
 ```tsx
-import { Checkbox } from "@bfrs/agentic-components";
+import { Checkbox, Radio } from "@bfrs/agentic-components";
 
 <Checkbox
   label="Accept terms"
@@ -370,6 +393,14 @@ import { Checkbox } from "@bfrs/agentic-components";
 />
 
 <Checkbox label="Partially selected" checked="indeterminate" />
+
+<Radio
+  options={[
+    { value: "registered", label: "Registered business", description: "Company GST and business KYC are available." },
+    { value: "individual", label: "Individual seller", description: "Use personal details for seller verification." }
+  ]}
+  defaultValue="registered"
+/>
 ```
 
 ## Development

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

@@ -1,7 +1,9 @@
+import { ReactNode } from 'react';
 import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
 export type RadioOption = {
     value: string;
-    label: string;
+    label: ReactNode;
+    description?: ReactNode;
     disabled?: boolean;
 };
 export type RadioProps = RadioGroupPrimitive.RadioGroupProps & {

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

@@ -66,6 +66,7 @@ export * from './patterns/ChatBubble';
 export * from './patterns/ChatComposer';
 export * from './patterns/FullPageLoader';
 export * from './patterns/BusinessInfoDisplayCard';
+export * from './patterns/HorizontalStepper';
 export * from './patterns/StepProgressCard';
 export * from './patterns/RevealAndCopy';
 export * from './patterns/Collapsible';

package/dist/components/ui/patterns/HorizontalStepper/HorizontalStepper.d.ts

@@ -0,0 +1,45 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export type HorizontalStepperState = "done" | "active" | "pending" | "disabled";
+export type HorizontalStepperVariant = "primary" | "success" | "info" | "warning" | "neutral";
+export type HorizontalStepperSize = "sm" | "md";
+export type HorizontalStepperStep = {
+    id?: string;
+    label: ReactNode;
+    secondaryText?: ReactNode;
+    /** Backwards-compatible alias for secondaryText. Prefer secondaryText for new code. */
+    description?: ReactNode;
+    status?: HorizontalStepperState;
+    disabled?: boolean;
+};
+export type HorizontalStepperProps = HTMLAttributes<HTMLElement> & {
+    steps: HorizontalStepperStep[];
+    currentStep?: number;
+    title?: ReactNode;
+    subheading?: ReactNode;
+    /** Backwards-compatible alias for subheading. Prefer subheading for new code. */
+    description?: ReactNode;
+    announcement?: ReactNode;
+    closeButton?: boolean;
+    closeLabel?: string;
+    onClose?: () => void;
+    onStepSelect?: (step: HorizontalStepperStep, index: number) => void;
+    size?: HorizontalStepperSize;
+    surface?: "card" | "plain";
+    variant?: HorizontalStepperVariant;
+};
+export declare const HorizontalStepper: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & {
+    steps: HorizontalStepperStep[];
+    currentStep?: number;
+    title?: ReactNode;
+    subheading?: ReactNode;
+    /** Backwards-compatible alias for subheading. Prefer subheading for new code. */
+    description?: ReactNode;
+    announcement?: ReactNode;
+    closeButton?: boolean;
+    closeLabel?: string;
+    onClose?: () => void;
+    onStepSelect?: (step: HorizontalStepperStep, index: number) => void;
+    size?: HorizontalStepperSize;
+    surface?: "card" | "plain";
+    variant?: HorizontalStepperVariant;
+} & import('react').RefAttributes<HTMLElement>>;

package/dist/components/ui/patterns/HorizontalStepper/index.d.ts

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

package/dist/custom-elements.d.ts

@@ -787,6 +787,12 @@ export declare class BfrsStepProgressCardElement extends ReactCustomElement {
     protected defaultDisplay(): string;
     protected renderElement(): unknown;
 }
+export declare class BfrsHorizontalStepperElement extends ReactCustomElement {
+    static readonly tagName = "horizontal-stepper";
+    static get observedAttributes(): string[];
+    protected defaultDisplay(): string;
+    protected renderElement(): unknown;
+}
 export declare class BfrsStepProgressCardSkeletonElement extends ReactCustomElement {
     static readonly tagName = "step-progress-card-skeleton";
     static get observedAttributes(): string[];
@@ -884,6 +890,7 @@ declare global {
         "bfrs-skeleton": BfrsSkeletonElement;
         "bfrs-spinner": BfrsSpinnerElement;
         "bfrs-stack": BfrsStackElement;
+        "bfrs-horizontal-stepper": BfrsHorizontalStepperElement;
         "bfrs-step-progress-card": BfrsStepProgressCardElement;
         "bfrs-step-progress-card-skeleton": BfrsStepProgressCardSkeletonElement;
         "bfrs-suggest-input": BfrsSuggestInputElement;