@ahrowe/ui 0.34.0 → 0.35.0

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

@@ -1,4 +1,4 @@
-import { CSSProperties } from 'react';
+import { default as React, CSSProperties } from 'react';
 import { IconContent } from '../types/icon.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type ActionIconSlots = 'root' | 'icon';
@@ -8,6 +8,8 @@ export interface ActionIconProps extends HtmlProps {
     style?: CSSProperties;
     title?: string;
     onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+    /** Ref to the root element. */
+    ref?: React.Ref<HTMLDivElement>;
     classNames?: SlotClassNames<ActionIconSlots>;
     styles?: SlotStyles<ActionIconSlots>;
 }

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

@@ -1,4 +1,4 @@
-import { ReactNode } from 'react';
+import { default as React, ReactNode } from 'react';
 import { ButtonStyleType } from '../button/button.types';
 import { HtmlProps, SlotClassNames, SlotStyles } from '../types/slots.types';
 import { IconAction } from '../types/actions.types';
@@ -18,6 +18,8 @@ export interface CardProps extends Omit<HtmlProps, 'tabIndex'> {
     style?: React.CSSProperties;
     autoGap?: boolean;
     clip?: boolean;
+    /** Ref to the root element. */
+    ref?: React.Ref<HTMLDivElement>;
     /** Classes for the inner elements. See `CardSlots`. */
     classNames?: SlotClassNames<CardSlots>;
     /** Inline styles for the inner elements. See `CardSlots`. */

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { FormValidator } from '../../services/formValidation';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type CheckboxSlots = 'icon' | 'checkmark' | 'label';
@@ -20,6 +20,8 @@ export interface CheckboxProps extends Omit<HtmlProps, 'onToggle'> {
     children?: ReactNode;
     background?: string | null;
     isLoading?: boolean;
+    /** Ref to the root element. */
+    ref?: Ref<HTMLDivElement>;
     classNames?: SlotClassNames<CheckboxSlots>;
     styles?: SlotStyles<CheckboxSlots>;
 }

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

@@ -4,6 +4,10 @@ export type ColorPickerSlots = 'root' | 'swatch' | 'panel' | 'gradient' | 'hueSl
 export interface ColorPickerLabels {
     /** The eyedropper button, read out by screen readers. */
     pickFromScreen?: string;
+    /** The saturation and brightness square, read out by screen readers. */
+    saturationAndBrightness?: string;
+    /** Where the square's cursor currently sits, read out after every move. */
+    saturationAndBrightnessValue?: (saturation: number, brightness: number) => string;
 }
 export interface ColorPickerProps extends Omit<HtmlProps, 'onChange'> {
     className?: string;

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

@@ -12,6 +12,7 @@ import { ColorPickerLabels } from '../colorPicker/colorPicker.types';
 import { EmptyStateLabels } from '../emptyState/emptyState.types';
 import { KlipyPickerLabels } from '../klipyPicker/klipyPicker.types';
 import { SearchInputLabels } from '../searchInput/searchInput.types';
+import { TooltipLabels } from '../tooltip/tooltip.types';
 import { VirtualListLabels } from '../virtualList/virtualList.types';
 import { ButtonProps } from '../button/button.types';
 import { ActionButtonsProps } from '../actionButtons/actionButtons.types';
@@ -74,6 +75,9 @@ export interface ComponentDefaults {
     SearchInput?: {
         labels?: SearchInputLabels;
     };
+    Tooltip?: {
+        labels?: TooltipLabels;
+    };
     VirtualList?: {
         labels?: VirtualListLabels;
     };

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

@@ -1,3 +1,3 @@
-import { FlipHandle, FlipProps } from './flip.types';
-declare const Flip: import('react').ForwardRefExoticComponent<FlipProps & import('react').RefAttributes<FlipHandle>>;
+import { FlipProps } from './flip.types';
+declare function Flip(props: FlipProps): import("react").JSX.Element;
 export default Flip;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type FlipAxis = 'x' | 'y';
 export type FlipSlots = 'root' | 'perspective' | 'surface' | 'front' | 'back';
@@ -35,6 +35,8 @@ export interface FlipProps extends HtmlProps {
     onFlip?: (flipped: boolean) => void;
     /** Fires once the flip transition finishes settling on the new face, for any trigger (click, controlled prop change, or ref call). Fires synchronously under `prefers-reduced-motion: reduce`, since no transition runs to wait for. */
     onFlipEnd?: (flipped: boolean) => void;
+    /** Imperative handle for flipping without owning the state. */
+    ref?: Ref<FlipHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<FlipSlots>;

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

@@ -71,6 +71,11 @@ export interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElem
     multiline?: boolean;
     rows?: number;
     autoResize?: boolean;
+    /**
+     * Ref to the rendered `<input>` (or `<textarea>` when `multiline`). Not forwarded to a
+     * `customInput`, which owns its own ref.
+     */
+    ref?: React.Ref<HTMLInputElement | HTMLTextAreaElement>;
     classNames?: SlotClassNames<InputSlots>;
     styles?: SlotStyles<InputSlots>;
     /** Overrides the text Input renders of its own. Merged per key. */

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

@@ -1,7 +1,8 @@
-import { default as React } from 'react';
+import { default as React, ReactElement } from 'react';
 import { DataProps } from '../types/baseProps.types';
 interface Properties extends DataProps, Omit<React.HTMLAttributes<HTMLDivElement>, 'tabIndex'> {
     tabIndex?: number | null;
+    ref?: React.Ref<HTMLDivElement>;
 }
-declare const InteractableDiv: React.ForwardRefExoticComponent<Properties & React.RefAttributes<HTMLDivElement>>;
+declare function InteractableDiv({ className, children, onClick, onKeyDown, tabIndex, ref, ...props }: Properties): ReactElement;
 export default InteractableDiv;

package/dist/types/common/loading/spinnerLoading/spinnerLoading.d.ts

@@ -3,9 +3,4 @@ interface Properties {
     className?: string | undefined;
 }
 declare function SpinnerLoading({ className }: Properties): ReactElement;
-declare namespace SpinnerLoading {
-    var defaultProps: {
-        className: undefined;
-    };
-}
 export default SpinnerLoading;

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

@@ -67,6 +67,8 @@ export interface NumberInputProps extends Omit<NumericFormatProps, 'onValueChang
     onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
     /** Overrides the text NumberInput renders of its own. Merged per key. */
     labels?: NumberInputLabels;
+    /** Ref to the inner `<input>`, for focusing the field. */
+    ref?: React.Ref<HTMLInputElement>;
     /** Classes for the inner elements. See `NumberInputSlots`. */
     classNames?: SlotClassNames<NumberInputSlots>;
     /** Inline styles for the inner elements. See `NumberInputSlots`. */

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

@@ -51,6 +51,8 @@ export interface OtpInputProps extends Omit<HtmlProps, 'onChange'> {
     autoFocus?: boolean;
     className?: string;
     style?: React.CSSProperties;
+    /** Ref to the root element. */
+    ref?: React.Ref<HTMLDivElement>;
     classNames?: SlotClassNames<OtpInputSlots>;
     styles?: SlotStyles<OtpInputSlots>;
     /** Overrides the text OtpInput renders of its own. Merged per key. */

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

@@ -3,5 +3,5 @@ import { PlanCanvasProps } from './planCanvas.types';
  * The ref lands on the `<svg>` itself, which is what a consumer wants for measuring or
  * screenshotting. Both the drawer and the viewer expose it as `getSvgElement()`.
  */
-declare const PlanCanvas: import('react').ForwardRefExoticComponent<PlanCanvasProps & import('react').RefAttributes<SVGSVGElement>>;
+declare function PlanCanvas(props: PlanCanvasProps): import("react").JSX.Element;
 export default PlanCanvas;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { DerivedRoom, PlanFloor, PlanRoom, PlanSelection, PlanView } from '../floorPlan';
 import { SlotClassNames, SlotStyles } from '../types/slots.types';
 export type PlanCanvasSlots = 'canvas' | 'grid' | 'underlay' | 'rooms' | 'roomFill' | 'roomLabel' | 'walls' | 'wallBody' | 'openings' | 'opening' | 'overlay';
@@ -55,6 +55,8 @@ export interface PlanCanvasProps {
         height: number;
     };
     'aria-label'?: string;
+    /** Ref to the rendered `<svg>` root. */
+    ref?: Ref<SVGSVGElement>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<PlanCanvasSlots>;

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

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
 import { RippleProps, RippleHandle } from './ripple.types';
 export type { RippleProps, RippleHandle };
-declare const Ripple: React.ForwardRefExoticComponent<RippleProps & React.RefAttributes<RippleHandle>>;
+declare function Ripple({ disabled, children, className, style, overflowHidden, rippleAnimationLength, rippleBackground, manualOnly, ref, ...rest }: RippleProps): React.JSX.Element;
 export default Ripple;

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

@@ -9,6 +9,7 @@ export interface RippleProps extends HtmlProps {
     rippleAnimationLength?: number;
     rippleBackground?: string;
     manualOnly?: boolean;
+    ref?: React.Ref<RippleHandle>;
 }
 export interface RippleHandle {
     addRipple: () => void;

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

@@ -1,3 +1,3 @@
-import { RoomDrawerHandle, RoomDrawerProps } from './roomDrawer.types';
-declare const RoomDrawer: import('react').ForwardRefExoticComponent<RoomDrawerProps & import('react').RefAttributes<RoomDrawerHandle>>;
+import { RoomDrawerProps } from './roomDrawer.types';
+declare function RoomDrawer(props: RoomDrawerProps): import("react").JSX.Element;
 export default RoomDrawer;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { FloorPlan, OpeningKind, PlanParseResult, PlanPoint, PlanRoom, PlanSelection, PlanView } from '../floorPlan';
 import { IconContent } from '../types/icon.types';
 import { HtmlProps, SlotClassNames, SlotStyles } from '../types/slots.types';
@@ -299,6 +299,8 @@ export interface RoomDrawerProps extends Omit<HtmlProps<HTMLDivElement>, 'onChan
     labels?: RoomDrawerLabels;
     icons?: RoomDrawerIcons;
     'aria-label'?: string;
+    /** Imperative handle for driving the editor. */
+    ref?: Ref<RoomDrawerHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<RoomDrawerSlots>;

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

@@ -1,4 +1,4 @@
-import { RoomViewerHandle, RoomViewerProps } from './roomViewer.types';
+import { RoomViewerProps } from './roomViewer.types';
 /**
  * Read-only view of a floor plan.
  *
@@ -6,5 +6,5 @@ import { RoomViewerHandle, RoomViewerProps } from './roomViewer.types';
  * two cannot drift apart. Selection and hover are React state rather than classes pushed
  * onto DOM nodes, which is what lets them be controlled from outside.
  */
-declare const RoomViewer: import('react').ForwardRefExoticComponent<RoomViewerProps & import('react').RefAttributes<RoomViewerHandle>>;
+declare function RoomViewer(props: RoomViewerProps): import("react").JSX.Element;
 export default RoomViewer;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { DerivedRoom, FloorPlan, PlanRoom, PlanView } from '../floorPlan';
 import { IconContent } from '../types/icon.types';
 import { HtmlProps, SlotClassNames, SlotStyles } from '../types/slots.types';
@@ -82,6 +82,8 @@ export interface RoomViewerProps extends Omit<HtmlProps<HTMLDivElement>, 'onSele
     emptyState?: ReactNode;
     labels?: RoomViewerLabels;
     icons?: RoomViewerIcons;
+    /** Imperative handle for driving the viewport. */
+    ref?: Ref<RoomViewerHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<RoomViewerSlots>;

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

@@ -1,3 +1,3 @@
 import { ReactElement } from 'react';
 import { SearchInputProps } from './searchInput.types';
-export default function SearchInput({ value, onChange, onDebounce, placeholder, label, debounceMs, totalAmount, showAmount, className, width, style, classNames, styles: slotStyles, labels, ...rest }: SearchInputProps): ReactElement;
+export default function SearchInput({ value, onChange, onDebounce, placeholder, label, debounceMs, totalAmount, showAmount, className, width, style, classNames, styles: slotStyles, labels, ref, ...rest }: SearchInputProps): ReactElement;

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

@@ -1,3 +1,4 @@
+import { default as React } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type SearchInputSlots = 'root' | 'input' | 'resultCount';
 /** Text SearchInput renders of its own, for translating it. */
@@ -22,4 +23,6 @@ export interface SearchInputProps extends Omit<HtmlProps, 'onChange'> {
     styles?: SlotStyles<SearchInputSlots>;
     /** Overrides the text SearchInput renders of its own. Merged per key. */
     labels?: SearchInputLabels;
+    /** Ref to the inner `<input>`, for focusing the field. */
+    ref?: React.Ref<HTMLInputElement>;
 }

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { FormValidator } from '../../services/formValidation';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type SwitchSlots = 'track' | 'thumb' | 'label';
@@ -14,6 +14,8 @@ export interface SwitchProps extends Omit<HtmlProps, 'onToggle'> {
     tabIndex?: number;
     formValidator?: FormValidator | null;
     children?: ReactNode;
+    /** Ref to the root element. */
+    ref?: Ref<HTMLDivElement>;
     classNames?: SlotClassNames<SwitchSlots>;
     styles?: SlotStyles<SwitchSlots>;
 }

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

@@ -1,3 +1,4 @@
 export { default } from './themeProvider';
 export { defaultTheme } from './defaultTheme';
+export { lightTheme } from './lightTheme';
 export type { Theme, ThemeVariables } from './theme.types';

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

@@ -0,0 +1,13 @@
+import { Theme } from './theme.types';
+/**
+ * The light sibling of {@link defaultTheme}, which is dark. Same brand, inverted surfaces:
+ * it declares only what has to flip, and inherits the rest through `baseThemeId`, so a change
+ * to the palette or the type scale reaches both themes at once.
+ *
+ * ```tsx
+ * <ThemeProvider themes={[defaultTheme, lightTheme]} activeThemeId='light'>
+ * ```
+ *
+ * `--primary-color` is deliberately untouched: it is the brand, and it reads on both.
+ */
+export declare const lightTheme: Theme;

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

@@ -1,3 +1,3 @@
-import { TiltHandle, TiltProps } from './tilt.types';
-declare const Tilt: import('react').ForwardRefExoticComponent<TiltProps & import('react').RefAttributes<TiltHandle>>;
+import { TiltProps } from './tilt.types';
+declare function Tilt(props: TiltProps): import("react").JSX.Element;
 export default Tilt;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 import { TiltAxisLock } from './tiltMath';
 export type TiltTrackingMode = 'self' | 'group';
@@ -31,6 +31,8 @@ export interface TiltProps extends HtmlProps {
     disabled?: boolean;
     /** Fires on every applied tilt update. */
     onTiltChange?: (rotateX: number, rotateY: number) => void;
+    /** Imperative handle for driving the tilt directly. */
+    ref?: Ref<TiltHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<TiltSlots>;

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

@@ -1,3 +1,3 @@
-import { TimerHandle, TimerProps } from './timer.types';
-declare const Timer: import('react').ForwardRefExoticComponent<TimerProps & import('react').RefAttributes<TimerHandle>>;
+import { TimerProps } from './timer.types';
+declare function Timer(props: TimerProps): import("react").JSX.Element;
 export default Timer;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type TimerSlots = 'root' | 'ringWrapper' | 'ringSvg' | 'ringTrack' | 'ringProgress' | 'ripples' | 'ripple' | 'display' | 'time' | 'label' | 'controls' | 'addButton' | 'removeButton' | 'pauseButton' | 'cancelButton';
 export type TimerStatus = 'idle' | 'running' | 'paused' | 'completed' | 'cancelled';
@@ -99,6 +99,8 @@ export interface TimerProps extends HtmlProps {
     notificationTitle?: string;
     /** Notification body when `notifyOnComplete` is set. Falls back to `label` when it's a string. */
     notificationBody?: string;
+    /** Imperative handle for starting, pausing and resetting the timer. */
+    ref?: Ref<TimerHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<TimerSlots>;

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

@@ -1,3 +1,3 @@
 import { default as React } from 'react';
 import { TooltipProps } from './tooltip.types';
-export default function Tooltip({ variant, message, isVisible, tooltipPosition, onClick }: TooltipProps): React.JSX.Element | null;
+export default function Tooltip({ variant, message, isVisible, tooltipPosition, onClick, labels, }: TooltipProps): React.JSX.Element | null;

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

@@ -1,5 +1,10 @@
 import { default as React } from 'react';
 export type TooltipVariant = 'info' | 'details' | 'error';
+/** Text Tooltip renders of its own, for translating it. */
+export interface TooltipLabels {
+    /** Accessible name of the `?` icon the `details` variant renders (default `More information`). */
+    details?: string;
+}
 export interface TooltipProps {
     variant: TooltipVariant;
     message?: React.ReactNode;
@@ -7,4 +12,6 @@ export interface TooltipProps {
     iconPosition?: string;
     tooltipPosition?: string;
     onClick?: () => void;
+    /** Overrides the text Tooltip renders of its own. Merged per key. */
+    labels?: TooltipLabels;
 }

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

@@ -15,6 +15,12 @@ type DataAttributes = {
  * matching React type instead and add `DataProps` for the `data-*` half — `Button` does this
  * with `React.ButtonHTMLAttributes<HTMLButtonElement>`.
  *
+ * `ref` is deliberately *not* here. `Ref<E>` is invariant, so a shared `Ref<HTMLElement>` is not
+ * assignable to the `<div>` it would be spread onto, and narrowing the default to `HTMLDivElement`
+ * re-types every event handler with it — which breaks `Dropdown` and `SplitButton`, whose `onClick`
+ * is typed for the `<button>` they hand it to. A component that accepts a ref declares it itself,
+ * next to its other props, typed for the element it actually lands on.
+ *
  * A component prop that collides with a native one of the same name must `Omit` the native one.
  */
 export type HtmlProps<E extends HTMLElement = HTMLElement> = React.HTMLAttributes<E> & DataAttributes;

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

@@ -0,0 +1,12 @@
+import { Ref } from 'react';
+/**
+ * Fans one element out to several refs, for a component that needs the node itself *and*
+ * hands it to the consumer through a `ref` prop.
+ *
+ * The returned callback is a new function on every render, so React detaches and reattaches
+ * it each time (null, then the node). Every ref here is therefore written twice per render,
+ * which is fine for storing a node and wrong for anything with a side effect. Call it inline
+ * rather than memoising: a memo would have to list the refs it closes over, and a consumer
+ * passing an inline callback ref changes that identity every render anyway.
+ */
+export declare function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): (node: T | null) => void;

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

@@ -1,7 +1,5 @@
 import { default as React } from 'react';
-import { VirtualListProps, VirtualListHandle } from './virtualList.types';
+import { VirtualListProps } from './virtualList.types';
 export { buildOffsets, findStartIndex, getVisibleRange, resolveReorderTarget, resolveTreeDropTarget, lastDescendantIndex, buildColumnTemplate, compareSortValues, isColumnSortable, isEmptySortValue, nextSort, sortItems, } from './virtualList.utils';
-declare const VirtualList: <T>(props: VirtualListProps<T> & {
-    ref?: React.Ref<VirtualListHandle>;
-}) => React.ReactElement | null;
+declare function VirtualList<T>({ ref, items, renderRow, ariaRoles, columns, height, estimatedRowHeight, overscan, rowGap, rowPadding, selectedKey, getItemKey, onRowClick, keyboardNavigation, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, resizableColumns, columnWidths, onColumnWidthsChange, labels, sort, defaultSort, onSortChange, showColumnToggle, onLoadMore, loadMoreThreshold, isLoading, multiSelect, selectedKeys, onSelectionChange, reorderable, onReorder, longPressDelay, treeReorder, getItemDepth, isGroup, onTreeDrop, treeIndentPx, dragHandle, showDivider, rowHover, className, style, classNames, styles: slotStyles, ...rest }: VirtualListProps<T>): React.JSX.Element;
 export default VirtualList;

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

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type ColumnWidthFixed = {
     type: 'fixed';
@@ -308,6 +308,8 @@ export interface VirtualListProps<T> extends HtmlProps {
      * and touch. Render a handle in your row, e.g. `<span data-drag-handle>⠿</span>`.
      */
     dragHandle?: boolean;
+    /** Imperative handle for scrolling and for recalculating column layout. */
+    ref?: Ref<VirtualListHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<VirtualListSlots>;

package/docs/Accordion.md

@@ -40,6 +40,15 @@ import { Accordion, AccordionStyleType } from '@ahrowe/ui';
 | `hideHeader` | `boolean` | Hide the clickable header |
 | `id` | `string` | Passed back in `onHeaderClicked` |
 
+## Accessibility
+
+The header is a button: it takes focus, toggles on Enter and Space, and reports the section's
+state through `aria-expanded`. It names the body it controls with `aria-controls`, and the body is
+a `role="region"` labelled by the header, so a screen reader can move between the two.
+
+An activation key pressed inside the body does not reach the header, so a Space typed into a
+field in an open section types a space instead of collapsing the section.
+
 **Slots:** `root` `header` `title` `icon` `body` `bodyInner`
 
 ## Sizing

package/docs/ActionIcon.md

@@ -27,3 +27,4 @@ import { faTrash } from '@fortawesome/free-solid-svg-icons';
 | `title` | `string` | Tooltip / accessible label |
 | `onClick` | `(event: MouseEvent) => void` | Click handler |
 | `className` | `string` | Root element class |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |

package/docs/CLAUDE.md

@@ -90,6 +90,43 @@ Most components expose `classNames` and `styles` props for styling inner element
 
 Slot keys per component are documented in each component's doc file below.
 
+## Refs
+
+The library targets **React 19 or newer**. Every component that takes a ref takes it as a plain
+prop, not through `forwardRef`, so there is nothing to unwrap and a generic component keeps its
+type parameter.
+
+```tsx
+const input = useRef<HTMLInputElement>(null);
+<Input label="Name" ref={input} />;
+input.current?.focus();
+```
+
+A ref lands on the element you would actually reach for, which is not always the root: `Input`,
+`Textarea`, `NumberInput` and `SearchInput` give you the `<input>` or `<textarea>` inside, not
+their wrapper. Components that do more than hold a node expose an imperative handle instead of an
+element: `Timer` (`start`/`pause`/`reset`), `Flip` (`flip`/`setFlipped`/`reset`), `Tilt`
+(`setTilt`/`reset`), `Ripple` (`addRipple`), `VirtualList` (scrolling and column layout),
+`RoomDrawer` and `RoomViewer`. Each handle's type is exported next to the component's props.
+
+## Server components
+
+Every module in the package is marked `'use client'`. All the components are interactive, so none
+of them renders on a server, but they can be imported straight into a React Server Components app
+(Next.js App Router and the like) with no wrapper component in between.
+
+## Right to left
+
+Not supported. The stylesheets use physical CSS properties (`margin-left`, `left`), so the library
+does not mirror for right-to-left languages.
+
+## Reduced motion
+
+Components honour `prefers-reduced-motion: reduce`: entrances, slides, chevron rotations and the
+ink ripple stop, while fades and colour changes stay. Two things deliberately keep moving, because
+freezing them would state something untrue: the loading spinners, and the Toast progress bar that
+shows how long a toast has left.
+
 ## Icon props (`IconDefinition | ReactElement`)
 
 Every `icon` prop (and every icon field inside an item/action object) accepts either a

package/docs/Card.md

@@ -61,6 +61,7 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 | `tabIndex` | `number \| null` | For keyboard navigation |
 | `autoGap` | `boolean` | Space stacked sub-components apart with a shared gap (default `true`); set `false` to space them yourself |
 | `clip` | `boolean` | Clip content to the rounded corners (`overflow: hidden`, default `false`). Set `true` for full-bleed `CardMedia` or a clipped hover/ripple effect. Safe to enable even when the card holds a `Dropdown`/`Popover`/`Tooltip` — those popovers are portaled and always escape the card regardless of this setting |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **CardHeaderProps:**
 

package/docs/Checkbox.md

@@ -36,6 +36,7 @@ const agreedValidator = new FormValidator(false, [Validators.required()]);
 | `isLoading` | `boolean` | Shows skeleton state |
 | `children` | `ReactNode` | Custom label content |
 | `cursorDefault` | `boolean` | Use default cursor instead of pointer |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **Slots:** `icon` `checkmark` `label`
 

package/docs/ColorPicker.md

@@ -51,8 +51,18 @@ The inline swatch tracks the theme's text size, since it sits beside a label: `-
 
 The picker panel deliberately does not. It is a floating control surface with its own fixed layout — a saturation area, sliders and a hex field — and it holds together at a large base font rather than needing to grow with it.
 
-**Labels:** `pickFromScreen` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ColorPickerLabels`.
+**Labels:** `pickFromScreen`, `saturationAndBrightness`, `saturationAndBrightnessValue(saturation, brightness)` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ColorPickerLabels`.
 
-**Keyboard:** the swatch is a button, so `Enter` or `Space` opens the panel and puts the focus on the hue slider, the arrow keys move it, `Tab` walks the rest of the panel, and `Escape` closes and hands the focus back. The saturation and value square is a pointer control with no keyboard equivalent; the hex field covers the same ground for anyone not using a mouse.
+**Keyboard:** the swatch is a button, so `Enter` or `Space` opens the panel and puts the focus on the saturation and brightness square. A click leaves the focus on the swatch, since a pointer open is not a request to be taken somewhere. `Tab` walks the rest of the panel, and `Escape` closes and hands the focus back to the swatch.
+
+| Key | Does |
+|-----|------|
+| `←` `→` | Saturation, a percent at a time |
+| `↑` `↓` | Brightness, a percent at a time |
+| `Shift` with any arrow | Ten at a time |
+| `Home` `End` | Saturation to either end |
+| `PageUp` `PageDown` | Brightness to either end |
+
+The square is a two-axis control, which ARIA has no role for. It reports itself as a slider whose value is the horizontal axis, with `aria-valuetext` carrying both numbers, so a screen reader reads out "62% saturation, 40% brightness" after every move.
 
 **Slots:** `root` `swatch` `panel` `gradient` `hueSlider` `alphaSlider` `hexInput` `eyeDropper`

package/docs/Input.md

@@ -122,6 +122,7 @@ The stored value is the formatted one, spaces included, so strip them before a l
 | `parse` | `(value: string) => string` | Transform the value on every change, before `onChange`/`formValidator` — also what gets rendered (see above) |
 | `isUppercase` | `boolean` | Uppercases the field's rendering (CSS only — the stored value is unchanged; use `parse` to uppercase the value itself) |
 | `customInput` | `ReactElement` | Element rendered in place of the internal `<input>`, cloned with all of Input's props. The escape hatch for a mask library; note `autoFocus` and `autoResize` stop working, since Input cannot attach its ref |
+| `ref` | `Ref<HTMLInputElement \| HTMLTextAreaElement>` | Ref to the inner field, not the wrapper. Not forwarded to a `customInput` |
 
 **Slots:** `label` `container` `input` `suffix` `upperRightLabel` `fieldset`
 

package/docs/KlipyPicker.md

@@ -6,7 +6,7 @@
 
 **Import:** `import { KlipyPicker } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Klipy API token — the component ships with a default key, but supply your own `token` prop for production use.
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Klipy API token, passed as the `token` prop. There is no built-in key: without one the picker renders but every request fails.
 
 ```tsx
 import { KlipyPicker } from '@ahrowe/ui';

package/docs/NumberInput.md

@@ -76,6 +76,7 @@ const priceValidator = new FormValidator<number | undefined>(undefined, [Validat
 | `arrowsLayout` | `'auto' \| 'stacked' \| 'split'` | Stepper layout. Default: `'auto'` |
 | `labels.increase` | `string` | Accessible name for the increase button. Default: `'Increase'` |
 | `labels.decrease` | `string` | Accessible name for the decrease button. Default: `'Decrease'` |
+| `ref` | `Ref<HTMLInputElement>` | Ref to the inner `<input>` |
 
 **Steppers (`showArrows`):** two layouts, picked by `arrowsLayout`:
 

package/docs/OtpInput.md

@@ -88,6 +88,7 @@ const codeValidator = new FormValidator('', [Validators.required(), Validators.m
 | `clearErrorDelay` | `number` | Delay in ms before `clearOnError` clears the boxes (default `900`) |
 | `disabled` | `boolean` | |
 | `autoFocus` | `boolean` | Focuses the first empty box (or the first box) on mount |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **Slots:** `root` `label` `inputs` `input` `separator`
 

package/docs/SearchInput.md

@@ -40,6 +40,7 @@ import { SearchInput } from '@ahrowe/ui';
 | Variable | Falls back to |
 |----------|---------------|
 | `--search-input-color` | *(none — unset by default)* |
+| `ref` | `Ref<HTMLInputElement>` | Ref to the inner `<input>`, for focusing the field |
 
 **Key props:**
 

package/docs/Switch.md

@@ -46,6 +46,7 @@ const notifyValidator = new FormValidator(false);
 | `disabled` | `boolean` | |
 | `children` | `ReactNode` | Custom label content (overrides `label`) |
 | `tabIndex` | `number` | |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **Sizing:** the track and thumb are dimensioned in `em`, so the whole switch scales with the inherited `font-size` — no dedicated size prop. Use `style={{ fontSize: ... }}` to scale everything together, or the `track`/`thumb` slots (`classNames`/`styles`) to resize just those parts.
 

package/docs/Textarea.md

@@ -40,5 +40,6 @@ const descValidator = new FormValidator('', [Validators.required(), Validators.m
 | `formValidator` | `FormValidator` | Connects to validation |
 | `placeholder` | `string` | |
 | `readOnly` | `boolean` | |
+| `ref` | `Ref<HTMLTextAreaElement>` | Ref to the inner `<textarea>` |
 
 **Slots:** Same as `Input` — `label` `container` `input` `suffix` `upperRightLabel` `fieldset`