@ahrowe/ui 0.12.0 → 0.14.0

package/dist/types/package/common/configProvider/configProvider.types.d.ts

@@ -18,6 +18,11 @@ import { SectionHeaderProps } from '../sectionHeader/sectionHeader.types';
 import { SkeletonProps } from '../skeleton/skeleton.types';
 import { AccordionProps } from '../accordion/accordion.types';
 import { DividerProps } from '../divider/divider.types';
+import { AlertProps } from '../alert/alert.types';
+import { CarouselProps } from '../carousel/carousel.types';
+import { BreadcrumbProps } from '../breadcrumb/breadcrumb.types';
+import { RatingProps } from '../rating/rating.types';
+import { SplitButtonProps } from '../splitButton/splitButton.types';
 /**
  * Global default props keyed by component name.
  *
@@ -52,6 +57,11 @@ export interface ComponentDefaults {
     Skeleton?: Partial<SkeletonProps>;
     Accordion?: Partial<AccordionProps>;
     Divider?: Partial<DividerProps>;
+    Alert?: Partial<AlertProps>;
+    Carousel?: Partial<CarouselProps>;
+    Breadcrumb?: Partial<BreadcrumbProps>;
+    Rating?: Partial<RatingProps>;
+    SplitButton?: Partial<SplitButtonProps>;
 }
 export interface ConfigProviderProps {
     children: React.ReactNode;

package/dist/types/package/common/divider/divider.types.d.ts

@@ -5,10 +5,15 @@ export declare enum DividerTextPosition {
     Center = "center",
     Right = "right"
 }
+export declare enum DividerOrientation {
+    Horizontal = "horizontal",
+    Vertical = "vertical"
+}
 export type DividerSlots = 'root' | 'line' | 'content';
 export interface DividerProps extends HtmlProps {
     text?: ReactNode;
     textPosition?: DividerTextPosition;
+    orientation?: DividerOrientation;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<DividerSlots>;

package/dist/types/package/common/hooks/useFocusBoundary.d.ts

@@ -0,0 +1,20 @@
+import { RefObject } from 'react';
+/** Tabbable descendants of `root`, in DOM order. */
+export declare function tabbablesIn(root: ParentNode | null): HTMLElement[];
+export interface UseFocusBoundaryArgs {
+    /** The trigger element focus returns to on Escape / Shift+Tab out of the content's top. */
+    triggerRef: RefObject<HTMLElement | null>;
+    /** The portaled content root — tabbables inside it define the Tab boundary. */
+    contentRef: RefObject<HTMLElement | null>;
+}
+/**
+ * Focus helpers for content portaled to the end of the DOM (e.g. via BodyEnd), where Tab can't
+ * reach it in visual document order on its own. Shared by FloatingMenu and Popover, which both
+ * need to hand focus back to the trigger on Escape / Shift+Tab out of the top, and continue
+ * focus naturally past the trigger when Tab exits the bottom.
+ */
+export declare function useFocusBoundary({ triggerRef, contentRef }: UseFocusBoundaryArgs): {
+    firstTriggerFocusable: () => HTMLElement | null;
+    restoreFocusToTrigger: () => void;
+    focusAfterTrigger: () => void;
+};

package/dist/types/package/common/input/input.types.d.ts

@@ -11,6 +11,10 @@ export declare enum InputType {
     Search = "searchInput",
     Password = "password"
 }
+export declare enum InputIconPosition {
+    Left = "left",
+    Right = "right"
+}
 export type InputSlots = 'label' | 'container' | 'input' | 'suffix' | 'upperRightLabel' | 'fieldset';
 type OverriddenInputAttributes = 'onChange' | 'onFocus' | 'onBlur' | 'onMouseEnter' | 'onMouseLeave' | 'onClick' | 'type' | 'value' | 'min' | 'max' | 'autoComplete';
 export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, OverriddenInputAttributes>, HtmlProps {
@@ -28,6 +32,7 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     style?: React.CSSProperties;
     value?: string | number;
     icon?: React.ReactElement | null;
+    iconPosition?: InputIconPosition;
     isUppercase?: boolean;
     isRow?: boolean;
     tabIndex?: number;

package/dist/types/package/common/rating/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './rating';
+export * from './rating.types';

package/dist/types/package/common/rating/rating.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { RatingProps } from './rating.types';
+declare function Rating(props: RatingProps): ReactElement;
+export default Rating;

package/dist/types/package/common/rating/rating.types.d.ts

@@ -0,0 +1,19 @@
+import { CSSProperties } from 'react';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+export type RatingSlots = 'root' | 'item' | 'iconEmpty' | 'iconFilled';
+export interface RatingProps extends HtmlProps {
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    max?: number;
+    allowHalf?: boolean;
+    allowClear?: boolean;
+    readOnly?: boolean;
+    disabled?: boolean;
+    icon?: IconDefinition;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<RatingSlots>;
+    styles?: SlotStyles<RatingSlots>;
+}

package/dist/types/package/common/splitButton/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './splitButton';
+export * from './splitButton.types';

package/dist/types/package/common/splitButton/splitButton.d.ts

@@ -0,0 +1,3 @@
+import { SplitButtonProps } from './splitButton.types';
+declare function SplitButton(props: SplitButtonProps): import("react/jsx-runtime").JSX.Element;
+export default SplitButton;

package/dist/types/package/common/splitButton/splitButton.types.d.ts

@@ -0,0 +1,28 @@
+import { CSSProperties, ReactNode } from 'react';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { ButtonStyleType, ButtonSize } from '../button/button.types';
+import { Align } from '../floatingMenu/floatingMenu.types';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+export interface SplitButtonAction {
+    id: string;
+    label: ReactNode;
+    onClick: () => void;
+    disabled?: boolean;
+    icon?: IconDefinition;
+}
+export type SplitButtonSlots = 'root' | 'primaryButton' | 'triggerButton' | 'menu' | 'menuItem';
+export interface SplitButtonProps extends HtmlProps {
+    children?: ReactNode;
+    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void> | void;
+    actions: SplitButtonAction[];
+    styleType?: ButtonStyleType;
+    size?: ButtonSize;
+    disabled?: boolean;
+    isLoading?: boolean;
+    /** Alignment of the actions menu relative to the trigger button (default `Align.Right`) */
+    align?: Align;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<SplitButtonSlots>;
+    styles?: SlotStyles<SplitButtonSlots>;
+}

package/dist/types/package/common/themeProvider/theme.types.d.ts

@@ -56,6 +56,7 @@ export interface ThemeVariables {
     '--error-border-color'?: string;
     '--input-label-resting-color'?: string;
     '--input-label-floating-color'?: string;
+    '--search-input-color'?: string;
     '--default-border-radius'?: string;
     '--padding-sides'?: string;
     '--margin-top'?: string;

package/dist/types/package/common/virtualList/useRowDrag.d.ts

@@ -19,9 +19,13 @@ interface UseRowDragArgs {
 /** The drag-related props the parent spreads onto a given row. */
 export interface RowDragProps {
     reorderable: boolean;
+    /** Native mouse DnD is active for the list (independent of which row is armed). */
+    mouseDragEnabled: boolean;
     draggable: boolean | undefined;
     isDragging: boolean;
     onMouseDown: ((e: React.MouseEvent<HTMLDivElement>) => void) | undefined;
+    onMouseOver: ((e: React.MouseEvent<HTMLDivElement>) => void) | undefined;
+    onMouseLeave: ((e: React.MouseEvent<HTMLDivElement>) => void) | undefined;
     onDragStart: ((e: React.DragEvent<HTMLDivElement>) => void) | undefined;
     onDragOver: ((e: React.DragEvent<HTMLDivElement>) => void) | undefined;
     onDragEnd: (() => void) | undefined;

package/dist/types/package/common/virtualList/useVirtualWindow.d.ts

@@ -10,6 +10,8 @@ interface UseVirtualWindowArgs<T> {
     overscan: number;
     onLoadMore?: () => Promise<void>;
     loadMoreThreshold: number;
+    /** Initial/filter load in progress — the body is replaced by a spinner. */
+    isLoading: boolean;
 }
 interface UseVirtualWindowResult {
     rootRef: React.RefObject<HTMLDivElement | null>;
@@ -37,5 +39,5 @@ interface UseVirtualWindowResult {
  * scroll handle. Mode-agnostic — knows nothing about columns, selection or
  * dragging.
  */
-export declare function useVirtualWindow<T>({ items, keys, getItemKey, estimatedRowHeight, rowGap, overscan, onLoadMore, loadMoreThreshold, }: UseVirtualWindowArgs<T>): UseVirtualWindowResult;
+export declare function useVirtualWindow<T>({ items, keys, getItemKey, estimatedRowHeight, rowGap, overscan, onLoadMore, loadMoreThreshold, isLoading, }: UseVirtualWindowArgs<T>): UseVirtualWindowResult;
 export {};

package/dist/types/package/common/virtualList/virtualList.types.d.ts

@@ -132,7 +132,11 @@ export interface VirtualListProps<T> extends HtmlProps {
     /** Show the gear column-toggle button in the header. Default: true when columns present. */
     showColumnToggle?: boolean;
     /**
-     * Called when the user scrolls within `loadMoreThreshold` px of the bottom.
+     * Called when the user scrolls within `loadMoreThreshold` px of the bottom, and
+     * repeatedly while the rows don't fill the viewport — a list too short to scroll
+     * would otherwise never ask for a second batch. Each row count is asked at most
+     * once, so the loop ends as soon as a call appends nothing; pass `undefined`
+     * once the source is exhausted to skip even that final probe.
      * Must return a Promise that resolves once new items have been appended to `items`.
      * A spinner is shown at the bottom while the Promise is pending.
      */

package/dist/types/package/common/virtualList/virtualRow.d.ts

@@ -16,10 +16,17 @@ export interface VirtualRowProps {
     ariaSetSize?: number;
     rowRole: 'row' | 'listitem';
     reorderable?: boolean;
+    /**
+     * Native mouse DnD is active for the list. Distinct from `draggable`, which in
+     * `dragHandle` mode is only set on the row the pointer has armed.
+     */
+    mouseDragEnabled?: boolean;
     draggable?: boolean;
     isDragging?: boolean;
     reserveToggleGutter?: boolean;
     onMouseDown?: (e: React.MouseEvent<HTMLDivElement>) => void;
+    onMouseOver?: (e: React.MouseEvent<HTMLDivElement>) => void;
+    onMouseLeave?: (e: React.MouseEvent<HTMLDivElement>) => void;
     onDragStart?: (e: React.DragEvent<HTMLDivElement>) => void;
     onDragOver?: (e: React.DragEvent<HTMLDivElement>) => void;
     onDragEnd?: () => void;
@@ -38,5 +45,5 @@ export interface VirtualRowProps {
  * grid (table mode), registering itself with the shared ResizeObserver and
  * carrying all the drag / drop-indicator wiring the parent assigns it.
  */
-declare function VirtualRow({ index, top, padding, columnTemplate, isSelected, showDivider, hover, onClick, observer, ariaRowIndex, ariaPosInSet, ariaSetSize, rowRole, reorderable, draggable, isDragging, reserveToggleGutter, onMouseDown, onDragStart, onDragOver, onDragEnd, onDrop, onTouchStart, dropPosition, dropIndentPx, dropIndicatorClassName, dropIndicatorStyle, rowClassName, rowStyle, children, }: VirtualRowProps): import("react/jsx-runtime").JSX.Element;
+declare function VirtualRow({ index, top, padding, columnTemplate, isSelected, showDivider, hover, onClick, observer, ariaRowIndex, ariaPosInSet, ariaSetSize, rowRole, reorderable, mouseDragEnabled, draggable, isDragging, reserveToggleGutter, onMouseDown, onMouseOver, onMouseLeave, onDragStart, onDragOver, onDragEnd, onDrop, onTouchStart, dropPosition, dropIndentPx, dropIndicatorClassName, dropIndicatorStyle, rowClassName, rowStyle, children, }: VirtualRowProps): import("react/jsx-runtime").JSX.Element;
 export default VirtualRow;

package/dist/types/package/index.d.ts

@@ -3,6 +3,8 @@ export * from './common/accordion';
 export * from './common/actionButtons';
 export { default as ActionIcon } from './common/actionIcon';
 export * from './common/actionIcon';
+export { default as Alert } from './common/alert';
+export * from './common/alert';
 export { default as AnimatedLogo } from './common/animatedLogo';
 export * from './common/animatedLogo';
 export { default as AnimatedText } from './common/animatedText';
@@ -13,10 +15,16 @@ export { default as Badge } from './common/badge';
 export * from './common/badge';
 export { default as BodyEnd } from './common/bodyEnd';
 export * from './common/bodyEnd';
+export { default as Breadcrumb } from './common/breadcrumb';
+export * from './common/breadcrumb';
 export { default as Button } from './common/button';
 export * from './common/button';
+export { default as ButtonGroup } from './common/buttonGroup';
+export * from './common/buttonGroup';
 export { default as Card } from './common/card';
 export * from './common/card';
+export { default as Carousel } from './common/carousel';
+export * from './common/carousel';
 export { default as Checkbox } from './common/checkbox';
 export * from './common/checkbox';
 export { default as Chip } from './common/chip';
@@ -74,6 +82,8 @@ export { default as ProgressBar } from './common/progressBar';
 export * from './common/progressBar';
 export { default as RadioGroup } from './common/radioGroup';
 export * from './common/radioGroup';
+export { default as Rating } from './common/rating';
+export * from './common/rating';
 export { default as Ripple } from './common/ripple';
 export * from './common/ripple';
 export { default as RoomDrawer } from './common/roomDrawer';
@@ -90,6 +100,8 @@ export { default as Skeleton } from './common/skeleton';
 export * from './common/skeleton';
 export { default as Slider } from './common/slider';
 export * from './common/slider';
+export { default as SplitButton } from './common/splitButton';
+export * from './common/splitButton';
 export { default as Stepper } from './common/stepper';
 export * from './common/stepper';
 export { default as Sticky } from './common/sticky';

package/docs/Alert.md

@@ -0,0 +1,64 @@
+# Alert
+
+**When to use:** A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices. Unlike `Toast`, it isn't portaled or auto-dismissed, and it stays in the page's normal flow for as long as its consumer renders it. Use `Toast` instead for a transient, corner-anchored notification.
+
+**Import:** `import { Alert, AlertStyleType } from '@ahrowe/ui'`
+
+**Style variants:** `AlertStyleType.Default` | `AlertStyleType.Info` | `AlertStyleType.Success` | `AlertStyleType.Warn` | `AlertStyleType.Error`
+
+```tsx
+import { Alert, AlertStyleType } from '@ahrowe/ui';
+
+// Default, neutral message
+<Alert>A default, neutral message.</Alert>
+
+// Semantic variants
+<Alert styleType={AlertStyleType.Info}>Here's something worth knowing.</Alert>
+<Alert styleType={AlertStyleType.Success}>Your changes were saved.</Alert>
+<Alert styleType={AlertStyleType.Warn}>Your storage is almost full.</Alert>
+<Alert styleType={AlertStyleType.Error}>Something went wrong. Please try again.</Alert>
+
+// With a title
+<Alert styleType={AlertStyleType.Warn} title="Storage almost full">
+  You've used 92% of your available space. Free up room or upgrade your plan.
+</Alert>
+
+// Dismissible: the consumer owns visibility. onClose is called on click,
+// so stop rendering the Alert (or flip your own state) to actually hide it
+const [visible, setVisible] = useState(true);
+{visible && (
+  <Alert
+    styleType={AlertStyleType.Info}
+    title="New feature available"
+    onClose={() => setVisible(false)}
+  >
+    Try out the new dashboard layout from your account settings.
+  </Alert>
+)}
+
+// Without the leading icon
+<Alert styleType={AlertStyleType.Success} hideIcon>
+  A minimal message with no leading icon.
+</Alert>
+
+// Custom icon, overriding the styleType default
+import { faRocket } from '@fortawesome/free-solid-svg-icons';
+<Alert styleType={AlertStyleType.Info} icon={faRocket}>
+  Shipping a new release tonight.
+</Alert>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `ReactNode` | Optional bold heading above the description |
+| `children` | `ReactNode` | The message body |
+| `styleType` | `AlertStyleType` | Colour variant and default icon (default `Default`) |
+| `icon` | `IconDefinition` | Overrides the default FontAwesome icon for `styleType` |
+| `hideIcon` | `boolean` | Hide the leading icon entirely |
+| `onClose` | `() => void` | Shows a close button and is called when it's clicked. `Alert` doesn't hide itself, so stop rendering it (or update your own state) in the handler |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Alert: { hideIcon: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `icon` `content` `title` `description` `closeButton`

package/docs/Breadcrumb.md

@@ -0,0 +1,106 @@
+# Breadcrumb
+
+**When to use:** A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page. The last item is always rendered as the current page and isn't clickable.
+
+**Import:** `import { Breadcrumb } from '@ahrowe/ui'`
+**Types:** `import type { BreadcrumbItem, BreadcrumbProps } from '@ahrowe/ui'`
+
+```tsx
+import { Breadcrumb } from '@ahrowe/ui';
+import type { BreadcrumbItem } from '@ahrowe/ui';
+
+const items: BreadcrumbItem[] = [
+  { label: 'Home', href: '/' },
+  { label: 'Documents', href: '/documents' },
+  { label: 'Report.pdf' }, // last item: rendered as the current page, not a link
+];
+
+<Breadcrumb items={items} />
+
+// With leading icons
+import { faHouse, faFolder } from '@fortawesome/free-solid-svg-icons';
+
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/', icon: faHouse },
+    { label: 'Projects', href: '/projects', icon: faFolder },
+    { label: 'Current project' },
+  ]}
+/>
+
+// Client-side routing (e.g. react-router): keep href for a real, right-clickable link,
+// and use onClick to intercept the native navigation with the router's own navigate()
+import { useNavigate } from 'react-router-dom';
+
+function Example() {
+  const navigate = useNavigate();
+  return (
+    <Breadcrumb
+      items={[
+        {
+          label: 'Home',
+          href: '/',
+          onClick: (event) => {
+            event.preventDefault();
+            navigate('/');
+          },
+        },
+        { label: 'Current page' },
+      ]}
+    />
+  );
+}
+
+// A disabled crumb: dimmed, not clickable, regardless of href/onClick
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Archived', href: '/archived', disabled: true },
+    { label: 'Old report' },
+  ]}
+/>
+
+// Custom separator (default is a chevron icon)
+<Breadcrumb items={items} separator="/" />
+
+// Long trails: collapse the middle behind a clickable ellipsis once items.length
+// exceeds maxItems. The ellipsis counts as one of the visible slots, so maxItems={3}
+// on a 4-item trail shows: Home / ... / Settings. Clicking the ellipsis opens a menu
+// (via FloatingMenu) listing the hidden items.
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Invoices', href: '/invoices' },
+    { label: 'Editor', href: '/invoices/editor' },
+    { label: 'Settings' },
+  ]}
+  maxItems={3}
+/>
+```
+
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `maxItems` is used and the trail actually collapses (the hidden-items menu is a `FloatingMenu`, which renders via portal).
+
+**BreadcrumbItem:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Optional stable key; falls back to the item's index |
+| `label` | `ReactNode` | The crumb's text |
+| `href` | `string` | Renders the crumb as a real `<a>`. Omit to render a plain clickable element (with `onClick`) or static text |
+| `icon` | `IconDefinition` | Optional leading FontAwesome icon |
+| `onClick` | `(event: MouseEvent) => void` | Click handler. Works alongside `href`: call `event.preventDefault()` to stop the native navigation and hand off to a client-side router's own navigate function (see the react-router example above). Also works on its own, with no `href` |
+| `disabled` | `boolean` | Dims the crumb and makes it non-interactive, regardless of `href`/`onClick` |
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `BreadcrumbItem[]` | The crumbs, in order. The last one is always rendered as the current page |
+| `separator` | `ReactNode` | Overrides the default chevron separator between items |
+| `maxItems` | `number` | Collapses the middle items behind a clickable ellipsis once `items.length` exceeds this. The ellipsis counts as one of the visible slots, alongside the always-shown first item (so `maxItems={3}` shows first item, ellipsis, last item) |
+
+**Collapsing behaviour:** the hidden count grows and shrinks by exactly however many items are actually over the limit, rather than always jumping to the same minimal first/ellipsis/last shape. A trail with 11 items and `maxItems={10}` hides only 2 items, not the whole middle, so the trail doesn't visually lurch as one more level of navigation pushes it just over the limit.
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Breadcrumb: { separator: '/' } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `list` `item` `link` `icon` `separator` `current` `ellipsis` `hiddenList` `hiddenItem`

package/docs/ButtonGroup.md

@@ -0,0 +1,90 @@
+# ButtonGroup
+
+**When to use:** Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners. Use for a segmented toggle ("Day / Week / Month"), an icon toolbar (bold/italic/underline), or any set of related actions that should read as one control rather than separate buttons. Purely a layout wrapper, no interaction logic of its own, so any button-like children work, not just `Button`.
+
+**Import:** `import { ButtonGroup, ButtonGroupOrientation } from '@ahrowe/ui'`
+
+**Orientation:** `ButtonGroupOrientation.Horizontal` (default) | `ButtonGroupOrientation.Vertical`
+
+```tsx
+import { ButtonGroup, ButtonGroupOrientation, Button, ButtonStyleType } from '@ahrowe/ui';
+
+// Segmented toggle
+<ButtonGroup>
+  <Button styleType={ButtonStyleType.Default}>Day</Button>
+  <Button styleType={ButtonStyleType.Default}>Week</Button>
+  <Button styleType={ButtonStyleType.Default}>Month</Button>
+</ButtonGroup>
+
+// Icon toolbar
+<ButtonGroup>
+  <Button styleType={ButtonStyleType.Default} icon={faBold} aria-label="Bold" />
+  <Button styleType={ButtonStyleType.Default} icon={faItalic} aria-label="Italic" />
+  <Button styleType={ButtonStyleType.Default} icon={faUnderline} aria-label="Underline" />
+</ButtonGroup>
+
+// Vertical
+<ButtonGroup orientation={ButtonGroupOrientation.Vertical}>
+  <Button styleType={ButtonStyleType.Default}>Bold</Button>
+  <Button styleType={ButtonStyleType.Default}>Italic</Button>
+  <Button styleType={ButtonStyleType.Default}>Underline</Button>
+</ButtonGroup>
+
+// With a separator — filled styles (Primary/Delete) have no border of their own to merge,
+// so a vertical Divider gives adjacent buttons a visible seam instead of blending together
+import { Divider, DividerOrientation } from '@ahrowe/ui';
+
+<ButtonGroup>
+  <Button styleType={ButtonStyleType.Primary}>Save</Button>
+  <Divider orientation={DividerOrientation.Vertical} />
+  <Button styleType={ButtonStyleType.Primary}>Save & new</Button>
+</ButtonGroup>
+
+// Nested groups — a toolbar made of two self-contained sub-groups, spaced apart rather
+// than merged into one continuous strip
+<ButtonGroup>
+  <ButtonGroup>
+    <Button styleType={ButtonStyleType.Default} icon={faBold} aria-label="Bold" />
+    <Button styleType={ButtonStyleType.Default} icon={faItalic} aria-label="Italic" />
+    <Button styleType={ButtonStyleType.Default} icon={faUnderline} aria-label="Underline" />
+  </ButtonGroup>
+  <ButtonGroup>
+    <Button styleType={ButtonStyleType.Default} icon={faAlignLeft} aria-label="Align left" />
+    <Button styleType={ButtonStyleType.Default} icon={faAlignCenter} aria-label="Align center" />
+    <Button styleType={ButtonStyleType.Default} icon={faAlignRight} aria-label="Align right" />
+  </ButtonGroup>
+</ButtonGroup>
+
+// With an Input — a search bar. Input's visible border lives on its own container/fieldset
+// elements, not its root, so (like SplitButton) the side touching the button needs a manual
+// corner override via Input's own slots rather than ButtonGroup's automatic ones
+import { Input } from '@ahrowe/ui';
+
+const groupedInputStyle = { borderTopRightRadius: 0, borderBottomRightRadius: 0 };
+
+<ButtonGroup>
+  <Input
+    placeholder="Search…"
+    useMatLabelStyle={false}
+    value={search}
+    onChange={setSearch}
+    styles={{ container: groupedInputStyle, fieldset: groupedInputStyle }}
+  />
+  <Button styleType={ButtonStyleType.Primary} icon={faMagnifyingGlass} aria-label="Search" />
+</ButtonGroup>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The buttons (or button-like elements) to join, in order |
+| `orientation` | `ButtonGroupOrientation` | Layout direction (default `Horizontal`) |
+
+**How it works:** the first and last children keep rounded outer corners; every child in between is flattened on both sides. Adjacent borders are collapsed with a `-1px` margin so two 1px borders don't stack into a visible double line, and whichever child is hovered/focused gets a `z-index` bump so its border/focus ring isn't clipped by its neighbors.
+
+**Separators:** any child with `role="separator"` (what `Divider` sets) is excluded from that border-collapsing margin, on both sides — it stays fully visible between its neighbors instead of being partially hidden under one of them. Use a vertical `Divider` (see [Divider.md](Divider.md)) between two buttons when their style has no visible border of its own to merge (`Primary`, `Delete`), so there's still a clear seam between them.
+
+**Note:** the corner-flattening rules key off DOM position (`:first-child`/`:last-child`), so they work for direct `Button` children out of the box. A child that renders as a wrapper around its own button (e.g. a component that portals its real content elsewhere) won't get the flattening automatically. `SplitButton` is exactly that case (its second child is a `FloatingMenu`-wrapped button), which is why it sets its own corner overrides directly rather than relying on `ButtonGroup`'s automatic ones. See [SplitButton.md](SplitButton.md).
+
+**Slots:** none — `ButtonGroup` has no named inner elements, only `className`/`style` on the root.

package/docs/CLAUDE.md

@@ -95,13 +95,17 @@ Slot keys per component are documented in each component's doc file below.
 @Accordion.md
 @ActionButtons.md
 @ActionIcon.md
+@Alert.md
 @AnimatedLogo.md
 @AnimatedText.md
 @Avatar.md
 @Badge.md
 @BodyEnd.md
+@Breadcrumb.md
 @Button.md
+@ButtonGroup.md
 @Card.md
+@Carousel.md
 @Checkbox.md
 @Chip.md
 @ColorPicker.md
@@ -133,6 +137,7 @@ Slot keys per component are documented in each component's doc file below.
 @Popover.md
 @ProgressBar.md
 @RadioGroup.md
+@Rating.md
 @Ripple.md
 @RoomDrawer.md
 @RoomViewer.md
@@ -141,6 +146,7 @@ Slot keys per component are documented in each component's doc file below.
 @SectionHeader.md
 @Skeleton.md
 @Slider.md
+@SplitButton.md
 @Stepper.md
 @Sticky.md
 @Switch.md

package/docs/Carousel.md

@@ -0,0 +1,67 @@
+# Carousel
+
+**When to use:** A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay. Slides are plain children, so any content works (images, cards, mixed content), not just a fixed image-gallery shape.
+
+**Import:** `import { Carousel } from '@ahrowe/ui'`
+**Types:** `import type { CarouselProps } from '@ahrowe/ui'`
+
+```tsx
+import { Carousel } from '@ahrowe/ui';
+
+// Uncontrolled, looping by default, with arrows, dots, and swipe all on
+<Carousel>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</Carousel>
+
+// Controlled
+const [index, setIndex] = useState(0);
+<Carousel currentIndex={index} onChange={setIndex}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</Carousel>
+
+// Autoplay, paused on hover/focus by default, with dots hidden
+<Carousel autoPlay autoPlayInterval={4000} showDots={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+
+// Bounded instead of looping: arrows disable at the first/last slide
+<Carousel loop={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+
+// No swipe/drag, arrows only
+<Carousel swipeable={false} showDots={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+```
+
+Pass slides as direct children (an array or a set of sibling elements), not through a component that returns a fragment internally. `Carousel` reads its immediate children via `React.Children`, so a wrapper component's own children aren't visible to it. If slides come from a `.map()`, spread the array straight into `Carousel`, the same way `children` normally works in React.
+
+**Interaction:** drag or swipe the track to move between slides (committing past roughly 20% of the container's width, or releasing further than that snaps to the next/previous slide; a shorter drag springs back). Left/right arrow keys move between slides when focus is anywhere inside the carousel.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The slides, one per direct child |
+| `currentIndex` | `number` | Controlled active slide index |
+| `defaultIndex` | `number` | Initial active slide index when uncontrolled (default `0`) |
+| `onChange` | `(index: number) => void` | Called whenever the active slide changes, from arrows, dots, keyboard, drag, or autoplay |
+| `loop` | `boolean` | Wrap from the last slide to the first and back (default `true`) |
+| `autoPlay` | `boolean` | Automatically advance on a timer (default `false`) |
+| `autoPlayInterval` | `number` | Autoplay delay in ms (default `4000`) |
+| `pauseOnHover` | `boolean` | Pause autoplay while hovered or focused (default `true`) |
+| `showArrows` | `boolean` | Show the prev/next buttons (default `true`); hidden automatically with one slide or none |
+| `showDots` | `boolean` | Show the position dots (default `true`); hidden automatically with one slide or none |
+| `swipeable` | `boolean` | Allow dragging/swiping the track (default `true`) |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Carousel: { autoPlay: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `track` `slide` `prevButton` `nextButton` `dots` `dot`