@brijbyte/agentic-ui 0.0.3 → 0.0.5

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,31 @@
+/**
+ * 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";
+import { resolveClassName, cx } from "../utils/resolveClassName";
+
+type BaseGroupProps = ComponentPropsWithoutRef<typeof BaseRadioGroup>;
+
+export interface RadioGroupRootProps extends BaseGroupProps {}
+
+export const RadioGroupRoot = forwardRef<ComponentRef<typeof BaseRadioGroup>, RadioGroupRootProps>(function RadioGroupRoot(
+  { className, ...props },
+  ref,
+) {
+  return <BaseRadioGroup ref={ref} className={(state) => cx(styles.group, resolveClassName(className, state))} {...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/parts.tsx

@@ -33,6 +33,7 @@ import { forwardRef } from "react";
 import type { ComponentRef, ComponentPropsWithoutRef, ReactNode } from "react";
 import { Select as BaseSelect } from "@base-ui/react/select";
 import styles from "./select.module.css";
+import { resolveClassName, cx } from "../utils/resolveClassName";
 
 type BaseTriggerProps = ComponentPropsWithoutRef<typeof BaseSelect.Trigger>;
 type BaseValueProps = ComponentPropsWithoutRef<typeof BaseSelect.Value>;
@@ -46,41 +47,20 @@ type BaseGroupProps = ComponentPropsWithoutRef<typeof BaseSelect.Group>;
 type BaseGroupLabelProps = ComponentPropsWithoutRef<typeof BaseSelect.GroupLabel>;
 type BaseSeparatorProps = ComponentPropsWithoutRef<typeof BaseSelect.Separator>;
 
-export interface SelectTriggerProps extends Omit<BaseTriggerProps, "className"> {
-  className?: string;
-}
-export interface SelectValueProps extends Omit<BaseValueProps, "className"> {
-  className?: string;
-}
-export interface SelectPositionerProps extends Omit<BasePositionerProps, "className"> {
-  className?: string;
-}
-export interface SelectPopupProps extends Omit<BasePopupProps, "className"> {
-  className?: string;
-}
-export interface SelectListProps extends Omit<BaseListProps, "className"> {
-  className?: string;
-}
-export interface SelectItemProps extends Omit<BaseItemProps, "className"> {
-  className?: string;
-}
-export interface SelectItemTextProps extends Omit<BaseItemTextProps, "className"> {
-  className?: string;
-}
-export interface SelectItemIndicatorProps extends Omit<BaseItemIndicatorProps, "className"> {
-  className?: string;
+export interface SelectTriggerProps extends BaseTriggerProps {}
+export interface SelectValueProps extends BaseValueProps {}
+export interface SelectPositionerProps extends BasePositionerProps {}
+export interface SelectPopupProps extends BasePopupProps {}
+export interface SelectListProps extends BaseListProps {}
+export interface SelectItemProps extends BaseItemProps {}
+export interface SelectItemTextProps extends BaseItemTextProps {}
+export interface SelectItemIndicatorProps extends BaseItemIndicatorProps {
   /** Custom icon. Defaults to a checkmark SVG. */
   children?: ReactNode;
 }
-export interface SelectGroupProps extends Omit<BaseGroupProps, "className"> {
-  className?: string;
-}
-export interface SelectGroupLabelProps extends Omit<BaseGroupLabelProps, "className"> {
-  className?: string;
-}
-export interface SelectSeparatorProps extends Omit<BaseSeparatorProps, "className"> {
-  className?: string;
-}
+export interface SelectGroupProps extends BaseGroupProps {}
+export interface SelectGroupLabelProps extends BaseGroupLabelProps {}
+export interface SelectSeparatorProps extends BaseSeparatorProps {}
 
 function DefaultCheckIcon() {
   return (
@@ -94,42 +74,49 @@ export const SelectTrigger = forwardRef<ComponentRef<typeof BaseSelect.Trigger>,
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Trigger ref={ref} className={`${styles.trigger} ${className ?? ""}`} {...props} />;
+  return <BaseSelect.Trigger ref={ref} className={(state) => cx(styles.trigger, resolveClassName(className, state))} {...props} />;
 });
 
 export const SelectValue = forwardRef<ComponentRef<typeof BaseSelect.Value>, SelectValueProps>(function SelectValue(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Value ref={ref} className={`${styles["trigger-value"]} ${className ?? ""}`} {...props} />;
+  return <BaseSelect.Value ref={ref} className={(state) => cx(styles["trigger-value"], resolveClassName(className, state))} {...props} />;
 });
 
 export const SelectPositioner = forwardRef<ComponentRef<typeof BaseSelect.Positioner>, SelectPositionerProps>(function SelectPositioner(
   { className, sideOffset = 4, ...props },
   ref,
 ) {
-  return <BaseSelect.Positioner ref={ref} className={`${styles.positioner} ${className ?? ""}`} sideOffset={sideOffset} {...props} />;
+  return (
+    <BaseSelect.Positioner
+      ref={ref}
+      className={(state) => cx(styles.positioner, resolveClassName(className, state))}
+      sideOffset={sideOffset}
+      {...props}
+    />
+  );
 });
 
 export const SelectPopup = forwardRef<ComponentRef<typeof BaseSelect.Popup>, SelectPopupProps>(function SelectPopup(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Popup ref={ref} className={`${styles.popup} ${className ?? ""}`} {...props} />;
+  return <BaseSelect.Popup ref={ref} className={(state) => cx(styles.popup, resolveClassName(className, state))} {...props} />;
 });
 
 export const SelectList = forwardRef<ComponentRef<typeof BaseSelect.List>, SelectListProps>(function SelectList(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.List ref={ref} className={`${styles.list ?? ""} ${className ?? ""}`} {...props} />;
+  return <BaseSelect.List ref={ref} className={(state) => cx(styles.list ?? "", resolveClassName(className, state))} {...props} />;
 });
 
 export const SelectItem = forwardRef<ComponentRef<typeof BaseSelect.Item>, SelectItemProps>(function SelectItem(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Item ref={ref} className={`${styles.item} ${className ?? ""}`} {...props} />;
+  return <BaseSelect.Item ref={ref} className={(state) => cx(styles.item, resolveClassName(className, state))} {...props} />;
 });
 
 export const SelectItemText = forwardRef<ComponentRef<typeof BaseSelect.ItemText>, SelectItemTextProps>(function SelectItemText(
@@ -142,7 +129,11 @@ export const SelectItemText = forwardRef<ComponentRef<typeof BaseSelect.ItemText
 export const SelectItemIndicator = forwardRef<ComponentRef<typeof BaseSelect.ItemIndicator>, SelectItemIndicatorProps>(
   function SelectItemIndicator({ className, children, ...props }, ref) {
     return (
-      <BaseSelect.ItemIndicator ref={ref} className={`${styles["item-indicator"]} ${className ?? ""}`} {...props}>
+      <BaseSelect.ItemIndicator
+        ref={ref}
+        className={(state) => cx(styles["item-indicator"], resolveClassName(className, state))}
+        {...props}
+      >
         {children ?? <DefaultCheckIcon />}
       </BaseSelect.ItemIndicator>
     );
@@ -160,12 +151,14 @@ export const SelectGroupLabel = forwardRef<ComponentRef<typeof BaseSelect.GroupL
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.GroupLabel ref={ref} className={`${styles["group-label"]} ${className ?? ""}`} {...props} />;
+  return (
+    <BaseSelect.GroupLabel ref={ref} className={(state) => cx(styles["group-label"], resolveClassName(className, state))} {...props} />
+  );
 });
 
 export const SelectSeparator = forwardRef<ComponentRef<typeof BaseSelect.Separator>, SelectSeparatorProps>(function SelectSeparator(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Separator ref={ref} className={`${styles.separator} ${className ?? ""}`} {...props} />;
+  return <BaseSelect.Separator ref={ref} className={(state) => cx(styles.separator, resolveClassName(className, state))} {...props} />;
 });

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/parts.tsx

@@ -20,6 +20,7 @@ import { forwardRef } from "react";
 import type { ComponentRef, ComponentPropsWithoutRef } from "react";
 import { Slider as BaseSlider } from "@base-ui/react/slider";
 import styles from "./slider.module.css";
+import { resolveClassName, cx } from "../utils/resolveClassName";
 
 type BaseControlProps = ComponentPropsWithoutRef<typeof BaseSlider.Control>;
 type BaseTrackProps = ComponentPropsWithoutRef<typeof BaseSlider.Track>;
@@ -28,63 +29,51 @@ type BaseThumbProps = ComponentPropsWithoutRef<typeof BaseSlider.Thumb>;
 type BaseLabelProps = ComponentPropsWithoutRef<typeof BaseSlider.Label>;
 type BaseValueProps = ComponentPropsWithoutRef<typeof BaseSlider.Value>;
 
-export interface SliderControlProps extends Omit<BaseControlProps, "className"> {
-  className?: string;
-}
-export interface SliderTrackProps extends Omit<BaseTrackProps, "className"> {
-  className?: string;
-}
-export interface SliderIndicatorProps extends Omit<BaseIndicatorProps, "className"> {
-  className?: string;
-}
-export interface SliderThumbProps extends Omit<BaseThumbProps, "className"> {
-  className?: string;
-}
-export interface SliderLabelProps extends Omit<BaseLabelProps, "className"> {
-  className?: string;
-}
-export interface SliderValueProps extends Omit<BaseValueProps, "className"> {
-  className?: string;
-}
+export interface SliderControlProps extends BaseControlProps {}
+export interface SliderTrackProps extends BaseTrackProps {}
+export interface SliderIndicatorProps extends BaseIndicatorProps {}
+export interface SliderThumbProps extends BaseThumbProps {}
+export interface SliderLabelProps extends BaseLabelProps {}
+export interface SliderValueProps extends BaseValueProps {}
 
 export const SliderControl = forwardRef<ComponentRef<typeof BaseSlider.Control>, SliderControlProps>(function SliderControl(
   { className, ...props },
   ref,
 ) {
-  return <BaseSlider.Control ref={ref} className={`${styles.control} ${className ?? ""}`} {...props} />;
+  return <BaseSlider.Control ref={ref} className={(state) => cx(styles.control, resolveClassName(className, state))} {...props} />;
 });
 
 export const SliderTrack = forwardRef<ComponentRef<typeof BaseSlider.Track>, SliderTrackProps>(function SliderTrack(
   { className, ...props },
   ref,
 ) {
-  return <BaseSlider.Track ref={ref} className={`${styles.track} ${className ?? ""}`} {...props} />;
+  return <BaseSlider.Track ref={ref} className={(state) => cx(styles.track, resolveClassName(className, state))} {...props} />;
 });
 
 export const SliderIndicator = forwardRef<ComponentRef<typeof BaseSlider.Indicator>, SliderIndicatorProps>(function SliderIndicator(
   { className, ...props },
   ref,
 ) {
-  return <BaseSlider.Indicator ref={ref} className={`${styles.indicator} ${className ?? ""}`} {...props} />;
+  return <BaseSlider.Indicator ref={ref} className={(state) => cx(styles.indicator, resolveClassName(className, state))} {...props} />;
 });
 
 export const SliderThumb = forwardRef<ComponentRef<typeof BaseSlider.Thumb>, SliderThumbProps>(function SliderThumb(
   { className, ...props },
   ref,
 ) {
-  return <BaseSlider.Thumb ref={ref} className={`${styles.thumb} ${className ?? ""}`} {...props} />;
+  return <BaseSlider.Thumb ref={ref} className={(state) => cx(styles.thumb, resolveClassName(className, state))} {...props} />;
 });
 
 export const SliderLabel = forwardRef<ComponentRef<typeof BaseSlider.Label>, SliderLabelProps>(function SliderLabel(
   { className, ...props },
   ref,
 ) {
-  return <BaseSlider.Label ref={ref} className={`${styles.label} ${className ?? ""}`} {...props} />;
+  return <BaseSlider.Label ref={ref} className={(state) => cx(styles.label, resolveClassName(className, state))} {...props} />;
 });
 
 export const SliderValue = forwardRef<ComponentRef<typeof BaseSlider.Value>, SliderValueProps>(function SliderValue(
   { className, ...props },
   ref,
 ) {
-  return <BaseSlider.Value ref={ref} className={`${styles.value} ${className ?? ""}`} {...props} />;
+  return <BaseSlider.Value ref={ref} className={(state) => cx(styles.value, resolveClassName(className, state))} {...props} />;
 });

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,