@bloomreach/react-banana-ui 1.40.0 → 1.41.0

package/dist/src/components/inputs/index.d.ts

@@ -7,6 +7,7 @@ export * from './input-field';
 export * from './radio';
 export * from './radio-field';
 export * from './radio-group';
+export * from './segmented-control';
 export * from './select-field';
 export * from './select-option';
 export * from './slider';

package/dist/src/components/inputs/segmented-control/index.d.ts

@@ -0,0 +1,2 @@
+export { default as SegmentedControl } from './segmented-control';
+export type { SegmentedControlItem, SegmentedControlProps } from './segmented-control.types';

package/dist/src/components/inputs/segmented-control/segmented-control.d.ts

@@ -0,0 +1,26 @@
+import { SegmentedControlProps } from './segmented-control.types';
+/**
+ * A radio-group-based control that presents a set of mutually exclusive choices
+ * as a row of equal-width segments with an animated thumb indicator that slides
+ * to the selected item.
+ *
+ * Supports controlled and uncontrolled usage, keyboard navigation (arrow keys,
+ * Home/End, Space/Enter), full-width layout, two sizes (`md` and `sm`),
+ * read-only and disabled states, icon-only segments, and native form
+ * participation via hidden radio inputs.
+ *
+ * @example
+ * ```tsx
+ * <SegmentedControl
+ *   items={[
+ *     { value: 'day', label: 'Day' },
+ *     { value: 'week', label: 'Week' },
+ *     { value: 'month', label: 'Month' },
+ *   ]}
+ *   defaultValue="day"
+ *   onChange={(value) => console.log(value)}
+ * />
+ * ```
+ */
+declare const SegmentedControl: import('react').ForwardRefExoticComponent<SegmentedControlProps & import('react').RefAttributes<HTMLDivElement>>;
+export default SegmentedControl;

package/dist/src/components/inputs/segmented-control/segmented-control.qa.stories.d.ts

@@ -0,0 +1,18 @@
+import { Args, Meta } from '@storybook/react-vite';
+import { Story } from './segmented-control.stories';
+import { SegmentedControlProps } from './segmented-control.types';
+type StoryArgs = Args & SegmentedControlProps;
+declare const meta: Meta<StoryArgs>;
+export default meta;
+export declare const DefaultQA: Story;
+export declare const ControlledQA: Story;
+export declare const WithIconsQA: Story;
+export declare const IconOnlyQA: Story;
+export declare const SmallSizeQA: Story;
+export declare const FullWidthQA: Story;
+export declare const DisabledGroupQA: Story;
+export declare const DisabledItemsQA: Story;
+export declare const TwoItemsQA: Story;
+export declare const FiveItemsQA: Story;
+export declare const ReadOnlyQA: Story;
+export declare const CombinedStories: Story;

package/dist/src/components/inputs/segmented-control/segmented-control.stories.d.ts

@@ -0,0 +1,18 @@
+import { default as SegmentedControl } from './segmented-control';
+import { Meta, StoryObj } from '@storybook/react-vite';
+declare const meta: Meta<typeof SegmentedControl>;
+export default meta;
+export type Story = StoryObj<typeof SegmentedControl>;
+export declare const Default: Story;
+export declare const Controlled: Story;
+export declare const Uncontrolled: Story;
+export declare const WithIcons: Story;
+export declare const IconOnly: Story;
+export declare const SmallSize: Story;
+export declare const FullWidth: Story;
+export declare const DisabledGroup: Story;
+export declare const DisabledItems: Story;
+export declare const TwoItems: Story;
+export declare const FiveItems: Story;
+export declare const ReadOnly: Story;
+export declare const FormIntegration: Story;

package/dist/src/components/inputs/segmented-control/segmented-control.types.d.ts

@@ -0,0 +1,93 @@
+import { FocusEventHandler, HTMLAttributes, ReactNode } from 'react';
+export interface SegmentedControlItem {
+    /**
+     * Accessible name for icon-only segments. Required when `label` is omitted.
+     */
+    ariaLabel?: string;
+    /**
+     * Whether this individual segment is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Icon element displayed before the label (or alone for icon-only segments).
+     */
+    icon?: ReactNode;
+    /**
+     * Text label displayed in the segment.
+     */
+    label?: string;
+    /**
+     * Unique value identifying this segment.
+     */
+    value: string;
+}
+export interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color' | 'onBlur' | 'onChange' | 'onFocus' | 'role' | 'tabIndex'> {
+    /**
+     * Accessible label for the radio group.
+     */
+    'aria-label'?: string;
+    /**
+     * ID of an element that labels the radio group.
+     */
+    'aria-labelledby'?: string;
+    /**
+     * Additional CSS class applied to the root element.
+     */
+    className?: string;
+    /**
+     * The initially selected value (uncontrolled mode).
+     */
+    defaultValue?: string;
+    /**
+     * Disables the entire control and all segments.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Associates the hidden radio inputs with a `<form>` by its `id`.
+     */
+    form?: string;
+    /**
+     * When true, the control stretches to fill its container and distributes
+     * segments equally.
+     * @default false
+     */
+    fullWidth?: boolean;
+    /**
+     * The segments to render. Each item must have a unique `value`.
+     */
+    items: SegmentedControlItem[];
+    /**
+     * Name attribute for the hidden radio inputs, enabling form participation.
+     * Auto-generated if omitted.
+     */
+    name?: string;
+    /**
+     * Callback fired when a segment loses focus.
+     * The event bubbles to the control root.
+     */
+    onBlur?: FocusEventHandler<HTMLDivElement>;
+    /**
+     * Callback fired when the selected value changes.
+     */
+    onChange?: (value: string) => void;
+    /**
+     * Callback fired when a segment receives focus.
+     * The event bubbles to the control root.
+     */
+    onFocus?: FocusEventHandler<HTMLDivElement>;
+    /**
+     * When true, the control displays its value but does not allow interaction.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Size of the control.
+     * @default 'md'
+     */
+    size?: 'md' | 'sm';
+    /**
+     * The currently selected value (controlled mode).
+     */
+    value?: string;
+}

package/dist/src/components/inputs/segmented-control/use-segmented-control.d.ts

@@ -0,0 +1,69 @@
+import { FocusEvent, ForwardedRef, KeyboardEvent, RefCallback } from 'react';
+import { SegmentedControlItem } from './segmented-control.types';
+/**
+ * CSS transform and width values used to position the sliding thumb or focus
+ * indicator absolutely over a specific segment element.
+ */
+interface IndicatorStyle {
+    /** CSS `translateX` value derived from the segment's `offsetLeft`. */
+    transform: string;
+    /** Pixel width derived from the segment's `offsetWidth`. */
+    width: string;
+}
+/** Parameters accepted by the `useSegmentedControl` hook. */
+interface UseSegmentedControlParameters {
+    /** Initial selected value for uncontrolled usage. */
+    defaultValue?: string;
+    /** When `true`, all interaction is suppressed. */
+    disabled: boolean;
+    /** Ordered list of segment descriptors. */
+    items: SegmentedControlItem[];
+    /** Base name for the hidden radio inputs; auto-generated when omitted. */
+    name?: string;
+    /** Callback fired when the selected value changes. */
+    onChange?: (value: string) => void;
+    /** When `true`, the selected value is displayed but cannot be changed. */
+    readOnly: boolean;
+    /** Forwarded ref from the `SegmentedControl` component. */
+    ref: ForwardedRef<HTMLDivElement>;
+    /** Currently selected value for controlled usage. */
+    value?: string;
+}
+/** Values returned by `useSegmentedControl` for consumption by `SegmentedControl`. */
+interface UseSegmentedControlReturn {
+    /** Style for the focus-ring indicator, or `null` when no segment is focused. */
+    focusIndicatorStyle: IndicatorStyle | null;
+    /** Capture-phase blur handler that clears the focused index when focus leaves the control. */
+    handleBlur: (event: FocusEvent<HTMLDivElement>) => void;
+    /** Capture-phase focus handler that tracks which segment item currently has focus. */
+    handleFocus: (event: FocusEvent<HTMLDivElement>) => void;
+    /** Keyboard handler supporting arrow navigation, Home/End, and Space/Enter activation. */
+    handleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    /** Selects a segment by value, guarded by disabled and read-only checks. */
+    handleSelect: (value: string, isItemDisabled: boolean) => void;
+    /** When `true`, suppresses the thumb CSS transition to prevent an unwanted initial animation. */
+    isThumbTransitionDisabled: boolean;
+    /** Merged ref combining the forwarded ref and the internal root ref. */
+    mergedRef: null | RefCallback<HTMLDivElement>;
+    /** Resolved `name` attribute shared by all hidden radio inputs in the group. */
+    resolvedName: string | undefined;
+    /** The currently selected segment value. */
+    selectedValue: string | undefined;
+    /** Stable callback to register or clear a segment element ref by its array index. */
+    setItemRef: (index: number, element: HTMLDivElement | null) => void;
+    /** Index of the segment that should receive `tabIndex={0}` for roving-tabindex navigation. */
+    tabbableIndex: number;
+    /** Style for the selected-item thumb indicator, or `null` when nothing is selected. */
+    thumbStyle: IndicatorStyle | null;
+}
+/**
+ * Encapsulates all state and event-handling logic for the `SegmentedControl`
+ * component, including:
+ * - Controlled/uncontrolled value management via `useControlledValue`
+ * - Roving-tabindex keyboard navigation
+ * - Animated thumb and focus-ring indicator positioning via synchronous DOM
+ *   measurements in a layout effect
+ * - `ResizeObserver`-based indicator recalculation on container resize
+ */
+declare const useSegmentedControl: (parameters: UseSegmentedControlParameters) => UseSegmentedControlReturn;
+export default useSegmentedControl;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bloomreach/react-banana-ui",
   "type": "module",
-  "version": "1.40.0",
+  "version": "1.41.0",
   "private": false,
   "repository": {
     "type": "git",