@brijbyte/agentic-ui 0.0.2 → 0.0.4

package/src/radio/parts.tsx

@@ -0,0 +1,43 @@
+/**
+ * Styled primitives for Radio (single item).
+ *
+ * @example
+ * ```tsx
+ * import { RadioGroup } from '@base-ui/react/radio-group';
+ * import { RadioRoot, RadioIndicator } from '@brijbyte/agentic-ui/radio';
+ *
+ * <RadioGroup defaultValue="a">
+ *   <label htmlFor="opt-a">
+ *     <RadioRoot id="opt-a" value="a">
+ *       <RadioIndicator />
+ *     </RadioRoot>
+ *     Option A
+ *   </label>
+ * </RadioGroup>
+ * ```
+ */
+import { forwardRef } from "react";
+import type { ComponentRef, ComponentPropsWithoutRef } from "react";
+import { Radio as BaseRadio } from "@base-ui/react/radio";
+import styles from "./radio.module.css";
+
+type BaseRootProps = ComponentPropsWithoutRef<typeof BaseRadio.Root>;
+type BaseIndicatorProps = ComponentPropsWithoutRef<typeof BaseRadio.Indicator>;
+
+export interface RadioRootProps extends Omit<BaseRootProps, "className"> {
+  className?: string;
+}
+export interface RadioIndicatorProps extends Omit<BaseIndicatorProps, "className"> {
+  className?: string;
+}
+
+export const RadioRoot = forwardRef<ComponentRef<typeof BaseRadio.Root>, RadioRootProps>(function RadioRoot({ className, ...props }, ref) {
+  return <BaseRadio.Root ref={ref} className={`${styles.radio} ${className ?? ""}`} {...props} />;
+});
+
+export const RadioIndicator = forwardRef<ComponentRef<typeof BaseRadio.Indicator>, RadioIndicatorProps>(function RadioIndicator(
+  { className, ...props },
+  ref,
+) {
+  return <BaseRadio.Indicator ref={ref} keepMounted className={`${styles.indicator} ${className ?? ""}`} {...props} />;
+});

package/src/radio/radio.module.css

@@ -0,0 +1,96 @@
+@layer components {
+  /* ── Single radio item layout ───────────────────────────────────── */
+
+  .item {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    cursor: pointer;
+    user-select: none;
+  }
+
+  .item:has([data-disabled]) {
+    cursor: not-allowed;
+  }
+
+  .item:has([data-disabled]) .label {
+    opacity: 0.44;
+  }
+
+  /* ── Radio button (the circle) ──────────────────────────────────── */
+
+  .radio {
+    flex-shrink: 0;
+    width: 16px;
+    height: 16px;
+    border-radius: var(--radius-full);
+    border: var(--border-width-base) solid var(--color-line-strong);
+    background-color: var(--color-surface-1);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition:
+      background-color var(--duration-fast) var(--easing-standard),
+      border-color var(--duration-fast) var(--easing-standard),
+      box-shadow var(--duration-fast) var(--easing-standard);
+    outline: none;
+    position: relative;
+    /* Reset button/span defaults */
+    padding: 0;
+    margin: 0;
+  }
+
+  .radio:focus-visible {
+    box-shadow: var(--shadow-focus);
+    border-color: var(--color-accent);
+  }
+
+  .radio:hover:not([data-disabled]) {
+    border-color: var(--color-accent);
+  }
+
+  .radio[data-checked] {
+    background-color: var(--color-accent);
+    border-color: var(--color-accent);
+  }
+
+  .radio[data-checked]:hover:not([data-disabled]) {
+    background-color: var(--color-accent-hover);
+    border-color: var(--color-accent-hover);
+  }
+
+  .radio[data-disabled] {
+    opacity: 0.44;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* ── Indicator (inner dot) ──────────────────────────────────────── */
+
+  .indicator {
+    width: 6px;
+    height: 6px;
+    border-radius: var(--radius-full);
+    background-color: var(--color-on-accent);
+    transform: scale(0);
+    transition:
+      transform var(--duration-fast) var(--easing-spring),
+      opacity var(--duration-fast) var(--easing-standard);
+    opacity: 0;
+  }
+
+  /* data-checked is on the Root; the Indicator inherits it */
+  .radio[data-checked] .indicator {
+    transform: scale(1);
+    opacity: 1;
+  }
+
+  /* ── Label text ─────────────────────────────────────────────────── */
+
+  .label {
+    font-family: var(--font-mono);
+    font-size: var(--font-size-sm);
+    color: var(--color-primary);
+    line-height: var(--line-height-normal);
+  }
+}

package/src/radio/radio.tsx

@@ -0,0 +1,37 @@
+import { useId } from "react";
+import type { ReactNode } from "react";
+import { Radio as BaseRadio } from "@base-ui/react/radio";
+import styles from "./radio.module.css";
+
+export interface RadioProps {
+  /** Value submitted with the form and matched against the group's value. */
+  value: string;
+  /** Label rendered next to the button. */
+  children?: ReactNode;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** Override the auto-generated element id. */
+  id?: string;
+  className?: string;
+}
+
+/**
+ * A single radio button with an optional label.
+ * Must be placed inside `<RadioGroup>` or a raw base-ui RadioGroup.
+ */
+export function Radio({ value, children, id, className, ...props }: RadioProps) {
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const radioId = id ?? useId();
+
+  return (
+    <label className={`${styles.item} ${className ?? ""}`} htmlFor={radioId}>
+      <BaseRadio.Root id={radioId} value={value} className={styles.radio} {...props}>
+        <BaseRadio.Indicator keepMounted className={styles.indicator} />
+      </BaseRadio.Root>
+      {children && <span className={styles.label}>{children}</span>}
+    </label>
+  );
+}
+
+export { styles as RadioStyles };

package/src/radio-group/index.ts

@@ -0,0 +1,5 @@
+export { RadioGroup, RadioGroupStyles } from "./radio-group";
+export type { RadioGroupProps, RadioOption } from "./radio-group";
+
+export { RadioGroupRoot } from "./parts";
+export type { RadioGroupRootProps } from "./parts";

package/src/radio-group/parts.tsx

@@ -0,0 +1,32 @@
+/**
+ * Styled primitive for RadioGroup.
+ *
+ * @example
+ * ```tsx
+ * import { Radio } from '@brijbyte/agentic-ui/radio';
+ * import { RadioGroupRoot } from '@brijbyte/agentic-ui/radio-group';
+ *
+ * <RadioGroupRoot defaultValue="b" name="plan">
+ *   <Radio value="a">Hobby</Radio>
+ *   <Radio value="b">Pro</Radio>
+ *   <Radio value="c">Enterprise</Radio>
+ * </RadioGroupRoot>
+ * ```
+ */
+import { forwardRef } from "react";
+import type { ComponentRef, ComponentPropsWithoutRef } from "react";
+import { RadioGroup as BaseRadioGroup } from "@base-ui/react/radio-group";
+import styles from "./radio-group.module.css";
+
+type BaseGroupProps = ComponentPropsWithoutRef<typeof BaseRadioGroup>;
+
+export interface RadioGroupRootProps extends Omit<BaseGroupProps, "className"> {
+  className?: string;
+}
+
+export const RadioGroupRoot = forwardRef<ComponentRef<typeof BaseRadioGroup>, RadioGroupRootProps>(function RadioGroupRoot(
+  { className, ...props },
+  ref,
+) {
+  return <BaseRadioGroup ref={ref} className={`${styles.group} ${className ?? ""}`} {...props} />;
+});

package/src/radio-group/radio-group.module.css

@@ -0,0 +1,17 @@
+@layer components {
+  .group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+  }
+
+  .group-label {
+    font-family: var(--font-mono);
+    font-size: var(--font-size-xs);
+    font-weight: var(--font-weight-semibold);
+    color: var(--color-tertiary);
+    text-transform: uppercase;
+    letter-spacing: var(--letter-spacing-wide);
+    margin-bottom: var(--space-1);
+  }
+}

package/src/radio-group/radio-group.tsx

@@ -0,0 +1,63 @@
+import { useId } from "react";
+import type { ReactNode } from "react";
+import { RadioGroup as BaseRadioGroup } from "@base-ui/react/radio-group";
+import { Radio } from "../radio/radio";
+import styles from "./radio-group.module.css";
+
+export interface RadioOption {
+  value: string;
+  label: ReactNode;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+  /** The options to render. Each becomes one `<Radio>` item. */
+  options: RadioOption[];
+  /** Accessible group label rendered above the options. */
+  label?: ReactNode;
+  /** Controlled selected value. */
+  value?: string;
+  /** Initial selected value (uncontrolled). */
+  defaultValue?: string;
+  onValueChange?: (value: string, eventDetails: unknown) => void;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  /** HTML name for form submission. */
+  name?: string;
+  className?: string;
+}
+
+/**
+ * A labelled group of radio buttons. Renders a base-ui RadioGroup with one
+ * `<Radio>` per option.
+ *
+ * For full control over layout or behaviour use `RadioGroupRoot` with
+ * individual `<Radio>` or `<RadioRoot>` elements.
+ */
+export { styles as RadioGroupStyles };
+
+export function RadioGroup({ options, label, className, onValueChange, ...props }: RadioGroupProps) {
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const labelId = useId();
+
+  return (
+    <BaseRadioGroup
+      aria-labelledby={label ? labelId : undefined}
+      className={`${styles.group} ${className ?? ""}`}
+      onValueChange={onValueChange as never}
+      {...props}
+    >
+      {label && (
+        <div id={labelId} className={styles["group-label"]}>
+          {label}
+        </div>
+      )}
+      {options.map((opt) => (
+        <Radio key={opt.value} value={opt.value} {...(opt.disabled !== undefined && { disabled: opt.disabled })}>
+          {opt.label}
+        </Radio>
+      ))}
+    </BaseRadioGroup>
+  );
+}

package/src/select/select.tsx

@@ -14,17 +14,26 @@ export interface SelectGroup {
 }
 
 export interface SelectProps {
+  /** Currently selected value (controlled). */
   value?: string;
+  /** Initially selected value (uncontrolled). */
   defaultValue?: string;
-  /** `eventDetails` is the base-ui event details object. Value may be null when cleared. */
+  /** Called when the selection changes. `eventDetails` is the base-ui event details object. Value may be null when cleared. */
   onValueChange?: (value: string | null, eventDetails: unknown) => void;
+  /** Prevent interaction. */
   disabled?: boolean;
+  /** Mark the field as required for form validation. */
   required?: boolean;
+  /** HTML name attribute for form submission. */
   name?: string;
+  /** Text shown when no value is selected. */
   placeholder?: string;
+  /** Flat list of options (use `groups` for grouped options). */
   options?: SelectOption[];
+  /** Grouped options with optional section labels. */
   groups?: SelectGroup[];
   className?: string;
+  /** Override the auto-generated element id. */
   id?: string;
 }
 
@@ -55,6 +64,10 @@ function SelectItem({ option }: { option: SelectOption }) {
   );
 }
 
+/**
+ * Dropdown select with keyboard navigation, grouping, and search. Pass
+ * `options` for a flat list or `groups` for sections with optional labels.
+ */
 export function Select({ placeholder = "Select…", options, groups, className, onValueChange, value, defaultValue, ...props }: SelectProps) {
   const allOptions = useMemo(() => [...(options ?? []), ...(groups?.flatMap((g) => g.options) ?? [])], [options, groups]);
 

package/src/separator/separator.tsx

@@ -11,6 +11,10 @@ export interface SeparatorProps extends Omit<BaseSeparatorProps, "className"> {
   className?: string;
 }
 
+/**
+ * A semantic divider accessible to screen readers. Renders a horizontal
+ * line by default; switch to vertical for inline layouts.
+ */
 export const Separator = forwardRef<ComponentRef<typeof BaseSeparator>, SeparatorProps>(function Separator(
   { className, orientation = "horizontal", ...props },
   ref,

package/src/shared/PopupArrow.tsx

@@ -0,0 +1,41 @@
+/**
+ * Shared arrow SVG used by Menu and Popover.
+ *
+ * Two paths:
+ *   1. Fill — the arrow body, matches the popup surface colour.
+ *   2. Seam — a thin strip in the border colour at the base, covering
+ *      the popup border at the junction so it doesn't bleed through.
+ *
+ * All CSS classes come from the importing component's own CSS module
+ * so the rules are bundled into the component's CSS file, not a
+ * separate shared chunk that consumers would need to import separately.
+ *
+ * @example
+ * ```tsx
+ * <BaseMenu.Arrow className={styles.arrow}>
+ *   <PopupArrow fillClass={styles["arrow-fill"]!} seamClass={styles["arrow-seam"]!} />
+ * </BaseMenu.Arrow>
+ * ```
+ */
+
+interface PopupArrowProps {
+  fillClass: string;
+  seamClass: string;
+}
+
+export function PopupArrow({ fillClass, seamClass }: PopupArrowProps) {
+  return (
+    <svg width="20" height="10" viewBox="0 0 20 10" fill="none" aria-hidden>
+      {/* Body — surface colour */}
+      <path
+        d="M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
+        className={fillClass}
+      />
+      {/* Seam — border colour strip at the base, covers the popup border at the junction */}
+      <path
+        d="M10.3333 3.34539L5.47654 7.71648C4.55842 8.54279 3.36693 9 2.13172 9H0V8H2.13172C3.11989 8 4.07308 7.63423 4.80758 6.97318L9.66437 2.60207C10.0447 2.25979 10.622 2.2598 11.0023 2.60207L15.8591 6.97318C16.5936 7.63423 17.5468 8 18.5349 8H20V9H18.5349C17.2998 9 16.1083 8.54278 15.1901 7.71648L10.3333 3.34539Z"
+        className={seamClass}
+      />
+    </svg>
+  );
+}

package/src/slider/slider.tsx

@@ -3,17 +3,29 @@ import { Slider as BaseSlider } from "@base-ui/react/slider";
 import styles from "./slider.module.css";
 
 export interface SliderProps {
+  /** Current value (controlled). Pass an array for range sliders. */
   value?: number | number[];
+  /** Initial value (uncontrolled). Pass an array for range sliders. */
   defaultValue?: number | number[];
+  /** Called on every value change while dragging. */
   onValueChange?: (value: number | number[], eventDetails: unknown) => void;
+  /** Called once when the user finishes dragging. */
   onValueCommitted?: (value: number | number[], eventDetails: unknown) => void;
+  /** Minimum allowed value. @default 0 */
   min?: number;
+  /** Maximum allowed value. @default 100 */
   max?: number;
+  /** Step increment. @default 1 */
   step?: number;
+  /** Step used for Page Up / Page Down keyboard shortcuts. @default 10 */
   largeStep?: number;
+  /** Prevent interaction. */
   disabled?: boolean;
+  /** HTML name attribute for form submission. */
   name?: string;
+  /** Axis direction. @default "horizontal" */
   orientation?: "horizontal" | "vertical";
+  /** `Intl.NumberFormatOptions` for value display formatting. */
   format?: Intl.NumberFormatOptions;
   /** Visible label rendered above the track. */
   label?: ReactNode;
@@ -24,6 +36,12 @@ export interface SliderProps {
   className?: string;
 }
 
+/**
+ * An accessible range input with full keyboard and touch support. Pass a
+ * single number for a standard slider or an array for a range slider with
+ * two thumbs. Supports steps, large steps (Page Up/Down), and
+ * `Intl.NumberFormat` display formatting.
+ */
 export function Slider({
   label,
   showValue = false,

package/src/styles/tokens.css

@@ -5,9 +5,6 @@
  * Monospace-first, semantic color tokens, supports light & dark modes.
  */
 
-/* Establish layer order — must come before any @layer usage */
-@layer theme, base, components, utilities;
-
 @layer theme {
   :root {
     /* ─── Typography ──────────────────────────────────────────────── */
@@ -146,7 +143,7 @@
 
     /* Text */
     --color-primary: rgba(0, 0, 0, 0.88);
-    --color-secondary: rgba(0, 0, 0, 0.55);
+    --color-secondary: rgba(0, 0, 0, 0.6); /* raised from 0.55 — AA 5.01:1 on hover bg */
     --color-tertiary: rgba(0, 0, 0, 0.36);
     --color-disabled: rgba(0, 0, 0, 0.24);
     --color-inverse: rgba(255, 255, 255, 0.95);
@@ -170,6 +167,8 @@
     --color-accent: #0078d4;
     --color-accent-hover: #006bbf;
     --color-accent-pressed: #005ea8;
+    --color-accent-solid: #0078d4; /* solid button bg — same as accent in light (4.83:1 vs white) */
+    --color-accent-text: #005ea8; /* text/icon on tinted surfaces — AA 5.09:1 on accent-tint bg */
     --color-accent-tint: rgba(0, 120, 212, 0.1);
     --color-accent-tint-hover: rgba(0, 120, 212, 0.16);
 
@@ -190,20 +189,23 @@
     /* Status — Success */
     --color-success-bg: #f0fdf4;
     --color-success-border: #bbf7d0;
-    --color-success-text: #15803d;
-    --color-success-solid: #16a34a;
+    --color-success-text: #147a39; /* darkened from #15803d — AA 4.73:1 on canvas */
+    --color-success-solid: #15803d; /* darkened from #16a34a — AA 5.02:1 vs white */
+    --color-success-on-solid: #ffffff;
 
     /* Status — Warning */
     --color-warning-bg: #fffbeb;
     --color-warning-border: #fde68a;
     --color-warning-text: #92400e;
-    --color-warning-solid: #d97706;
+    --color-warning-solid: #b45309; /* darkened from #d97706 — AA 5.02:1 vs white */
+    --color-warning-on-solid: #ffffff;
 
     /* Status — Error */
     --color-error-bg: #fef2f2;
     --color-error-border: #fecaca;
     --color-error-text: #991b1b;
     --color-error-solid: #dc2626;
+    --color-error-on-solid: #ffffff;
 
     /* Status — Info */
     --color-info-bg: #eff6ff;
@@ -268,6 +270,8 @@
       --color-accent: #0a84ff;
       --color-accent-hover: #0071e3;
       --color-accent-pressed: #005bb5;
+      --color-accent-solid: #0071e3; /* solid button bg — darkened from #0a84ff — AA 4.70:1 vs white */
+      --color-accent-text: #60a5fa; /* text/icon on tinted surfaces — AA 5.87:1 on accent-tint bg */
       --color-accent-tint: rgba(10, 132, 255, 0.12);
       --color-accent-tint-hover: rgba(10, 132, 255, 0.2);
 
@@ -289,19 +293,22 @@
       --color-success-bg: rgba(22, 163, 74, 0.12);
       --color-success-border: rgba(22, 163, 74, 0.3);
       --color-success-text: #4ade80;
-      --color-success-solid: #22c55e;
+      --color-success-solid: #22c55e; /* vivid — AA 9.22:1 vs black text */
+      --color-success-on-solid: #000000; /* dark text preserves vibrancy */
 
       /* Status — Warning */
       --color-warning-bg: rgba(217, 119, 6, 0.12);
       --color-warning-border: rgba(217, 119, 6, 0.3);
       --color-warning-text: #fbbf24;
-      --color-warning-solid: #f59e0b;
+      --color-warning-solid: #f59e0b; /* vivid — AA 9.78:1 vs black text */
+      --color-warning-on-solid: #000000; /* dark text preserves vibrancy */
 
       /* Status — Error */
       --color-error-bg: rgba(220, 38, 38, 0.12);
       --color-error-border: rgba(220, 38, 38, 0.3);
       --color-error-text: #f87171;
-      --color-error-solid: #ef4444;
+      --color-error-solid: #dc2626; /* darkened from #ef4444 — AA 4.83:1 vs white */
+      --color-error-on-solid: #ffffff;
 
       /* Status — Info */
       --color-info-bg: rgba(37, 99, 235, 0.12);
@@ -355,6 +362,8 @@
     --color-accent: #0a84ff;
     --color-accent-hover: #0071e3;
     --color-accent-pressed: #005bb5;
+    --color-accent-solid: #0071e3;
+    --color-accent-text: #60a5fa;
     --color-accent-tint: rgba(10, 132, 255, 0.12);
     --color-accent-tint-hover: rgba(10, 132, 255, 0.2);
 
@@ -374,16 +383,19 @@
     --color-success-border: rgba(22, 163, 74, 0.3);
     --color-success-text: #4ade80;
     --color-success-solid: #22c55e;
+    --color-success-on-solid: #000000;
 
     --color-warning-bg: rgba(217, 119, 6, 0.12);
     --color-warning-border: rgba(217, 119, 6, 0.3);
     --color-warning-text: #fbbf24;
     --color-warning-solid: #f59e0b;
+    --color-warning-on-solid: #000000;
 
     --color-error-bg: rgba(220, 38, 38, 0.12);
     --color-error-border: rgba(220, 38, 38, 0.3);
     --color-error-text: #f87171;
-    --color-error-solid: #ef4444;
+    --color-error-solid: #dc2626;
+    --color-error-on-solid: #ffffff;
 
     --color-info-bg: rgba(37, 99, 235, 0.12);
     --color-info-border: rgba(37, 99, 235, 0.3);

package/src/switch/switch.module.css

@@ -6,10 +6,14 @@
     cursor: pointer;
     user-select: none;
   }
-  .root[data-disabled] {
-    opacity: 0.44;
+  /* data-disabled lives on the inner button, not the label wrapper.
+     Use :has() to dim the label text, and target the track directly. */
+  .root:has([data-disabled]) {
     cursor: not-allowed;
   }
+  .root:has([data-disabled]) .label {
+    opacity: 0.44;
+  }
   .thumb-track {
     position: relative;
     width: 36px;
@@ -24,6 +28,11 @@
     outline: none;
     flex-shrink: 0;
   }
+  .thumb-track[data-disabled] {
+    opacity: 0.44;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
   .thumb-track:focus-visible {
     box-shadow: var(--shadow-focus);
   }

package/src/switch/switch.tsx

@@ -4,19 +4,31 @@ import { Switch as BaseSwitch } from "@base-ui/react/switch";
 import styles from "./switch.module.css";
 
 export interface SwitchProps {
+  /** Controlled checked state. */
   checked?: boolean;
+  /** Initial checked state (uncontrolled). */
   defaultChecked?: boolean;
+  /** Prevent interaction. */
   disabled?: boolean;
+  /** Mark the field as required for form validation. */
   required?: boolean;
+  /** HTML name attribute for form submission. */
   name?: string;
+  /** HTML value attribute for form submission. */
   value?: string;
   /** Called when checked state changes. `eventDetails` is the base-ui event details object. */
   onCheckedChange?: (checked: boolean, eventDetails: unknown) => void;
+  /** Label content rendered next to the switch. */
   children?: ReactNode;
+  /** Override the auto-generated element id. */
   id?: string;
   className?: string;
 }
 
+/**
+ * Toggle for boolean settings. Renders a track with a sliding thumb and
+ * an optional label. Wraps `@base-ui/react` Switch.
+ */
 export function Switch({ children, id, className, onCheckedChange, ...props }: SwitchProps) {
   // eslint-disable-next-line react-hooks/rules-of-hooks
   const switchId = id ?? useId();

package/src/tabs/tabs.tsx

@@ -11,14 +11,21 @@ export interface TabItem {
 }
 
 export interface TabsProps {
+  /** Array of tab definitions to render. */
   items: TabItem[];
+  /** Currently active tab value (controlled). */
   value?: string;
+  /** Initially active tab value (uncontrolled). Defaults to the first item. */
   defaultValue?: string;
-  /** `eventDetails` is the base-ui event details object. */
+  /** Called when the active tab changes. `eventDetails` is the base-ui event details object. */
   onValueChange?: (value: unknown, eventDetails: unknown) => void;
   className?: string;
 }
 
+/**
+ * Tab navigation for switching between content panels. Each tab can have
+ * an optional icon and can be individually disabled.
+ */
 export function Tabs({ items, className, ...props }: TabsProps) {
   const defaultVal = props.defaultValue ?? items[0]?.value;
 

package/src/toast/toast.tsx

@@ -77,8 +77,11 @@ const DEFAULT_LIMIT: Record<NonNullable<ToastViewportProps["variant"]>, number>
 
 export interface ToastProviderProps {
   children: ReactNode;
+  /** Layout style for the viewport. @default "list" */
   variant?: ToastViewportProps["variant"];
+  /** Maximum number of toasts shown at once. */
   limit?: number;
+  /** Auto-dismiss delay in milliseconds. */
   timeout?: number;
 }
 
@@ -91,6 +94,10 @@ const MAX_LIMIT: Record<NonNullable<ToastViewportProps["variant"]>, number> = {
   list: 5,
 };
 
+/**
+ * Drop-in provider that wires limit defaults to the chosen viewport variant.
+ * Use this instead of base-ui's `Toast.Provider` when using `ToastViewport`.
+ */
 export function ToastProvider({ children, variant = "list", limit, timeout }: ToastProviderProps) {
   const resolvedLimit = Math.min(limit ?? DEFAULT_LIMIT[variant], MAX_LIMIT[variant]);
   return (
@@ -100,6 +107,10 @@ export function ToastProvider({ children, variant = "list", limit, timeout }: To
   );
 }
 
+/**
+ * Renders and manages toast notifications. Supports `"stacked"` (Sonner-style
+ * fanned cards) and `"list"` (vertically stacked, each fully visible) layouts.
+ */
 export function ToastViewport({ variant = "list", limit: _limit }: ToastViewportProps) {
   const manager = useToastManager();
   const isStacked = variant === "stacked";