@ahrowe/ui 0.37.0 → 0.38.0

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

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { CommandPaletteProps } from './commandPalette.types.js';
+declare function CommandPalette(props: CommandPaletteProps): ReactElement;
+export default CommandPalette;

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

@@ -0,0 +1,42 @@
+import { CSSProperties } from 'react';
+import { MenuEntry } from '../menu/menu.types.js';
+import { Presentation } from '../configProvider/presentation.types.js';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export type CommandPaletteSlots = 'root' | 'search' | 'input' | 'list' | 'item' | 'itemIcon' | 'itemLabel' | 'itemShortcut' | 'heading' | 'separator' | 'empty';
+export interface CommandPaletteLabels {
+    /** Accessible name of the dialog and the search field. Default: "Search commands". */
+    label?: string;
+    /** Placeholder in the search field. Default: "Type a command or search…". */
+    placeholder?: string;
+    /** Shown when nothing matches. Default: "No results". */
+    empty?: string;
+    /** Shown while `isLoading` and nothing matches yet. Default: "Searching…". */
+    loading?: string;
+    /** Announced to screen readers as the matches change. */
+    results?: (count: number) => string;
+}
+export interface CommandPaletteProps extends HtmlProps<HTMLDivElement> {
+    /** The commands, in the same shape `Menu` takes. Headings group them; separators split groups. */
+    items: MenuEntry[];
+    isOpen: boolean;
+    onClose: () => void;
+    /** Called with the id of the command that was run, after its own `onClick`. */
+    onAction?: (id: string) => void;
+    /** Called on every keystroke, and with `''` each time the palette opens. */
+    onQueryChange?: (query: string) => void;
+    /**
+     * Filter `items` by the query. Default `true`. Set `false` when `items` are already the results,
+     * e.g. fetched from a server in `onQueryChange`.
+     */
+    filter?: boolean;
+    /** Shows the `loading` label instead of `empty` while nothing matches. */
+    isLoading?: boolean;
+    /** Centred dialog, bottom sheet, or a sheet only on a small touch screen. */
+    presentation?: Presentation;
+    /** Text this component renders of its own. */
+    labels?: CommandPaletteLabels;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<CommandPaletteSlots>;
+    styles?: SlotStyles<CommandPaletteSlots>;
+}

package/dist/types/common/commandPalette/filterCommands.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { MenuAction, MenuEntry } from '../menu/menu.types.js';
+export interface CommandGroup {
+    heading?: ReactNode;
+    /** Whether a separator started this group, so the divider can be drawn above it. */
+    separated: boolean;
+    actions: MenuAction[];
+}
+/** Splits entries into groups at each heading and separator, keeping their order. */
+export declare function groupCommands(items: MenuEntry[]): CommandGroup[];
+/**
+ * The groups with only the actions matching `query`, best matches first within each group, and
+ * the group holding the best match first. A heading moves with its group, never away from it.
+ */
+export declare function filterCommands(groups: CommandGroup[], query: string): CommandGroup[];

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

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

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

@@ -15,6 +15,9 @@ import { SearchInputLabels } from '../searchInput/searchInput.types.js';
 import { TooltipLabels } from '../tooltip/tooltip.types.js';
 import { VirtualListLabels } from '../virtualList/virtualList.types.js';
 import { ButtonProps } from '../button/button.types.js';
+import { CopyButtonProps } from '../copyButton/copyButton.types.js';
+import { CommandPaletteProps } from '../commandPalette/commandPalette.types.js';
+import { WeatherIconProps } from '../weatherIcon/weatherIcon.types.js';
 import { ActionButtonsProps } from '../actionButtons/actionButtons.types.js';
 import { ConfirmModalProps } from '../confirmModal/confirmModal.types.js';
 import { BadgeProps } from '../badge/badge.types.js';
@@ -91,6 +94,7 @@ export interface ComponentDefaults {
     RadioGroup?: Partial<RadioGroupProps>;
     DatePicker?: Partial<DatePickerProps>;
     Button?: Partial<ButtonProps>;
+    CopyButton?: Partial<CopyButtonProps>;
     ActionButtons?: Partial<ActionButtonsProps>;
     ConfirmModal?: Partial<ConfirmModalProps>;
     Badge?: Partial<BadgeProps>;
@@ -118,6 +122,8 @@ export interface ComponentDefaults {
     RoomViewer?: Partial<RoomViewerProps>;
     Popover?: Partial<PopoverProps>;
     Modal?: Partial<ModalProps>;
+    CommandPalette?: Partial<CommandPaletteProps>;
+    WeatherIcon?: Partial<WeatherIconProps>;
 }
 export interface ConfigProviderProps {
     children: React.ReactNode;

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

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { CopyButtonProps } from './copyButton.types.js';
+declare function CopyButton(props: CopyButtonProps): ReactElement;
+export default CopyButton;

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

@@ -0,0 +1,36 @@
+import { CSSProperties, MouseEvent, Ref } from 'react';
+import { IconContent } from '../types/icon.types.js';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export type CopyButtonSlots = 'root' | 'icon';
+export interface CopyButtonLabels {
+    /** Accessible name and tooltip before copying. Default: "Copy". */
+    copy?: string;
+    /** Accessible name and tooltip after a successful copy, also announced. Default: "Copied". */
+    copied?: string;
+    /** Announced when the copy fails. Default: "Could not copy". */
+    failed?: string;
+}
+export interface CopyButtonProps extends Omit<HtmlProps<HTMLDivElement>, 'onCopy' | 'onError'> {
+    /** Text written to the clipboard on click. */
+    value: string;
+    /** How long the copied state shows, in ms. Default: 2000. */
+    timeout?: number;
+    /** Icon before copying. Default: `faCopy`. */
+    icon?: IconContent;
+    /** Icon while the copied state shows. Default: `faCheck`. */
+    copiedIcon?: IconContent;
+    /** Called after a successful copy. */
+    onCopy?: (value: string) => void;
+    /** Called when the clipboard refuses the write, e.g. outside a secure context. */
+    onError?: () => void;
+    /** Called on every click, before the copy. */
+    onClick?: (event: MouseEvent<HTMLDivElement>) => void;
+    /** Text this component renders of its own. */
+    labels?: CopyButtonLabels;
+    /** Ref to the root element. */
+    ref?: Ref<HTMLDivElement>;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<CopyButtonSlots>;
+    styles?: SlotStyles<CopyButtonSlots>;
+}

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

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

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

@@ -2,13 +2,10 @@ import { default as React } from 'react';
 import { ErrorBoundaryProps, ErrorBoundaryState } from './errorBoundary.types.js';
 declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
     state: ErrorBoundaryState;
-    private copyResetTimeout;
     static getDerivedStateFromError(error: Error): Partial<ErrorBoundaryState>;
     componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
     componentDidUpdate(prevProps: ErrorBoundaryProps): void;
-    componentWillUnmount(): void;
     private reset;
-    private copyStackTrace;
     render(): React.ReactNode;
 }
 export default ErrorBoundary;

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

@@ -13,9 +13,9 @@ export interface ErrorBoundaryFallbackProps {
 export interface ErrorBoundaryLabels {
     /** Accordion header for the stack trace section. Default: "Stack trace". */
     stackTrace?: string;
-    /** Copy button label before copying. Default: "Copy". */
+    /** Copy button's tooltip and accessible name before copying. Default: "Copy". */
     copy?: string;
-    /** Copy button label right after a successful copy. Default: "Copied". */
+    /** Copy button's tooltip and accessible name right after a successful copy. Default: "Copied". */
     copied?: string;
     /** Reset button label. Default: "Try again". */
     reset?: string;
@@ -53,5 +53,4 @@ export interface ErrorBoundaryProps extends Omit<HtmlProps, 'title' | 'onError'>
 export interface ErrorBoundaryState {
     error: Error | null;
     errorInfo: ErrorInfo | null;
-    copied: boolean;
 }

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

@@ -11,3 +11,5 @@ export type { UseSwipeDismissOptions, UseSwipeDismissResult } from './useSwipeDi
 export { useOverlay } from './useOverlay.js';
 export type { UseOverlayArgs } from './useOverlay.js';
 export { tabbablesIn } from './useFocusBoundary.js';
+export { useClipboard } from './useClipboard.js';
+export type { UseClipboardOptions, UseClipboardResult } from './useClipboard.js';

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

@@ -0,0 +1,16 @@
+export interface UseClipboardOptions {
+    /** How long `copied` stays `true` after a successful copy, in ms. Default: 2000. */
+    timeout?: number;
+}
+export interface UseClipboardResult {
+    /** Writes `text` to the clipboard. Resolves `true` on success, `false` on failure. */
+    copy: (text: string) => Promise<boolean>;
+    /** `true` for `timeout` ms after a successful copy. */
+    copied: boolean;
+    /** Why the last copy failed, until the next attempt. */
+    error: Error | null;
+    /** Clears `copied` and `error` early. */
+    reset: () => void;
+}
+export declare function useClipboard({ timeout }?: UseClipboardOptions): UseClipboardResult;
+export default useClipboard;

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

@@ -1,7 +1,11 @@
 import { default as React } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
 import { FormValidator } from '../../services/formValidation/index.js';
-export type InputDropdownSlots = 'root' | 'dropdown' | 'item';
+export type InputDropdownSlots = 'root' | 'dropdown' | 'item' | 'empty';
+export interface InputDropdownLabels {
+    /** Shown when nothing matches the typed text and `allowCustomValue` is off (default `No matches`). */
+    empty?: string;
+}
 export interface InputDropdownItem {
     label?: string;
     value: string;
@@ -29,6 +33,8 @@ export interface InputDropdownProps extends Omit<HtmlProps, 'onSelect'> {
     onChange?: (value: unknown) => void;
     placeholder?: string;
     readOnly?: boolean;
+    /** Overrides the text InputDropdown renders of its own. Merged per key. */
+    labels?: InputDropdownLabels;
     className?: string;
     style?: React.CSSProperties;
     classNames?: SlotClassNames<InputDropdownSlots>;

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

@@ -20,6 +20,8 @@ export interface MenuAction {
      * into a `useHotkeys` map, so the one spelling covers both ends.
      */
     shortcut?: string;
+    /** Extra search terms for `CommandPalette`, which also matches a string `label`. `Menu` ignores them. */
+    keywords?: string[];
     disabled?: boolean;
     /** Renders in the destructive colour. For deleting, discarding, revoking. */
     danger?: boolean;

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

@@ -9,6 +9,11 @@ interface State {
     resolvedVariables: Record<string, string>;
     colorFadeActive: boolean;
     currentThemeColor: string | null;
+    /** What `resolvedVariables` was resolved from, to tell a theme change from any other render. */
+    resolvedFrom: {
+        themes: Theme[] | undefined;
+        currentThemeId: string | undefined;
+    };
 }
 declare class ThemeProvider extends Component<Props, State> {
     state: State;
@@ -16,6 +21,7 @@ declare class ThemeProvider extends Component<Props, State> {
     private wrapperRef;
     private themeColorMeta;
     private createdThemeColorMeta;
+    static getDerivedStateFromProps(props: Props, state: State): Partial<State> | null;
     componentDidMount(): void;
     componentDidUpdate(prevProps: Props, prevState: State): void;
     componentWillUnmount(): void;
@@ -26,13 +32,8 @@ declare class ThemeProvider extends Component<Props, State> {
      * (and removes it again on unmount).
      */
     private syncThemeColorMeta;
-    /**
-     * Resolves the full variable set for a given theme ID by walking up the
-     * baseThemeId chain.  Returns variables ordered from deepest ancestor to
-     * the requested theme so callers can merge in order (later entries win).
-     */
-    private resolveChain;
-    private applyTheme;
+    /** `--primary-color` as the browser resolved it, which may be a `var()` of another variable. */
+    private readThemeColor;
     render(): React.JSX.Element;
 }
 export default ThemeProvider;

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

@@ -0,0 +1,3 @@
+export { default } from './weatherIcon.js';
+export { WeatherType } from './weatherIcon.types.js';
+export type { WeatherIconLabels, WeatherIconProps } from './weatherIcon.types.js';

package/dist/types/common/weatherIcon/parts.d.ts

@@ -0,0 +1,26 @@
+import { ReactElement } from 'react';
+import { WeatherPartProps } from './weatherIcon.types.js';
+/** Exported so a scene can clip what sits behind the cloud to this same silhouette. */
+export declare const CLOUD_PATH = "M 26.3 62.9 C 15.4 65.0 15.0 48.5 27.8 49.8 C 23.9 43.9 34.2 34.0 43.0 39.6 C 46.0 26.2 73.9 32.0 68.9 46.3 C 85.0 44.3 84.6 64.2 72.4 62.5 Z";
+export declare function Cloud({ className, delayed }: {
+    className?: string;
+    delayed?: boolean;
+}): ReactElement;
+export declare function Sun({ className }: {
+    className?: string;
+}): ReactElement;
+export declare function Moon({ className }: {
+    className?: string;
+}): ReactElement;
+export declare enum RainIntensity {
+    Light = "light",
+    Medium = "medium",
+    Heavy = "heavy"
+}
+export declare function Rain({ animated, intensity, }: WeatherPartProps & {
+    intensity?: RainIntensity;
+}): ReactElement;
+export declare function Snow({ animated }: WeatherPartProps): ReactElement;
+export declare function Hail({ animated }: WeatherPartProps): ReactElement;
+export declare function Fog(): ReactElement;
+export declare function Lightning(): ReactElement;

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

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { WeatherIconProps } from './weatherIcon.types.js';
+declare function WeatherIcon(props: WeatherIconProps): ReactElement;
+export default WeatherIcon;

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

@@ -0,0 +1,44 @@
+import { CSSProperties, SVGAttributes } from 'react';
+import { DataProps } from '../types/slots.types.js';
+export declare enum WeatherType {
+    Sunny = "sunny",
+    ClearNight = "clearNight",
+    Cloudy = "cloudy",
+    PartlyCloudy = "partlyCloudy",
+    PartlyCloudyNight = "partlyCloudyNight",
+    RainyLight = "rainyLight",
+    Rainy = "rainy",
+    RainyHeavy = "rainyHeavy",
+    Snowy = "snowy",
+    Hail = "hail",
+    Foggy = "foggy",
+    Thunderstorm = "thunderstorm"
+}
+/** The accessible name of each weather, read out by screen readers. */
+export type WeatherIconLabels = Partial<Record<`${WeatherType}`, string>>;
+/**
+ * The root is an `<svg>`, so the native attributes come from `SVGAttributes` rather than
+ * `HtmlProps`. Its `type` is the attribute of `<script>` and `<style>`, not of an `<svg>`.
+ */
+export interface WeatherIconProps extends DataProps, Omit<SVGAttributes<SVGSVGElement>, 'type'> {
+    /**
+     * The weather to draw. Takes the enum or its string value, so an API's own enum with the same
+     * values passes as it is.
+     */
+    type: WeatherType | `${WeatherType}`;
+    /** Width and height, any CSS size. Default `64`. */
+    size?: number | string;
+    /**
+     * Default `true`. `false` draws a still frame, for small or repeated icons where the motion is
+     * too small to see but costs the same. Always still under `prefers-reduced-motion`.
+     */
+    animated?: boolean;
+    /** Text this component renders of its own. */
+    labels?: WeatherIconLabels;
+    className?: string;
+    style?: CSSProperties;
+}
+/** What a falling part needs to know to pick its still frame. */
+export interface WeatherPartProps {
+    animated: boolean;
+}

package/dist/types/index.d.ts

@@ -31,10 +31,14 @@ export { default as Chip } from './common/chip/index.js';
 export * from './common/chip/index.js';
 export { default as ColorPicker } from './common/colorPicker/index.js';
 export * from './common/colorPicker/index.js';
+export { default as CommandPalette } from './common/commandPalette/index.js';
+export * from './common/commandPalette/index.js';
 export { default as ConfigProvider } from './common/configProvider/index.js';
 export * from './common/configProvider/index.js';
 export { default as ConfirmModal } from './common/confirmModal/index.js';
 export * from './common/confirmModal/index.js';
+export { default as CopyButton } from './common/copyButton/index.js';
+export * from './common/copyButton/index.js';
 export { default as DatePicker } from './common/datePicker/index.js';
 export * from './common/datePicker/index.js';
 export { default as Divider } from './common/divider/index.js';
@@ -146,6 +150,8 @@ export { default as Tree } from './common/tree/index.js';
 export * from './common/tree/index.js';
 export { default as VirtualList } from './common/virtualList/index.js';
 export * from './common/virtualList/index.js';
+export { default as WeatherIcon } from './common/weatherIcon/index.js';
+export * from './common/weatherIcon/index.js';
 export { default as Wizard } from './common/wizard/index.js';
 export * from './common/wizard/index.js';
 export * from './common/hooks/index.js';

package/docs/ButtonGroup.md

@@ -77,6 +77,8 @@ import { Input } from '@ahrowe/ui';
 
 **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.
 
+**One border per seam:** the overlap alone keeps both borders, and at a fractional scale (browser zoom, a 125% or 150% display) they round to different device pixels, so one seam reads 2px next to a 1px one. Each child therefore clips away the 1px it shares with the next one, and the later child's border is the one you see, as it always was. A focused child keeps its whole border, and the next child clips its shared 1px instead. This is a `clip-path` on the children, so a `clip-path` of your own on a grouped child is overridden.
+
 Flattening reaches a child's visible border even when that border doesn't live on the child's own root element — the case for `Input`, `Dropdown`, and everything built on either of them (`NumberInput`, `DatePicker`, `TimeInput`, `InputDropdown`, `Textarea`), whose actual border sits on a `fieldset` nested inside a `<label>`, as well as `ColorPicker`'s swatch and `Checkbox`'s checkmark box. Alongside the direct `border-radius` reset it applies to each child's root, `ButtonGroup` also sets `--group-radius-tl`/`-tr`/`-br`/`-bl` custom properties per position. Unlike `border-radius` itself, custom properties inherit through any nesting depth, so a descendant whose own `border-radius` reads `var(--group-radius-tl, var(--default-border-radius))` (etc.) picks up the right corner overrides no matter how deep it's nested — no consumer-facing prop needed.
 
 **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.

package/docs/CLAUDE.md

@@ -59,8 +59,10 @@ enums and slot names. Do not infer props from a component's name.
 | Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
 | Chip.md | Chip, ChipContainer, ChipStyleType | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
 | ColorPicker.md | ColorPicker | Hex colour selection — theme editors, annotation tools, customisation panels |
+| CommandPalette.md | CommandPalette | A search-first dialog for running any command or jumping anywhere in the app from the keyboard, usually opened with ⌘K / Ctrl+K |
 | ConfigProvider.md | ConfigProvider | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
 | ConfirmModal.md | ConfirmModal | Confirmation dialog before destructive or irreversible actions — delete, archive, send, overwrite |
+| CopyButton.md | CopyButton | Icon-only button that copies a value to the clipboard: an invoice number, an ID in a table row, an API key or share link inside an `Input` |
 | DatePicker.md | DatePicker | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
 | Divider.md | Divider, DividerTextPosition, DividerOrientation | A rule that separates sections of content — horizontal by default, filling the width of its parent |
 | Drawer.md | Drawer | Inline horizontal panel that collapses and expands by animating its width — side panels, navigation rails, detail/filter panes that slide open beside the main content |
@@ -73,7 +75,7 @@ enums and slot names. Do not infer props from a component's name.
 | FloorPlan.md | emptyFloorPlan, addWall, derivePlan | The shared data model behind `RoomDrawer` and `RoomViewer` |
 | FormValidator.md | FormValidator, Validators, useFormValidator | Track and validate a single form field's value, dirty/touched state, and errors |
 | FormValidatorGroup.md | useFormValidatorGroup, FormValidatorGroup, FormValidator, Validators | Manage a whole form — multiple fields, a single submit handler, validate-on-submit, dirty/touched tracking across the form, and mapping server-side errors back onto the right fields |
-| Hooks.md | useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, tabbablesIn | Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay |
+| Hooks.md | useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, useClipboard, tabbablesIn | Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, copying to the clipboard, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay |
 | IconPicker.md | IconPicker | Pick one item from a visual icon/image grid — category selectors, emoji-style pickers, avatar selectors, anything where each option is best represented by an icon or image rather than text alone |
 | IdleManager.md | IdleManager | Show something only once the user has stopped interacting — a screen saver, a session-timeout warning, an "are you still there?" prompt, an idle dashboard view |
 | Input.md | Input, InputType | Text input with floating label, validation state, and type variants |
@@ -119,6 +121,7 @@ enums and slot names. Do not infer props from a component's name.
 | Tooltip.md | Tooltip | Contextual help, info icons, field explanations, error pointers |
 | Tree.md | Tree, flattenTree | A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts |
 | VirtualList.md | VirtualList | Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM |
+| WeatherIcon.md | WeatherIcon, WeatherType | An animated weather symbol for a forecast, a dashboard widget or a day selector, one per condition a forecast reports |
 | Wizard.md | Wizard | Animated step container for multi-step forms and flows |
 
 <!-- components:end -->

package/docs/CommandPalette.md

@@ -0,0 +1,84 @@
+# CommandPalette
+
+**When to use:** A search-first dialog for running any command or jumping anywhere in the app from the keyboard, usually opened with ⌘K / Ctrl+K. It takes the same `MenuEntry[]` as [Menu](Menu.md), so one list can feed the menus, the palette and the shortcuts. For picking a value in a form, use [InputDropdown](InputDropdown.md).
+
+**Keywords:** cmd+k, ctrl+k, command menu, quick open, launcher, spotlight, go to anything, jump to, omnibox
+
+**Import:** `import { CommandPalette } from '@ahrowe/ui'`  
+**Types:** `import type { CommandPaletteProps, CommandPaletteLabels } from '@ahrowe/ui'`
+
+**Requires:** `<div id="bodyEnd"></div>` in your app: the palette is a [Modal](Modal.md) and portals there.
+
+```tsx
+import { CommandPalette, menuHotkeys, useHotkeys } from '@ahrowe/ui';
+import type { MenuEntry } from '@ahrowe/ui';
+
+const commands: MenuEntry[] = [
+  { heading: 'Invoice' },
+  { id: 'new-invoice', label: 'New invoice', icon: faPlus, shortcut: 'mod+n', onClick: createInvoice },
+  { id: 'export', label: 'Export as PDF', icon: faFilePdf, keywords: ['download', 'print'], onClick: exportPdf },
+  { heading: 'Go to' },
+  { id: 'customers', label: 'Customers', onClick: () => navigate('/customers') },
+];
+
+function App() {
+  const [isOpen, setOpen] = useState(false);
+  useHotkeys({ ...menuHotkeys(commands), 'mod+k': () => setOpen(true) });
+
+  return <CommandPalette items={commands} isOpen={isOpen} onClose={() => setOpen(false)} />;
+}
+```
+
+**Opening it is yours.** The palette binds no shortcut of its own, for the same reason `Menu` does not: if it listened for ⌘K and your app did too, it would open twice. `menuHotkeys` binds each command's `shortcut`, so the hint the palette draws and the key that fires stay one spelling.
+
+**Filtering** matches every typed word, in any order, against a string `label` and the command's `keywords`, ignoring case and accents: `uber` finds `Übersicht`. Within each group, a label starting with the query comes first, then a label word or a keyword starting with it, then any other match, and the group holding the best match moves to the top. A heading moves with its group and stays above it while any of it matches; separators are dropped while a query is typed. Typing highlights the best match, so Enter runs it. A `label` that is not a string cannot be read, so give such a command `keywords`.
+
+**Server results.** Set `filter={false}` and the palette shows `items` exactly as given, so they can be the results of your own search:
+
+```tsx
+const [results, setResults] = useState<MenuEntry[]>(commands);
+const [isLoading, setLoading] = useState(false);
+
+<CommandPalette
+  items={results}
+  filter={false}
+  isLoading={isLoading}
+  onQueryChange={(query) => {
+    if (!query) return setResults(commands);
+    setLoading(true);
+    searchCustomers(query).then((hits) => {
+      setResults(hits.map((c) => ({ id: c.id, label: c.name, onClick: () => navigate(`/customers/${c.id}`) })));
+      setLoading(false);
+    });
+  }}
+  isOpen={isOpen}
+  onClose={() => setOpen(false)}
+/>;
+```
+
+`onQueryChange` fires on every keystroke and with `''` each time the palette opens, so debounce the request and drop a response that arrives after a newer query. Between keystrokes the highlight follows the command's `id`, so it stays put while results arrive and are replaced around it.
+
+**Keyboard:** the focus stays in the search field. ↑ and ↓ move the highlight, wrapping and skipping disabled commands, Enter runs it, and Escape closes. Running a command calls its own `onClick`, then `onAction`, then `onClose`, the same order `Menu` uses. The number of matches is announced to screen readers as it changes.
+
+On a small touch screen it can present as a bottom sheet like every `Modal`: pass `presentation={Presentation.Auto}`, or set it app-wide through `ConfigProvider`.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `MenuEntry[]` | The commands. Headings group them; separators split groups (required) |
+| `isOpen` | `boolean` | Whether the palette is open (required) |
+| `onClose` | `() => void` | Called on Escape, a backdrop click, and after a command runs (required) |
+| `onAction` | `(id: string) => void` | Called with the id of the command that ran, after its own `onClick` |
+| `onQueryChange` | `(query: string) => void` | Called on every keystroke, and with `''` on open |
+| `filter` | `boolean` | Filter `items` by the query (default `true`). `false` shows them as given |
+| `isLoading` | `boolean` | Shows the `loading` label instead of `empty` while nothing matches |
+| `presentation` | `Presentation` | Centred dialog (default), bottom sheet, or a sheet only on a small touch screen |
+
+A command is a `MenuAction`: `id`, `label`, `icon`, `shortcut`, `keywords`, `disabled`, `danger` and `onClick`. See [Menu.md](Menu.md).
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CommandPalette: { presentation: Presentation.Auto } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `search` `input` `list` `item` `itemIcon` `itemLabel` `itemShortcut` `heading` `separator` `empty`
+
+**Labels:** `label` `placeholder` `empty` `loading` `results(count)`: 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: `CommandPaletteLabels`.

package/docs/ConfigProvider.md

@@ -92,8 +92,8 @@ A nested provider inherits it unless it sets its own, the same way `defaultProps
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
 
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
-- **Display:** `Button` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer`
-- **Overlays:** `ConfirmModal` · `Modal` · `Popover` · `Popover`
+- **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
+- **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
 - **Editors:** `RoomDrawer`, `RoomViewer`
 
 ```tsx

package/docs/CopyButton.md

@@ -0,0 +1,45 @@
+# CopyButton
+
+**When to use:** Icon-only button that copies a value to the clipboard: an invoice number, an ID in a table row, an API key or share link inside an `Input`. For a labelled "Copy link" button, use `Button` with the `useClipboard` hook instead (see [Hooks.md](Hooks.md)).
+
+**Keywords:** token, secret, reference number, snippet
+
+**Import:** `import { CopyButton } from '@ahrowe/ui'`  
+**Types:** `import type { CopyButtonProps, CopyButtonLabels } from '@ahrowe/ui'`
+
+```tsx
+import { CopyButton, Input } from '@ahrowe/ui';
+
+<span>
+  {invoice.number} <CopyButton value={invoice.number} />
+</span>
+
+// inside a field
+<Input label='API key' value={apiKey} readOnly suffix={<CopyButton value={apiKey} />} />
+
+// a toast on success, where the button is not where the user is looking
+<CopyButton value={url} onCopy={() => showToast('Link copied', { type: 'success' })} />
+```
+
+After a click the icon rotates into a check (through `AnimatedIcon`, held still under `prefers-reduced-motion`) for `timeout` ms, the accessible name and tooltip read "Copied", and a polite live region announces it, because a swapped icon or a changed `aria-label` alone is not read out. A refused write (an insecure context, a blocked iframe) announces "Could not copy" and calls `onError`; the icon stays as it was. `CopyButton` shows no toast of its own: pass one through `onCopy` / `onError` if you want it.
+
+The live region is rendered as a sibling of the button, so `CopyButton` returns two elements. It is visually hidden and takes no space.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Text written to the clipboard on click (required) |
+| `timeout` | `number` | How long the copied state shows, in ms (default `2000`) |
+| `icon` | `IconDefinition \| ReactElement` | Icon before copying (default `faCopy`). The swap animates only when both icons are FontAwesome definitions |
+| `copiedIcon` | `IconDefinition \| ReactElement` | Icon while copied (default `faCheck`) |
+| `onCopy` | `(value: string) => void` | Called after a successful copy |
+| `onError` | `() => void` | Called when the clipboard refuses the write. `useClipboard` returns the reason |
+| `onClick` | `(event: MouseEvent) => void` | Called on every click, before the copy |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the button |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CopyButton: { timeout: 1500 } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `icon`
+
+**Labels:** `copy` `copied` `failed`: 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: `CopyButtonLabels`.

package/docs/ErrorBoundary.md

@@ -65,7 +65,7 @@ import { ErrorBoundary } from '@ahrowe/ui';
 </ErrorBoundary>
 ```
 
-The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a labeled copy `Button` that fires a `Toast` confirmation if `ToastProvider` is mounted), and a `Button` for "Try again".
+The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a `CopyButton` that also fires a `Toast` confirmation if `ToastProvider` is mounted), and a `Button` for "Try again".
 
 **Key props:**
 
@@ -74,7 +74,7 @@ The default fallback is a centered card with a tinted icon badge, an `Accordion`
 | `children` | `ReactNode` | The subtree to protect |
 | `title` | `ReactNode` | Heading in the default fallback (default `"Something went wrong"`) |
 | `description` | `ReactNode` | Overrides the message shown under the title. Defaults to `error.message` |
-| `labels` | `ErrorBoundaryLabels` | Overrides for every other built-in string (stack trace label, copy/reset button text, copy toasts) — pass a translated set for non-English apps. See below |
+| `labels` | `ErrorBoundaryLabels` | Overrides for every other built-in string (stack trace label, copy button tooltip, reset button text, copy toasts) — pass a translated set for non-English apps. See below |
 | `fallback` | `ReactNode \| (props: ErrorBoundaryFallbackProps) => ReactNode` | Replaces the built-in fallback entirely. The render-function form receives `{ error, errorInfo, resetErrorBoundary }` |
 | `onError` | `(error: Error, errorInfo: ErrorInfo) => void` | Called once per catch — the place to report to Sentry/Datadog/etc. |
 | `onReset` | `() => void` | Called after the boundary is reset, whether via the built-in "Try again" button, a custom fallback calling `resetErrorBoundary`, or a `resetKeys` change. Use it to re-arm whatever state caused the crash |
@@ -86,8 +86,8 @@ The default fallback is a centered card with a tinted icon badge, an `Accordion`
 | Field | Default | Description |
 |-------|---------|--------------|
 | `stackTrace` | `"Stack trace"` | Accordion header for the stack trace section |
-| `copy` | `"Copy"` | Copy button label before copying |
-| `copied` | `"Copied"` | Copy button label right after a successful copy |
+| `copy` | `"Copy"` | Copy button tooltip and accessible name before copying |
+| `copied` | `"Copied"` | Copy button tooltip and accessible name right after a successful copy |
 | `reset` | `"Try again"` | Reset button label |
 | `copySuccessToast` | `"Stack trace copied to clipboard"` | Toast shown after a successful copy (only visible if `ToastProvider` is mounted) |
 | `copyErrorToast` | `"Could not copy stack trace"` | Toast shown if the copy fails |

package/docs/Fab.md

@@ -22,7 +22,6 @@ import { faPlus, faPen, faCamera } from '@fortawesome/free-solid-svg-icons';
     { id: 'photo', icon: faCamera, label: 'Photo' },
   ]}
   onMenuEntryClicked={(id) => handleAction(id)}
-  closeMenuOnEntryClicked
 />
 
 // Mini size
@@ -38,7 +37,7 @@ import { faPlus, faPen, faCamera } from '@fortawesome/free-solid-svg-icons';
 | `size` | `'default' \| 'mini'` | Button size |
 | `menuEntries` | `FabMenuEntry[]` | `{ id, icon, label? }` — enables speed dial |
 | `onMenuEntryClicked` | `(id: string) => void` | Sub-menu entry handler |
-| `closeMenuOnEntryClicked` | `boolean` | Auto-close menu after selection |
+| `closeMenuOnEntryClicked` | `boolean` | Close the menu after an entry is picked (default `true`) |
 | `onClick` | `() => void` | Simple click handler (no speed dial) |
 | `children` | `ReactNode` | FAB icon content |