@bfrs/agentic-components 0.2.6 → 0.2.7

package/BFRS_AGENTIC_COMPONENTS.md

@@ -22,13 +22,23 @@ Import the stylesheet once at your app entry point:
 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.
+
 Import components by name:
 
 ```tsx
-import { Button, Input, Slider, ColorPicker, ColorSwatchGroup, RevealAndCopy, Modal, DataTable, DateRangePicker, ToastProvider, useToast } from "@bfrs/agentic-components";
+import { BfrsProvider, Button, Input, Slider, ColorPicker, ColorSwatchGroup, 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.
+
+```tsx
+<BfrsProvider colorScheme="light">
+  <App />
+</BfrsProvider>
 ```
 
-For whole-app theme overrides, import the framework-neutral theme helper:
+For scoped theme overrides, import the framework-neutral theme helper:
 
 ```ts
 import { applyAgenticTheme, createAgenticThemeVariables } from "@bfrs/agentic-components/theme";
@@ -40,7 +50,7 @@ applyAgenticTheme({
 });
 ```
 
-Plain CSS variable overrides are also supported. Direct `--color-*` overrides should use HSL channels because component styles call them through `hsl(var(--color-...))`.
+`applyAgenticTheme()` writes to an explicit target when provided, otherwise to the first mounted BFRS scope (`.bfrs`, `[data-bfrs-root]`, or `[data-bfrs-mount]`). It does not write to the host document root. Plain CSS variable overrides are also supported. Direct `--bfrs-color-*` overrides should use HSL channels because component styles call them through `hsl(var(--bfrs-color-...))`.
 
 **Peer dependencies required:** `react >= 18.2.0`, `react-dom >= 18.2.0`
 
@@ -126,9 +136,9 @@ For validated forms, keep client validation, API validation, and submit side eff
 - **Tones** are always `"neutral" | "primary" | "brand" | "success" | "warning" | "danger" | "info"`
 - **Variants** control visual style (filled vs. outline vs. ghost, etc.)
 - All interactive components forward refs and spread native HTML props
-- Styling uses **Tailwind CSS** + **CVA** — do not add raw Tailwind classes on top of variant-controlled elements
-- Use the `cn()` utility from the library for conditional class merging
-- **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 (`dcl-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.
+- 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.
 
 ```tsx
 import { cn } from "@bfrs/agentic-components";
@@ -147,7 +157,7 @@ import { cn } from "@bfrs/agentic-components";
 Generic polymorphic wrapper. Use when you need a semantic HTML element with class merging.
 
 ```tsx
-<Box as="section" className="my-4">…</Box>
+<Box as="section" className="bfrs-my-4">…</Box>
 ```
 
 | Prop | Type | Default |

package/README.md

@@ -24,22 +24,28 @@ Use BFRS_AGENTIC_COMPONENTS.md for knowledge regarding the component library.
 
 ```tsx
 import "@bfrs/agentic-components/styles";
-import { Button, Card, Checkbox, Input, Text } from "@bfrs/agentic-components";
+import { BfrsProvider, 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>
+    <BfrsProvider>
+      <Card>
+        <Text variant="title">Create shipment</Text>
+        <Input placeholder="Pickup pincode" />
+        <Checkbox label="Save this pickup address" defaultChecked />
+        <Button onClick={() => undefined}>Continue</Button>
+      </Card>
+    </BfrsProvider>
   );
 }
 ```
 
+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.
+
 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.
+
 Size-aware controls support `sm`, `md`, and `lg`. `sm` is the compact dashboard size for dense controls and filters.
 
 ## Angular Usage
@@ -116,7 +122,7 @@ Registered tags include `bfrs-box`, `bfrs-container`, `bfrs-paper`, `bfrs-stack`
 
 ## Theme Overrides
 
-The package exposes a framework-neutral theme helper for app-wide token overrides. Use it from React, Angular, or plain TypeScript without importing the React component entry:
+The package exposes a framework-neutral theme helper for scoped token overrides. Use it from React, Angular, or plain TypeScript without importing the React component entry:
 
 ```ts
 import { applyAgenticTheme } from "@bfrs/agentic-components/theme";
@@ -138,16 +144,18 @@ applyAgenticTheme({
 });
 ```
 
-The helper accepts hex, rgb, hsl, or raw HSL channel values for semantic color tokens. Plain CSS variable overrides also work:
+`applyAgenticTheme()` writes to an explicit target when provided, otherwise to the first mounted BFRS scope (`.bfrs`, `[data-bfrs-root]`, or `[data-bfrs-mount]`). It never writes to the host document root. The helper accepts hex, rgb, hsl, or raw HSL channel values for semantic color tokens. Plain CSS variable overrides also work on a BFRS scope:
 
 ```css
-:root {
-  --color-primary: 251 51% 52%;
-  --radius-control: 14px;
-  --shadow-card: 0 12px 32px rgb(91 69 194 / 0.16);
+.bfrs {
+  --bfrs-color-primary: 251 51% 52%;
+  --bfrs-radius-control: 14px;
+  --bfrs-shadow-card: 0 12px 32px rgb(91 69 194 / 0.16);
 }
 ```
 
+`BfrsProvider` also accepts `theme` and `colorScheme="light" | "dark"` props. Inline `style` values override generated theme variables when both are provided.
+
 ### Validated Forms
 
 Keep form validation and API checks in the app. Render field errors below inputs, then show success or failure through the toast API.

package/dist/components/ui/data-display/KpiCard/KpiCard.d.ts

@@ -0,0 +1,16 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export type KpiCardAccent = "primary" | "success" | "warning" | "danger" | "info" | "none";
+export type KpiCardProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    label: ReactNode;
+    value: ReactNode;
+    accent?: KpiCardAccent;
+    labelClassName?: string;
+    valueClassName?: string;
+};
+export declare const KpiCard: import('react').ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    label: ReactNode;
+    value: ReactNode;
+    accent?: KpiCardAccent;
+    labelClassName?: string;
+    valueClassName?: string;
+} & import('react').RefAttributes<HTMLDivElement>>;

package/dist/components/ui/data-display/KpiCard/index.d.ts

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

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

@@ -1,7 +1,7 @@
 import { HTMLAttributes, ReactNode } from 'react';
 import { VariantProps } from 'class-variance-authority';
 declare const alertVariants: (props?: ({
-    tone?: "danger" | "success" | "warning" | "info" | null | undefined;
+    tone?: "success" | "warning" | "danger" | "info" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type AlertProps = HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants> & {
     title?: ReactNode;
@@ -9,7 +9,7 @@ export type AlertProps = HTMLAttributes<HTMLDivElement> & VariantProps<typeof al
     icon?: ReactNode;
 };
 export declare const Alert: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
-    tone?: "danger" | "success" | "warning" | "info" | null | undefined;
+    tone?: "success" | "warning" | "danger" | "info" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string> & {
     title?: ReactNode;
     action?: ReactNode;

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

@@ -0,0 +1,27 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export type ProgressBarTone = "primary" | "success" | "warning" | "danger" | "info";
+export type ProgressBarSize = "sm" | "md" | "lg";
+export type ProgressBarProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    value?: number;
+    max?: number;
+    indeterminate?: boolean;
+    tone?: ProgressBarTone;
+    size?: ProgressBarSize;
+    label?: ReactNode;
+    showValue?: boolean;
+    formatValue?: (percent: number, value: number, max: number) => ReactNode;
+    trackClassName?: string;
+    barClassName?: string;
+};
+export declare const ProgressBar: import('react').ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    value?: number;
+    max?: number;
+    indeterminate?: boolean;
+    tone?: ProgressBarTone;
+    size?: ProgressBarSize;
+    label?: ReactNode;
+    showValue?: boolean;
+    formatValue?: (percent: number, value: number, max: number) => ReactNode;
+    trackClassName?: string;
+    barClassName?: string;
+} & import('react').RefAttributes<HTMLDivElement>>;

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

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

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

@@ -1,13 +1,13 @@
 import { HTMLAttributes } from 'react';
 import { VariantProps } from 'class-variance-authority';
 declare const skeletonVariants: (props?: ({
-    variant?: "text" | "block" | "card" | "avatar" | null | undefined;
+    variant?: "text" | "card" | "block" | "avatar" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type SkeletonProps = HTMLAttributes<HTMLDivElement> & VariantProps<typeof skeletonVariants> & {
     animated?: boolean;
 };
 export declare const Skeleton: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
-    variant?: "text" | "block" | "card" | "avatar" | null | undefined;
+    variant?: "text" | "card" | "block" | "avatar" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string> & {
     animated?: boolean;
 } & import('react').RefAttributes<HTMLDivElement>>;

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

@@ -13,7 +13,7 @@ export type ColorPickerProps = Omit<InputHTMLAttributes<HTMLInputElement>, "defa
     inputClassName?: string;
     swatchClassName?: string;
 };
-export declare const ColorPicker: import('react').ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "value" | "size" | "type"> & {
+export declare const ColorPicker: import('react').ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange" | "type"> & {
     value: string;
     onValueChange: (value: string) => void;
     label?: ReactNode;

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

@@ -17,7 +17,7 @@ export type SliderProps = Omit<InputHTMLAttributes<HTMLInputElement>, "defaultVa
     valueClassName?: string;
     inputClassName?: string;
 };
-export declare const Slider: import('react').ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "value" | "size" | "type" | "step" | "max" | "min"> & {
+export declare const Slider: import('react').ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue" | "onChange" | "type" | "step" | "max" | "min"> & {
     value: number;
     onValueChange: (value: number) => void;
     min?: number;

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

@@ -1,3 +1,5 @@
+export { BfrsProvider } from './providers/BfrsProvider';
+export type { BfrsColorScheme, BfrsProviderProps } from './providers/BfrsProvider';
 export * from './primitives/Box';
 export * from './primitives/Container';
 export * from './primitives/Paper';
@@ -25,6 +27,7 @@ export * from './feedback/Badge';
 export * from './feedback/Alert';
 export * from './feedback/Skeleton';
 export * from './feedback/Spinner';
+export * from './feedback/ProgressBar';
 export * from './feedback/EmptyState';
 export * from '../feedback/ErrorState';
 export * from '../feedback/LoadingState';
@@ -39,6 +42,7 @@ export * from '../overlays/ConfirmDialog';
 export * from './data-display/Avatar';
 export * from '../data-display/MetricCard';
 export * from '../data-display/DataTable';
+export * from './data-display/KpiCard';
 export * from './navigation/Tabs';
 export * from './navigation/Breadcrumbs';
 export * from '../navigation/ActionMenu';

package/dist/components/ui/primitives/Paper/Paper.d.ts

@@ -1,12 +1,12 @@
 import { HTMLAttributes } from 'react';
 import { VariantProps } from 'class-variance-authority';
 declare const paperVariants: (props?: ({
-    variant?: "default" | "muted" | "elevated" | "outlined" | "glass" | null | undefined;
-    padding?: "none" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "default" | "elevated" | "muted" | "outlined" | "glass" | null | undefined;
+    padding?: "sm" | "md" | "lg" | "none" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type PaperProps = HTMLAttributes<HTMLDivElement> & VariantProps<typeof paperVariants>;
 export declare const Paper: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & VariantProps<(props?: ({
-    variant?: "default" | "muted" | "elevated" | "outlined" | "glass" | null | undefined;
-    padding?: "none" | "sm" | "md" | "lg" | null | undefined;
+    variant?: "default" | "elevated" | "muted" | "outlined" | "glass" | null | undefined;
+    padding?: "sm" | "md" | "lg" | "none" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string> & import('react').RefAttributes<HTMLDivElement>>;
 export {};

package/dist/components/ui/primitives/Text/Text.d.ts

@@ -1,15 +1,15 @@
 import { ElementType, HTMLAttributes } from 'react';
 import { VariantProps } from 'class-variance-authority';
 declare const textVariants: (props?: ({
-    variant?: "body" | "caption" | "h1" | "h2" | "h3" | "label" | "title" | "display" | "body-sm" | null | undefined;
-    tone?: "disabled" | "muted" | "primary" | "secondary" | "danger" | "success" | "accent" | null | undefined;
+    variant?: "caption" | "display" | "body" | "title" | "h1" | "h2" | "h3" | "label" | "body-sm" | null | undefined;
+    tone?: "accent" | "primary" | "success" | "danger" | "disabled" | "muted" | "secondary" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export type TextProps = HTMLAttributes<HTMLElement> & VariantProps<typeof textVariants> & {
     as?: ElementType;
 };
 export declare const Text: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & VariantProps<(props?: ({
-    variant?: "body" | "caption" | "h1" | "h2" | "h3" | "label" | "title" | "display" | "body-sm" | null | undefined;
-    tone?: "disabled" | "muted" | "primary" | "secondary" | "danger" | "success" | "accent" | null | undefined;
+    variant?: "caption" | "display" | "body" | "title" | "h1" | "h2" | "h3" | "label" | "body-sm" | null | undefined;
+    tone?: "accent" | "primary" | "success" | "danger" | "disabled" | "muted" | "secondary" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string> & {
     as?: ElementType;
 } & import('react').RefAttributes<HTMLElement>>;

package/dist/components/ui/providers/BfrsProvider/BfrsProvider.d.ts

@@ -0,0 +1,19 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { AgenticThemeOverrides } from '../../../../theme';
+export type BfrsColorScheme = "light" | "dark";
+export type BfrsProviderProps = HTMLAttributes<HTMLDivElement> & {
+    theme?: AgenticThemeOverrides;
+    colorScheme?: BfrsColorScheme;
+};
+export declare const BfrsProvider: import('react').ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    theme?: AgenticThemeOverrides;
+    colorScheme?: BfrsColorScheme;
+} & import('react').RefAttributes<HTMLDivElement>>;
+export declare function BfrsStyleScope({ children, root, colorScheme }: {
+    children: ReactNode;
+    root: HTMLElement | null;
+    colorScheme?: BfrsColorScheme;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function BfrsPortalScope({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export { BfrsPortalScope, BfrsProvider, BfrsStyleScope } from './BfrsProvider';
+export type { BfrsColorScheme, BfrsProviderProps } from './BfrsProvider';

package/dist/custom-elements.d.ts

@@ -1,4 +1,5 @@
 import { ColorSwatchValue } from './components/ui/forms/ColorSwatchGroup';
+import { BfrsColorScheme } from './components/ui/providers/BfrsProvider';
 type UnknownProps = Record<string, unknown>;
 type CheckedValue = boolean | "indeterminate";
 export type BfrsCustomElementRegistryOptions = {
@@ -22,6 +23,7 @@ declare abstract class ReactCustomElement extends HTMLElement {
     protected update(): void;
     protected textAttribute(name: string, fallback?: string): string | undefined;
     protected classNameAttribute(): string | undefined;
+    protected colorSchemeAttribute(): BfrsColorScheme;
     protected slottedText(fallback?: string): string | undefined;
     protected htmlContent(fallback?: string): unknown;
     protected booleanAttribute(name: string, fallback?: boolean): boolean;
@@ -258,6 +260,18 @@ export declare class BfrsSpinnerElement extends ReactCustomElement {
     static get observedAttributes(): string[];
     protected renderElement(): unknown;
 }
+export declare class BfrsProgressBarElement extends ReactCustomElement {
+    static readonly tagName = "progress-bar";
+    static get observedAttributes(): string[];
+    protected defaultDisplay(): string;
+    protected renderElement(): unknown;
+}
+export declare class BfrsKpiCardElement extends ReactCustomElement {
+    static readonly tagName = "kpi-card";
+    static get observedAttributes(): string[];
+    protected defaultDisplay(): string;
+    protected renderElement(): unknown;
+}
 export declare class BfrsEmptyStateElement extends ReactCustomElement {
     static readonly tagName = "empty-state";
     static get observedAttributes(): string[];
@@ -519,6 +533,7 @@ declare global {
         "bfrs-icon-button": BfrsIconButtonElement;
         "bfrs-inline-error": BfrsInlineErrorElement;
         "bfrs-input": BfrsInputElement;
+        "bfrs-kpi-card": BfrsKpiCardElement;
         "bfrs-label": BfrsLabelElement;
         "bfrs-layout-shell": BfrsLayoutShellElement;
         "bfrs-loading-state": BfrsLoadingStateElement;
@@ -527,6 +542,7 @@ declare global {
         "bfrs-page-header": BfrsPageHeaderElement;
         "bfrs-paper": BfrsPaperElement;
         "bfrs-popover": BfrsPopoverElement;
+        "bfrs-progress-bar": BfrsProgressBarElement;
         "bfrs-radio": BfrsRadioElement;
         "bfrs-reveal-and-copy": BfrsRevealAndCopyElement;
         "bfrs-searchable-select": BfrsSearchableSelectElement;