@ahrowe/ui 0.1.6 → 0.1.8

package/docs/Toast.md

@@ -0,0 +1,68 @@
+# 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('Your changes were saved.', { type: 'success' });
+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'` `'success'` `'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.6",
+  "version": "0.1.8",
   "publishConfig": {
     "access": "public"
   },