@ahrowe/ui 0.13.0 → 0.14.1

package/dist/types/package/common/kanbanBoard/KanbanColumn.d.ts

@@ -4,6 +4,34 @@ interface KanbanColumnInternalProps<T> extends KanbanColumnProps {
     itemIds: string[];
     items: Record<string, T>;
     renderItem: (item: T, id: string) => ReactNode;
+    dragHandle?: boolean;
+    /**
+     * Keep the column at its normal flex width even when `itemIds` is empty. Used while a drag
+     * is in progress: the empty-column collapse is driven by transient shadow state during a
+     * drag, and letting the column shrink mid-drag shifts every column's layout underneath the
+     * pointer, which can flip the collision target back and forth forever.
+     */
+    preserveSizeWhileEmpty?: boolean;
+    /** Shrink to a narrow strip when empty — see `KanbanBoardProps.collapseEmptyColumns`. Defaults to `true`. */
+    collapseEmptyColumns?: boolean;
+    /** Work-in-progress limit — see `KanbanColumnDef.maxItems`. Display-only. */
+    maxItems?: number;
+    /** Freezes the column — see `KanbanColumnDef.disabled`. */
+    disabled?: boolean;
+    /** Returns whether a specific card can't be picked up — see `KanbanBoardProps.getItemDisabled`. */
+    getItemDisabled?: (item: T, id: string) => boolean;
+    /** Custom content shown when the column has no cards — see `KanbanBoardProps.renderEmptyColumn`. */
+    emptyPlaceholder?: ReactNode;
+    /** Custom header actions — see `KanbanBoardProps.renderColumnActions`. */
+    actions?: ReactNode;
+    /** Allow the whole column to be dragged (by its header) to reorder it — see `KanbanBoardProps.reorderableColumns`. */
+    reorderable?: boolean;
+    /**
+     * Whether the card currently being dragged (if any) is actually a column. Suppresses the
+     * cards drop-target highlight, which otherwise lights up on every column a dragged column
+     * passes over — that highlight means "drop a card here", which doesn't apply mid-column-drag.
+     */
+    activeIsColumn?: boolean;
 }
-declare function KanbanColumn<T>({ id, title, itemIds, items, renderItem, className, classNames, styles: slotStyles, }: KanbanColumnInternalProps<T>): import("react/jsx-runtime").JSX.Element;
+declare function KanbanColumn<T>({ id, title, itemIds, items, renderItem, dragHandle, preserveSizeWhileEmpty, collapseEmptyColumns, maxItems, disabled, getItemDisabled, emptyPlaceholder, actions, reorderable, activeIsColumn, className, style, classNames, styles: slotStyles, ...rest }: KanbanColumnInternalProps<T>): import("react/jsx-runtime").JSX.Element;
 export default KanbanColumn;

package/dist/types/package/common/kanbanBoard/KanbanItem.d.ts

@@ -1,7 +1,3 @@
-import { ReactNode } from 'react';
-interface KanbanItemProps {
-    id: string;
-    children: ReactNode;
-}
-declare function KanbanItem({ id, children }: KanbanItemProps): import("react/jsx-runtime").JSX.Element;
+import { KanbanItemProps } from './kanbanBoard.types';
+declare function KanbanItem({ id, dragHandle, disabled, preventAsDropTarget, children }: KanbanItemProps): import("react/jsx-runtime").JSX.Element;
 export default KanbanItem;

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

@@ -1,12 +1,24 @@
 import { CSSProperties, ReactNode } from 'react';
-import { SlotClassNames, SlotStyles } from '../types/slots.types';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export interface KanbanColumnDef {
     id: string;
     title: string;
     itemIds: string[];
+    /**
+     * Optional work-in-progress limit. When set, the column header shows a `count/maxItems`
+     * badge, and the column gets a warning style once `itemIds.length` exceeds it. This is
+     * display-only — `KanbanBoard` doesn't block drops on its own. To enforce a hard limit,
+     * check it in `onChange` and skip updating your state when a drop would push a column over.
+     */
+    maxItems?: number;
+    /**
+     * Freezes the column: cards inside it can't be picked up, and nothing can be dropped into it.
+     * Use for a workflow rule like "cards in Done can't be moved back out."
+     */
+    disabled?: boolean;
 }
 export type KanbanBoardSlots = 'dragOverlay';
-export interface KanbanBoardProps<T = unknown> {
+export interface KanbanBoardProps<T = unknown> extends HtmlProps {
     /** Ordered list of column definitions. Each column owns its itemIds. */
     columns: KanbanColumnDef[];
     /** Flat map of all items keyed by their id. */
@@ -18,18 +30,72 @@ export interface KanbanBoardProps<T = unknown> {
      * Receives the full updated columns array — replace your state with this value.
      */
     onChange: (columns: KanbanColumnDef[]) => void;
+    /**
+     * Restrict drag initiation to elements marked `data-drag-handle` within a card,
+     * instead of the whole card. Use when `renderItem` includes interactive content
+     * (buttons, inputs) that would otherwise have its clicks swallowed by the drag listener.
+     */
+    dragHandle?: boolean;
+    /**
+     * Produce an accessible label for a card, announced to screen-reader users while dragging
+     * (e.g. "Picked up <label>."). Defaults to the card's id when omitted.
+     */
+    getItemLabel?: (item: T, id: string) => string;
+    /**
+     * Returns whether a specific card can't be picked up. Defaults to every card being draggable.
+     * Independent of a column's own `disabled` — a card can be pinned even in an otherwise
+     * unrestricted column.
+     */
+    getItemDisabled?: (item: T, id: string) => boolean;
+    /**
+     * Custom content shown inside a column when it has no cards, instead of leaving it blank.
+     * Receives the column definition.
+     */
+    renderEmptyColumn?: (column: KanbanColumnDef) => ReactNode;
+    /**
+     * Custom actions rendered in a column's header, next to its title (e.g. an "add card"
+     * button, a column menu). Receives the column definition.
+     */
+    renderColumnActions?: (column: KanbanColumnDef) => ReactNode;
+    /**
+     * Allow whole columns to be reordered by dragging their header, alongside the existing
+     * card dragging. Defaults to `false`.
+     */
+    reorderableColumns?: boolean;
+    /**
+     * Shrink a column to a narrow strip once it has no cards, instead of keeping it at the same
+     * width as every other column. Defaults to `true`. Set `false` to keep every column the same
+     * width regardless of card count. The collapsed width itself is set via the
+     * `--kanban-empty-column-width` CSS variable (falls back to `140px`) — override it theme-wide
+     * via `ThemeProvider`'s `variables`, or per board via `style`.
+     */
+    collapseEmptyColumns?: boolean;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<KanbanBoardSlots>;
     styles?: SlotStyles<KanbanBoardSlots>;
 }
-export type KanbanColumnSlots = 'header' | 'items';
-export interface KanbanColumnProps {
+export type KanbanColumnSlots = 'header' | 'items' | 'count' | 'placeholder' | 'actions';
+export interface KanbanColumnProps extends HtmlProps {
     id: string;
     title: string;
-    isOver?: boolean;
     children?: ReactNode;
     className?: string;
+    style?: CSSProperties;
     classNames?: SlotClassNames<KanbanColumnSlots>;
     styles?: SlotStyles<KanbanColumnSlots>;
 }
+export interface KanbanItemProps {
+    id: string;
+    dragHandle?: boolean;
+    /** Whether this card can't be picked up (column frozen, or the card itself is pinned). */
+    disabled?: boolean;
+    /**
+     * Whether this card also can't be a drop target for other cards — i.e. other cards can't be
+     * reordered relative to it either. Only true when the *column* is frozen (nothing should be
+     * dropped into it at all); a card pinned individually via `getItemDisabled` stays droppable, so
+     * other cards can still land before/after it normally.
+     */
+    preventAsDropTarget?: boolean;
+    children?: ReactNode;
+}

package/dist/types/package/common/kanbanBoard/kanbanBoard.utils.d.ts

@@ -0,0 +1,60 @@
+import { Announcements, ClientRect, CollisionDetection, KeyboardCoordinateGetter } from '@dnd-kit/core';
+import { KanbanColumnDef } from './kanbanBoard.types';
+export declare function columnsEqual(a: KanbanColumnDef[], b: KanbanColumnDef[]): boolean;
+export declare function findColumnForItem(columns: KanbanColumnDef[], itemId: string): number;
+/** Whether a drag's `active`/`over` participant is a whole column (vs. a card) — see `reorderableColumns`. */
+export declare function isColumnDragData(data: unknown): boolean;
+/**
+ * Reorders whole columns: moves `activeColumnId` to `overColumnId`'s position. Returns the same
+ * `columns` reference, unchanged, when either id doesn't resolve to a column or they're the same
+ * — callers can use that to skip a state update.
+ */
+export declare function moveColumn(columns: KanbanColumnDef[], activeColumnId: string, overColumnId: string): KanbanColumnDef[];
+/**
+ * Collision detection for the board's shared `DndContext`, which has to pick between two very
+ * differently-scaled sets of droppables at once: individual cards / a column's own card list
+ * (small, numerous) and whole columns (large, few). Plain `closestCorners` weighs every
+ * registered droppable together regardless of what's actually being dragged, so while dragging a
+ * column it competes against every card and card-list droppable it happens to fly over too — the
+ * column-level target only wins when the pointer lands somewhere that geometrically favors it,
+ * which reads as needing to "wiggle it around" before the right drop target lights up. This
+ * restricts the candidates to only the same kind as whatever is being dragged: a column drag only
+ * considers other columns, a card drag only considers cards and card lists.
+ */
+export declare const kanbanCollisionDetection: CollisionDetection;
+/** Extracts the column id from a column droppable's `column-<id>` identifier, or `null` for a card id. */
+export declare function resolveColumnDropId(overId: string): string | null;
+export interface DragGeometry {
+    /** The dragged card's current rect (translated by the drag delta), if measured. */
+    activeRect: ClientRect | null;
+    /** The rect of whatever `overId` refers to — a card, or a column's own droppable. */
+    overRect: ClientRect;
+}
+/**
+ * Computes the columns that result from dragging `activeItemId` over `overId` (a card id, or a
+ * `column-<id>` droppable id for empty column space). Returns the same `columns` reference,
+ * unchanged, when the drag doesn't resolve to a valid source/destination — callers can use that
+ * to skip a state update.
+ *
+ * `geometry` resolves cross-column drops that land on a card or gap with more than one possible
+ * position (see the two branches below for what each one decides).
+ */
+export declare function moveItem(columns: KanbanColumnDef[], activeItemId: string, overId: string, geometry: DragGeometry): KanbanColumnDef[];
+/**
+ * Builds screen-reader drag announcements against the columns layout as currently understood
+ * (the live shadow layout while a drag is in progress, or the settled `columns` prop otherwise).
+ */
+export declare function buildAnnouncements<T>(columns: KanbanColumnDef[], items: Record<string, T>, getItemLabel: (item: T, id: string) => string): Announcements;
+/**
+ * Custom keyboard coordinate getter for the board's multi-column, multi-`SortableContext`
+ * layout. dnd-kit's default `sortableKeyboardCoordinates` picks the geometrically closest
+ * droppable across the *entire* board — cards and column containers alike — which is unreliable
+ * once cards live inside independent per-column `SortableContext`s: up/down and left/right end up
+ * interchangeable depending on incidental rect positions. This instead restricts up/down to
+ * reordering within the active card's own column, and left/right to moving into the adjacent
+ * column (landing on the closest card there by vertical position, or the column itself when
+ * empty). Requires each `KanbanColumn`'s `SortableContext` to be given an explicit `id` matching
+ * its column id, so a card's `sortable.containerId` can be correlated with its `column-<id>`
+ * droppable.
+ */
+export declare const kanbanKeyboardCoordinateGetter: KeyboardCoordinateGetter;

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;
@@ -106,6 +107,8 @@ export interface ThemeVariables {
     '--stepper-gap'?: string;
     /** Text/check colour on a filled marker. Falls back to --text-on-primary. */
     '--stepper-text-on-marker'?: string;
+    /** Width a column collapses to once it has no cards (see `collapseEmptyColumns`). Falls back to 140px. */
+    '--kanban-empty-column-width'?: string;
     [key: string]: string | undefined;
 }
 export interface Theme {

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

@@ -19,6 +19,8 @@ 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';
@@ -98,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/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

@@ -103,6 +103,7 @@ Slot keys per component are documented in each component's doc file below.
 @BodyEnd.md
 @Breadcrumb.md
 @Button.md
+@ButtonGroup.md
 @Card.md
 @Carousel.md
 @Checkbox.md
@@ -145,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/Divider.md

@@ -1,13 +1,15 @@
 # Divider
 
-**When to use:** A horizontal rule that fills the width of its parent — separating sections of content. Optionally label it with text (e.g. "OR", a date, a section name); the line splits around the text, leaving a gap for it.
+**When to use:** A rule that separates sections of content — horizontal by default, filling the width of its parent. Optionally label it with text (e.g. "OR", a date, a section name); the line splits around the text, leaving a gap for it. Set `orientation` to `Vertical` for a vertical line filling the height of its parent instead, e.g. as a separator between two buttons in a `ButtonGroup`.
 
-**Import:** `import { Divider, DividerTextPosition } from '@ahrowe/ui'`
+**Import:** `import { Divider, DividerTextPosition, DividerOrientation } from '@ahrowe/ui'`
 
 **Text position:** `DividerTextPosition.Left` | `DividerTextPosition.Center` (default) | `DividerTextPosition.Right`
 
+**Orientation:** `DividerOrientation.Horizontal` (default) | `DividerOrientation.Vertical`
+
 ```tsx
-import { Divider, DividerTextPosition } from '@ahrowe/ui';
+import { Divider, DividerTextPosition, DividerOrientation } from '@ahrowe/ui';
 
 // Plain line
 <Divider />
@@ -20,6 +22,13 @@ import { Divider, DividerTextPosition } from '@ahrowe/ui';
 
 // Text near the right edge
 <Divider text="March 2026" textPosition={DividerTextPosition.Right} />
+
+// Vertical — fills the height of its (flex/grid) parent, e.g. between two buttons
+<ButtonGroup>
+  <Button>Save</Button>
+  <Divider orientation={DividerOrientation.Vertical} />
+  <Button>Save & new</Button>
+</ButtonGroup>
 ```
 
 **Key props:**
@@ -28,6 +37,9 @@ import { Divider, DividerTextPosition } from '@ahrowe/ui';
 |------|------|-------------|
 | `text` | `ReactNode` | Text (or any node) rendered on the line. Omit for a plain full-width line |
 | `textPosition` | `DividerTextPosition` | Where `text` sits along the line (default `Center`) |
+| `orientation` | `DividerOrientation` | `Horizontal` (default, fills width) or `Vertical` (fills height) |
 | `className` / `style` | | Root element |
 
+**Vertical orientation:** stretches to fill the height of a flex or grid parent (`align-self: stretch`), the same way `Button`s in a `ButtonGroup` do. Outside a flex/grid context, give it an explicit height via `style`, since a vertical line has no natural height of its own the way a horizontal one has a natural width (`100%` of its block-level parent).
+
 **Slots:** `root` `line` (the line segment(s) either side of `text`) `content` (the `text` wrapper)

package/docs/FloatingMenu.md

@@ -29,7 +29,9 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
   <ActionIcon icon={faEllipsis} />
 </FloatingMenu>
 
-// Keep open when clicking inside content
+// Keep open through several interactions with content — a column-visibility toggle where
+// checking one box shouldn't close the whole menu — or when re-clicking the trigger itself
+// (e.g. DatePicker re-clicking its own input) shouldn't close it either
 <FloatingMenu dontCloseOnChildClick content={<Form />}>
   <button>Open form</button>
 </FloatingMenu>
@@ -46,8 +48,10 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
 | `align` | `Align` | Popover alignment relative to trigger |
 | `isOpen` | `boolean` | Controlled open state |
 | `onOpenChange` | `(isOpen: boolean) => void` | Open state change callback |
-| `dontCloseOnChildClick` | `boolean` | Prevent close when clicking inside content |
+| `dontCloseOnChildClick` | `boolean` | Keep the menu open when its own content is clicked, and when the trigger itself is re-clicked while already open (default `false`) |
 
 **Slots:** `root` `trigger` `menu` `menuContainer`
 
-**Nested overlays in `content`:** a click anywhere inside `content` never closes the menu on its own — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Closing on a selection is opt-in: have the handler that reacts to the selection call `onOpenChange(false)` (or your own state setter) explicitly, the way a calendar's day-selection handler would, while a nested month/year `Dropdown` inside the same menu is left alone.
+**Closing behaviour:** by default, clicking anywhere in `content` closes the menu — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Re-clicking the trigger while open is a clean toggle: it closes the menu (unless `dontCloseOnChildClick` is set, in which case it's a no-op — the trigger owns its own open/close entirely, so it never fights with an outside-click check). Set `dontCloseOnChildClick` when `content` needs several interactions before the user is done (a multi-checkbox toggle, a color picker's slider, a calendar) — the consumer is then responsible for closing explicitly, e.g. calling `onOpenChange(false)` from the handler that reacts to a final selection.
+
+**Keyboard:** the menu is portaled to the end of the DOM, so Tab can't reach it in visual order on its own. When `content` has real focusable elements, Escape closes the menu and returns focus to the trigger; Tab past the last focusable element (or Shift+Tab past the first) closes the menu and continues focus as if it sat right after the trigger. This doesn't include auto-focusing the first element on open — content ranges from menus to live controls (e.g. `ColorPicker`'s hue slider), where grabbing focus on open would let a stray arrow-key press change a value the user never touched. A consumer that wants that (like `SplitButton` focusing its first enabled action) implements it itself.

package/docs/Input.md

@@ -17,14 +17,13 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 // Password
 <Input label="Password" type={InputType.Password} value={pw} onChange={setPw} />
 
-// Search with clear button
+// Search — clear button appears automatically once there's a value, and clears itself;
+// onClearClicked is optional, only needed to react to the clear beyond the value itself
 <Input
   type={InputType.Search}
   label="Search"
   value={query}
   onChange={setQuery}
-  showCancel
-  onClearClicked={() => setQuery('')}
 />
 
 // Multiline (textarea)
@@ -38,10 +37,34 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 
 // Row layout
 <Input label="Name" isRow value={name} onChange={setName} />
+
+// Custom icon on the left instead of the default right — the field's padding, the material
+// label (resting and floated), and the native placeholder all shift out of its way automatically
+<Input
+  label="Search"
+  icon={<FontAwesomeIcon icon={faMagnifyingGlass} />}
+  iconPosition={InputIconPosition.Left}
+  value={query}
+  onChange={setQuery}
+/>
+
+// A decorative type icon (Email/Phone/Edit) on the left, no custom icon needed
+<Input label="Email" type={InputType.Email} iconPosition={InputIconPosition.Left} />
+
+// A custom icon replaces Email's built-in envelope outright — there's nothing functional to lose
+<Input label="Email" type={InputType.Email} icon={<FontAwesomeIcon icon={faAt} />} />
 ```
 
 **InputType enum:** `Edit` | `Phone` | `Email` | `Iban` | `Date` | `HasNoIcon` | `Search` | `Password`
 
+**InputIconPosition enum:** `Left` | `Right` — which side the input's icon renders on, whichever icon is currently showing (built-in type icon or custom `icon`). Defaults to `Left` for `Email`/`Phone`/`Search` once `useMatLabelStyle` is off (their historical placement), `Right` otherwise; pass it explicitly to move any type's icon to either side regardless of `useMatLabelStyle`.
+
+**Custom icon vs. built-in type icon:** passing `icon` alongside a decorative type (`Edit`, `Phone`, `Email`) replaces that type's built-in icon outright, since there's nothing functional attached to it to lose. `Search` and `Password` ignore `icon` — their icon is functional (clear button, show/hide toggle), not decorative, so it always renders regardless of whether `icon` is set.
+
+**Search clear icon:** `InputType.Search` shows a magnifying glass that animates into a clear (×) button once the field has a value, rather than the browser's own native search-cancel decoration, which is suppressed so it doesn't clash with the theme.
+
+**Mobile keyboard layout:** `Email`, `Phone`, and `Search` each set the matching `inputMode` (`email` / `tel` / `search`), so mobile browsers show the right on-screen keyboard — an `@`-and-`.com` layout for email, a numeric dial pad for phone, a "Go"/search action key for search. `Email`'s native `type` is deliberately left as `text` rather than `email`, to avoid the browser's own "please match the requested format" validation UI fighting the `formValidator`-driven error tooltip this component already shows — `inputMode="email"` alone is enough to get the correct keyboard. Pass `inputMode` directly to override the computed default for any other case.
+
 **Key props:**
 
 | Prop | Type | Description |
@@ -58,12 +81,13 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 | `rows` | `number` | Textarea row count |
 | `autoResize` | `boolean` | Textarea grows with content |
 | `suffix` | `string \| ReactNode` | Right-side suffix |
-| `icon` | `ReactElement` | Custom icon element, positioned absolute on the right (the field is padded to match); clickable via `onIconClick` |
+| `icon` | `ReactElement` | Custom icon, positioned absolute on the side set by `iconPosition`; clickable via `onIconClick`. Replaces the built-in icon for `Edit`/`Phone`/`Email`; ignored for `Search`/`Password` (see below) |
+| `iconPosition` | `InputIconPosition` | Side the input's icon renders on — built-in or custom, whichever is showing (see enum above for the default). On the left, the material label (resting and floated) and the fieldset notch shift right to clear it too |
 | `onIconClick` | `() => void` | Click handler for the custom `icon` |
 | `upperRightLabel` | `string \| ReactNode` | Small label above right |
-| `showCancel` | `boolean` | Show clear icon when focused |
+| `showCancel` | `boolean` | Show clear icon when focused (ignored for `InputType.Search`, which always shows it once there's a value — see below) |
 | `alwaysShowCancel` | `boolean` | Always show clear icon |
-| `onClearClicked` | `() => void` | Clear button handler |
+| `onClearClicked` | `() => void` | Called after the clear button clears the value. Optional — clicking clear always empties the field itself, whether or not this is set |
 | `isRow` | `boolean` | Horizontal layout |
 | `labelInBorder` | `boolean` | Label inside fieldset border |
 | `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when empty and unfocused, so an empty field reads as blank instead of showing the label as if it were a value. Only applies with `useMatLabelStyle` (default) |