@ahrowe/ui 0.1.5 → 0.1.7

package/docs/CLAUDE.md

@@ -111,14 +111,16 @@ Slot keys per component are documented in each component's doc file below.
 @Chip.md
 @ColorPicker.md
 @ConfirmModal.md
+@DatePicker.md
 @Dropdown.md
 @EmptyState.md
 @Fab.md
 @FloatingMenu.md
-@Icon.md
+@IconPicker.md
 @IdleManager.md
 @InfiniteBlock.md
 @Input.md
+@InputDropdown.md
 @InteractableDiv.md
 @KanbanBoard.md
 @Loading.md
@@ -129,10 +131,14 @@ Slot keys per component are documented in each component's doc file below.
 @ProgressBar.md
 @Ripple.md
 @RoomDrawer.md
+@RoomViewer.md
 @ScrollbarProvider.md
 @SearchInput.md
 @Stepper.md
 @TenorPicker.md
 @Textarea.md
+@ThemeProvider.md
+@Toast.md
 @Tooltip.md
+@VirtualList.md
 @Wizard.md

package/docs/DatePicker.md

@@ -0,0 +1,77 @@
+# DatePicker
+
+**When to use:** Date selection input — booking forms, birth date fields, date range pickers, deadline selectors. Renders as a text input with a floating label by default; can also be inline or modal.
+
+**Import:** `import { DatePicker } from '@ahrowe/ui'`
+
+```tsx
+import { DatePicker, FormValidator } from '@ahrowe/ui';
+
+// Controlled input with floating label
+<DatePicker
+  label="Date of birth"
+  selected={date}
+  onSelect={(date) => setDate(date)}
+/>
+
+// With FormValidator
+const dateValidator = new FormValidator<Date | null>(null);
+<DatePicker label="Start date" formValidator={dateValidator} />
+
+// Inline calendar (no input field)
+<DatePicker
+  selected={date}
+  onSelect={setDate}
+  isInline
+  noInput
+/>
+
+// Inside a modal (calendar opens in a Modal overlay)
+<DatePicker
+  label="Schedule date"
+  selected={date}
+  onSelect={setDate}
+  isModal
+/>
+
+// With min/max constraints and a clear button
+<DatePicker
+  label="Appointment"
+  selected={date}
+  onSelect={setDate}
+  minDate={new Date()}
+  maxDate={endOfYear}
+  showClearButton
+/>
+
+// Date range (highlight start–end)
+<DatePicker
+  label="From"
+  selected={startDate}
+  onSelect={setStartDate}
+  startDate={startDate}
+  endDate={endDate}
+/>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Floating label on the input |
+| `selected` | `Date` | Currently selected date |
+| `onSelect` | `(date: Date \| null) => void` | Called when a date is picked |
+| `onChange` | `(date: Date \| null) => void` | Alternative change callback |
+| `formValidator` | `FormValidator` | Connects to validation |
+| `isRequired` | `boolean` | |
+| `isValid` | `boolean` | Manual valid state |
+| `errorMessage` | `string` | Manual error message |
+| `noInput` | `boolean` | Hide the text input (show calendar only) |
+| `noHeader` | `boolean` | Hide the month/year navigation header |
+| `isModal` | `boolean` | Open calendar in a Modal overlay |
+| `isInline` | `boolean` | Render calendar always-visible inline |
+| `minDate` | `Date \| null` | Earliest selectable date |
+| `maxDate` | `Date \| null` | Latest selectable date |
+| `showClearButton` | `boolean` | Show a clear/reset button |
+| `startDate` | `Date` | Range highlight start |
+| `endDate` | `Date` | Range highlight end |

package/docs/IconPicker.md

@@ -0,0 +1,55 @@
+# IconPicker
+
+**When to use:** 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.
+
+**Import:** `import { IconPicker } from '@ahrowe/ui'`  
+**Types:** `import type { IconPickerItem, IconPickerProps } from '@ahrowe/ui'`
+
+```tsx
+import { IconPicker, FormValidator } from '@ahrowe/ui';
+import type { IconPickerItem } from '@ahrowe/ui';
+import { faHouse, faCar, faTree } from '@fortawesome/free-solid-svg-icons';
+
+const items: IconPickerItem[] = [
+  { id: 'house', label: 'House',  icon: faHouse },
+  { id: 'car',   label: 'Car',    icon: faCar },
+  { id: 'tree',  label: 'Tree',   icon: faTree },
+  { id: 'custom', label: 'Custom', customIcon: <img src="/logo.png" alt="" /> },
+];
+
+// Controlled
+<IconPicker
+  label="Category"
+  data={items}
+  selectedId={selectedId}
+  onChange={(id) => setSelectedId(id)}
+/>
+
+// With FormValidator
+const categoryValidator = new FormValidator<string | null>(null);
+<IconPicker label="Category" data={items} formValidator={categoryValidator} isRequired />
+```
+
+**IconPickerItem:**
+
+```ts
+interface IconPickerItem {
+  id: string;
+  label: string;
+  icon?: IconDefinition;       // FontAwesome icon
+  customIcon?: React.ReactNode; // custom element (overrides icon)
+}
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `IconPickerItem[]` | Items to display in the grid |
+| `selectedId` | `string \| null` | Currently selected item id |
+| `label` | `string` | Floating label |
+| `onChange` | `(id: string) => void` | Called when selection changes |
+| `formValidator` | `FormValidator` | Connects to validation |
+| `isRequired` | `boolean` | |
+
+**Slots:** `root` `label` `itemContainer` `item`

package/docs/InputDropdown.md

@@ -0,0 +1,52 @@
+# InputDropdown
+
+**When to use:** Combobox-style input — the user can type to filter and also pick from a dropdown list. Use over `Dropdown` when free-text entry or search-to-filter behaviour is needed.
+
+**Import:** `import { InputDropdown } from '@ahrowe/ui'`  
+**Types:** `import type { InputDropdownItem, InputDropdownProps } from '@ahrowe/ui'`
+
+```tsx
+import { InputDropdown } from '@ahrowe/ui';
+import type { InputDropdownItem } from '@ahrowe/ui';
+
+const items: InputDropdownItem[] = [
+  { value: 'react',      label: 'React' },
+  { value: 'vue',        label: 'Vue' },
+  { value: 'svelte',     label: 'Svelte' },
+];
+
+// Controlled
+<InputDropdown
+  label="Framework"
+  value={selected}
+  items={items}
+  onSelect={(value) => setSelected(value)}
+/>
+
+// With FormValidator
+const frameworkValidator = new FormValidator('');
+<InputDropdown label="Framework" items={items} formValidator={frameworkValidator} />
+```
+
+**InputDropdownItem:**
+
+```ts
+interface InputDropdownItem {
+  value: string;
+  label?: string;  // displayed text — falls back to value if omitted
+}
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Floating label |
+| `value` | `string` | Controlled value |
+| `items` | `InputDropdownItem[]` | Dropdown options |
+| `onSelect` | `(value: string) => void` | Called when an item is picked from the list |
+| `onChange` | `(value: unknown) => void` | Called on every text change |
+| `placeholder` | `string` | |
+| `formValidator` | `FormValidator` | Connects to validation |
+
+**Slots:** `root` `dropdown` `item`

package/docs/RoomViewer.md

@@ -0,0 +1,39 @@
+# RoomViewer
+
+**When to use:** Display read-only SVG floor plans with a floor selector — venue maps, seating layouts, building directories. Pair with `RoomDrawer` when you also need editing capability.
+
+**Import:** `import { RoomViewer } from '@ahrowe/ui'`  
+**Types:** `import type { RoomViewerFloor, RoomViewerProps } from '@ahrowe/ui'`
+
+```tsx
+import { RoomViewer } from '@ahrowe/ui';
+import type { RoomViewerFloor } from '@ahrowe/ui';
+
+const floors: RoomViewerFloor[] = [
+  {
+    label: 'Ground Floor',
+    data: <GroundFloorSvg />,
+  },
+  {
+    label: 'First Floor',
+    data: <FirstFloorSvg />,
+  },
+];
+
+<RoomViewer data={floors} />
+```
+
+**RoomViewerFloor:**
+
+```ts
+interface RoomViewerFloor {
+  label: string;        // Tab/selector label shown above the plan
+  data: React.ReactNode; // SVG floor plan element
+}
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `RoomViewerFloor[]` | Floor definitions to display |

package/docs/ThemeProvider.md

@@ -0,0 +1,82 @@
+# ThemeProvider
+
+**When to use:** Required wrapper for the entire component library. Injects all CSS custom properties as inline styles so every component inside can use theme variables. Place it at or near the root of your app.
+
+**Import:** `import { ThemeProvider } from '@ahrowe/ui'`  
+**Types:** `import type { Theme, ThemeVariables } from '@ahrowe/ui'`
+
+```tsx
+import { ThemeProvider } from '@ahrowe/ui';
+import '@ahrowe/ui/style.css'; // add once in your entry point
+
+// Minimal — uses the built-in default theme
+<ThemeProvider>
+  <App />
+</ThemeProvider>
+
+// With a custom theme
+import type { Theme } from '@ahrowe/ui';
+
+const brandTheme: Theme = {
+  id: 'brand',
+  variables: {
+    '--primary-color': '#6200ea',
+    '--primary-lighter': '#b388ff',
+    '--primary-accent': '#7c4dff',
+    '--background': '#ffffff',
+    '--text-color': '#212121',
+  },
+};
+
+<ThemeProvider themes={[brandTheme]} currentThemeId="brand">
+  <App />
+</ThemeProvider>
+
+// Extending the built-in theme (only override specific variables)
+const darkTheme: Theme = {
+  id: 'dark',
+  baseThemeId: 'default', // inherit everything not listed here
+  variables: {
+    '--background': '#121212',
+    '--background-accent': '#1e1e1e',
+    '--text-color': '#ffffff',
+  },
+};
+
+<ThemeProvider themes={[darkTheme]} currentThemeId="dark">
+  <App />
+</ThemeProvider>
+```
+
+**Theme type:**
+
+```ts
+interface Theme {
+  id: string;
+  baseThemeId?: string;    // inherit from another theme before applying variables
+  variables: ThemeVariables;
+}
+```
+
+**Key CSS variables** (see `package/common/themeProvider/theme.types.ts` for the full list):
+
+| Variable | Purpose |
+|----------|---------|
+| `--primary-color` / `--primary-lighter` / `--primary-accent` | Brand colours |
+| `--background` | Page/surface background |
+| `--background-accent` / `--background-accent-light` | Raised surfaces, cards |
+| `--text-color` / `--text-dark` | Primary and secondary text |
+| `--border-color` | Borders and dividers |
+| `--error-color` / `--success-color` / `--warn-color` / `--info-color` | Semantic colours |
+| `--default-border-radius` | Border radii |
+| `--card-shadow` | Elevation shadows |
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Your app content (required) |
+| `themes` | `Theme[]` | Theme definitions — defaults to built-in default theme |
+| `currentThemeId` | `string` | Active theme id — must match one of the `themes[].id` values |
+
+**Note:** Without `ThemeProvider`, all CSS variables are undefined and components will be unstyled.

package/docs/Toast.md

@@ -0,0 +1,67 @@
+# Toast
+
+**When to use:** Non-blocking notifications — save confirmations, error alerts, info messages, warnings. Toasts appear in a corner of the screen and auto-dismiss after a configurable duration.
+
+**Import:** `import { ToastProvider, showToast } from '@ahrowe/ui'`  
+**Types:** `import type { ToastOptions, ToastType, ToastPosition } from '@ahrowe/ui'`
+
+**Setup:** Wrap your app with `ToastProvider` (inside `ThemeProvider`):
+
+```tsx
+import { ThemeProvider, ToastProvider } from '@ahrowe/ui';
+
+<ThemeProvider>
+  <ToastProvider position="bottom-right" duration={3000}>
+    <App />
+  </ToastProvider>
+</ThemeProvider>
+```
+
+**Usage:** Call `showToast` anywhere — no component hierarchy required:
+
+```tsx
+import { showToast } from '@ahrowe/ui';
+
+// Simple message
+showToast('Profile saved!');
+
+// With type
+showToast('Something went wrong.', { type: 'error' });
+showToast('3 items updated.', { type: 'info' });
+showToast('Disk space is low.', { type: 'warn' });
+
+// Persistent (no auto-dismiss)
+showToast('Processing…', { duration: 0, showCloseButton: true });
+
+// With progress bar showing remaining time
+showToast('Uploading file…', {
+  duration: 5000,
+  showRemainingTime: true,
+});
+
+// Override position per-toast
+showToast('Copied!', { position: 'top-center', duration: 1500 });
+
+// With slot overrides
+showToast('Done', {
+  type: 'info',
+  classNames: { root: 'my-toast' },
+  styles: { progressBar: { backgroundColor: '#6200ea' } },
+});
+```
+
+**ToastProviderProps** (default config for all toasts):
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `position` | `ToastPosition` | `'bottom-right'` | Screen position |
+| `duration` | `number` | `3000` | Auto-dismiss delay in ms; `0` = persistent |
+| `showRemainingTime` | `boolean` | `false` | Show a progress bar draining to zero |
+| `showCloseButton` | `boolean` | `false` | Show × button |
+| `allowStacking` | `boolean` | `true` | Allow multiple toasts simultaneously |
+
+**ToastPosition:** `'top-left'` `'top-center'` `'top-right'` `'bottom-left'` `'bottom-center'` `'bottom-right'`
+
+**ToastType:** `'default'` `'info'` `'error'` `'warn'`
+
+**Slots:** `root` `icon` `content` `closeButton` `progressBar`

package/docs/VirtualList.md

@@ -0,0 +1,108 @@
+# VirtualList
+
+**When to use:** Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM. Supports column definitions, row selection, multi-select, column visibility toggling, and infinite scroll.
+
+**Import:** `import { VirtualList } from '@ahrowe/ui'`  
+**Types:** `import type { VirtualListProps, VirtualListColumn } from '@ahrowe/ui'`
+
+```tsx
+import { VirtualList } from '@ahrowe/ui';
+import type { VirtualListColumn } from '@ahrowe/ui';
+
+type User = { id: string; name: string; email: string; role: string };
+
+// Simple list mode (no columns)
+<VirtualList
+  items={users}
+  renderRow={(user) => (
+    <div className="row">{user.name} — {user.email}</div>
+  )}
+  height={500}
+/>
+
+// Table mode with column definitions
+const columns: VirtualListColumn<User>[] = [
+  {
+    key: 'name',
+    label: 'Name',
+    width: { type: 'flex', weight: 2 },
+    renderCell: (user) => <strong>{user.name}</strong>,
+  },
+  {
+    key: 'email',
+    label: 'Email',
+    width: { type: 'flex' },
+    renderCell: (user) => user.email,
+  },
+  {
+    key: 'role',
+    label: 'Role',
+    width: { type: 'fixed', px: 120 },
+    renderCell: (user) => user.role,
+    defaultHidden: true,
+  },
+];
+
+<VirtualList
+  items={users}
+  columns={columns}
+  getItemKey={(user) => user.id}
+  selectedKey={selectedId}
+  onRowClick={(user) => setSelectedId(user.id)}
+  height={600}
+/>
+
+// Infinite scroll
+<VirtualList
+  items={items}
+  columns={columns}
+  onLoadMore={async () => { await fetchNextPage(); }}
+  isLoading={isInitialLoading}
+  height="100%"
+/>
+
+// Multi-select
+<VirtualList
+  items={items}
+  columns={columns}
+  multiSelect
+  selectedKeys={selectedKeys}
+  onSelectionChange={(keys) => setSelectedKeys(keys)}
+  height={500}
+/>
+```
+
+**Column width types:**
+
+```ts
+{ type: 'fixed'; px: number }          // fixed pixel width
+{ type: 'flex';  weight?: number }     // flex, weight defaults to 1
+{ type: 'fit' }                        // shrink to content
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `T[]` | Data array (required) |
+| `renderRow` | `(item, index) => ReactNode` | Row render fn — list mode (no columns) |
+| `columns` | `VirtualListColumn<T>[]` | Column definitions — enables table/header mode |
+| `height` | `number \| string` | Scroll viewport height (default `'100%'`) |
+| `estimatedRowHeight` | `number` | Estimated row height before measurement (default `40`) |
+| `overscan` | `number` | Extra rows rendered outside the viewport (default `3`) |
+| `rowGap` | `number` | Gap in px between rows (default `0`) |
+| `showDivider` | `boolean` | Row divider lines (default `true`) |
+| `getItemKey` | `(item, index) => string \| number` | Stable key per item |
+| `selectedKey` | `string \| number \| null` | Controlled single-select key |
+| `onRowClick` | `(item, index) => void` | Row click handler |
+| `multiSelect` | `boolean` | Enable checkbox multi-select column |
+| `selectedKeys` | `Set<string \| number>` | Controlled multi-select keys |
+| `onSelectionChange` | `(keys) => void` | Multi-select change callback |
+| `showColumnToggle` | `boolean` | Show gear button to show/hide columns (default `true` when columns present) |
+| `visibleColumnKeys` | `string[]` | Controlled visible column keys |
+| `onVisibleColumnsChange` | `(keys) => void` | Column visibility change callback |
+| `onLoadMore` | `() => Promise<void>` | Triggered near the bottom — append items in the handler |
+| `loadMoreThreshold` | `number` | Distance from bottom that triggers `onLoadMore` (default `100`) |
+| `isLoading` | `boolean` | Replaces list body with a full-height spinner |
+
+**Slots:** `root` `header` `headerCell` `headerToggle` `togglePopover` `toggleItem` `body` `row` `cell` `selectCell` `loadingIndicator`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "publishConfig": {
     "access": "public"
   },
@@ -43,12 +43,16 @@
     "dist",
     "docs"
   ],
+  "lint-staged": {
+    "*.{ts,tsx}": "vitest related --run"
+  },
   "scripts": {
     "dev": "vite",
     "build": "vite build",
     "build:lib": "vite build --config vite.lib.config.ts",
     "build:mcp": "vite build --config vite.mcp.config.ts",
     "preview": "vite preview",
+    "gen-barrel": "tsx scripts/gen-barrel.ts",
     "gc": "bash src/scripts/generateComponent.sh $INIT_CWD process.argv",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -58,7 +62,8 @@
     "verify-package": "bash src/scripts/verify-package.sh",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:ui": "vitest --ui"
+    "test:ui": "vitest --ui",
+    "prepare": "husky"
   },
   "peerDependencies": {
     "@fortawesome/fontawesome-svg-core": ">=6.0.0",
@@ -99,8 +104,10 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
+    "husky": "^9.1.7",
     "jiti": "^2.7.0",
     "jsdom": "^29.1.1",
+    "lint-staged": "^17.0.5",
     "postcss": "^8.5.15",
     "postcss-nested": "^7.0.2",
     "prettier": "^3.8.3",
@@ -108,6 +115,7 @@
     "react-dom": "^19.2.6",
     "react-element-to-jsx-string": "^17.0.1",
     "react-syntax-highlighter": "^16.1.1",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",
     "vite": "^8.0.14",

package/dist/types/package/common/icon/Icon.d.ts

@@ -1,10 +0,0 @@
-export default Icon;
-declare function Icon({ type, ...rest }: {
-    [x: string]: any;
-    type: any;
-}): import("react/jsx-runtime").JSX.Element | null;
-declare namespace Icon {
-    namespace propTypes {
-        let type: any;
-    }
-}

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

@@ -1,2 +0,0 @@
-import { default as Icon } from './Icon';
-export default Icon;

package/dist/types/package/common/icon/svg/can.d.ts

@@ -1,2 +0,0 @@
-export default Can;
-declare function Can(props: any): import("react/jsx-runtime").JSX.Element;

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

@@ -1,2 +0,0 @@
-import { default as InputDropdownModern } from './inputDropdownModern.jsx';
-export default InputDropdownModern;

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

@@ -1,35 +0,0 @@
-import { ValidatableComponent } from '../../services/formValidation';
-export default InputDropdownModern;
-declare class InputDropdownModern extends ValidatableComponent<import('../../services/formValidation/validatableComponent').ValidatableComponentProps, import('../../services/formValidation/validatableComponent').ValidatableComponentState> {
-    static propTypes: {
-        label: any;
-        value: any;
-        formValidator: any;
-        items: any;
-        className: any;
-        onSelect: any;
-        placeholder: any;
-    };
-    static defaultProps: {
-        label: string;
-        value: string;
-        formValidator: null;
-        items: never[];
-        className: string;
-        onSelect: () => null;
-        placeholder: string;
-    };
-    constructor(props: any);
-    state: {
-        isMenuShown: boolean;
-        highlightedIndex: null;
-        currItems: any;
-        lastVal: string;
-    };
-    getItemsForValue: (value: any) => any;
-    getValueFromProps: (props: any) => any;
-    componentDidUpdate(prevProps: any, prevState: any): void;
-    hideMenuTimeout: any;
-    onKeyDown: (event: any) => void;
-    render(): import("react/jsx-runtime").JSX.Element;
-}

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

@@ -1,2 +0,0 @@
-import { default as RoleManager } from './roleManager.container.js';
-export default RoleManager;

package/dist/types/package/common/roleManager/roleManager.container.d.ts

@@ -1,2 +0,0 @@
-declare const _default: any;
-export default _default;

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

@@ -1,22 +0,0 @@
-import { default as React } from 'react';
-export default RoleManager;
-declare class RoleManager extends React.Component<any, any, any> {
-    static propTypes: {
-        children: any;
-        anyRequiredRoles: any;
-        allRequiredRoles: any;
-        invalidRoleContent: any;
-        user: any;
-        household: any;
-    };
-    static defaultProps: {
-        children: null;
-        anyRequiredRoles: never[];
-        allRequiredRoles: never[];
-        invalidRoleContent: null;
-    };
-    constructor(props: any);
-    state: {};
-    checkIsRoleSufficient: () => any;
-    render(): import("react/jsx-runtime").JSX.Element;
-}