# Agentic Components

Production-grade component library for Shiprocket agentic interfaces. React consumers use the native React exports; Angular consumers use the packaged Custom Elements bridge.

- Repository: https://github.com/bfrs/agentic-components
- Showcase: https://agentic-components.vercel.app/
- Package: `@bfrs/agentic-components`

## Install

Install from the public npm registry:

```bash
npm install @bfrs/agentic-components
```

During install, the package writes `BFRS_AGENTIC_COMPONENTS.md` into the consuming project. It also ensures `AGENTS.md` and `CLAUDE.md` reference that file, creating either file when missing. Existing agent files are preserved and only receive the reference line:

```md
Use BFRS_AGENTIC_COMPONENTS.md for knowledge regarding the component library.
```

## React Usage

```tsx
import "@bfrs/agentic-components/styles";
import { Button, Card, Checkbox, Input, Text } from "@bfrs/agentic-components";

export function Example() {
  return (
    <Card>
      <Text variant="title">Create shipment</Text>
      <Input placeholder="Pickup pincode" />
      <Checkbox label="Save this pickup address" defaultChecked />
      <Button onClick={() => undefined}>Continue</Button>
    </Card>
  );
}
```

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`.

Size-aware controls support `sm`, `md`, and `lg`. `sm` is the compact dashboard size for dense controls and filters.

## Angular Usage

Angular apps should import the custom element registry once and include the shared stylesheet globally:

```ts
// main.ts
import "@bfrs/agentic-components/custom-elements";
```

```scss
/* styles.scss */
@import "@bfrs/agentic-components/styles";
```

Add `CUSTOM_ELEMENTS_SCHEMA` to the module or standalone component that renders the tags:

```ts
import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";

@Component({
  selector: "app-example",
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <bfrs-input label="Pickup pincode" (value-change)="pickup = $event.detail.value"></bfrs-input>
    <bfrs-button variant="primary" (click)="continue()">Continue</bfrs-button>
  `
})
export class ExampleComponent {
  pickup = "";
  continue() {}
}
```

The custom-elements entrypoint registers Angular-friendly tags for the documented component surface, including layout, forms, feedback, overlays, filters, data display, navigation, and agentic pattern components.

Use simple attributes for primitive values and `[props]` for structured values or callback-capable advanced props:

```html
<bfrs-select
  placeholder="Channel"
  [props]="{ options: channelOptions, value: channel }"
  (value-change)="channel = $event.detail.value">
</bfrs-select>

<bfrs-data-table
  [props]="{ data: orders, columns: orderColumns, selection: true }"
  (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-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`, and `bfrs-step-progress-card`.

### DateRangePicker

Use `DateRangePicker` for preset and custom date-range filters. Keep API date formatting in the consuming app.

```tsx
import { DateRangePicker, presetToRange, type DateRangeValue } from "@bfrs/agentic-components";

const [range, setRange] = useState<DateRangeValue>({
  preset: "Last 30 days",
  ...presetToRange("Last 30 days")
});

<DateRangePicker value={range} onChange={setRange} maxRangeDays={365} />;
```

### ToastProvider

Wrap the app once and call toast helpers from app event handlers.

```tsx
import { Button, ToastProvider, useToast } from "@bfrs/agentic-components";

function SaveButton() {
  const { success, danger } = useToast();

  return <Button onClick={() => success("Changes saved")}>Save</Button>;
}

<ToastProvider>
  <SaveButton />
</ToastProvider>;
```

### 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.

```tsx
import { Checkbox } from "@bfrs/agentic-components";

<Checkbox
  label="Accept terms"
  description="Use checkboxes when each option can be selected independently."
  checked={accepted}
  onCheckedChange={setAccepted}
/>

<Checkbox label="Partially selected" checked="indeterminate" />
```

## Development

```bash
npm run typecheck
npm run lint
npm run build:lib
npm run build:demo
```

`npm run build:lib` outputs the package to `dist`.

`npm run build:demo` outputs the showcase app to `dist-demo`.

## Publishing

Package publishing is configured for npmjs public packages. Publish only through the controlled release flow:

```bash
npm run changeset
npm run version-packages
git tag v0.1.0
git push origin main --tags
```

The `Publish Package` GitHub Action publishes to npmjs on version tags, published GitHub releases, or manual workflow dispatch. Configure the repository secret `NPM_TOKEN` with publish access.

## Showcase Deployment

The public documentation is hosted at https://agentic-components.vercel.app/.

The showcase build target is `dist-demo`:

```bash
npm run build:demo
```
