@ahrowe/ui 0.1.18 → 0.1.20

package/docs/TabHeader.md

@@ -0,0 +1,62 @@
+# TabHeader
+
+**When to use:** A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages. Each tab carries an icon plus an optional title and subtitle.
+
+**Import:** `import { TabHeader } from '@ahrowe/ui'`
+
+**Mobile behaviour:** On narrow screens (≤ 640px) only the active tab keeps its title and subtitle; every other tab collapses to just its icon.
+
+```tsx
+import { useState } from 'react';
+import { TabHeader } from '@ahrowe/ui';
+import type { TabHeaderTab } from '@ahrowe/ui';
+import { faUser, faBell, faGear } from '@fortawesome/free-solid-svg-icons';
+
+const TABS: TabHeaderTab[] = [
+  { id: 'profile', icon: faUser, title: 'Profile', subtitle: 'Your details' },
+  { id: 'notifications', icon: faBell, title: 'Notifications', subtitle: 'Email & push' },
+  { id: 'settings', icon: faGear, title: 'Settings' },        // title only
+];
+
+function Example() {
+  const [tab, setTab] = useState('profile');
+  return <TabHeader tabs={TABS} currentTab={tab} onChange={setTab} />;
+}
+
+// Icon-only tabs
+<TabHeader
+  tabs={[{ id: 'a', icon: faUser }, { id: 'b', icon: faGear }]}
+  currentTab={tab}
+  onChange={setTab}
+/>
+
+// Disabled tab — dimmed and not selectable
+<TabHeader
+  tabs={[
+    { id: 'a', icon: faUser, title: 'Profile' },
+    { id: 'b', icon: faGear, title: 'Billing', disabled: true },
+  ]}
+  currentTab={tab}
+  onChange={setTab}
+/>
+```
+
+**TabHeaderProps:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `tabs` | `TabHeaderTab[]` | The tabs to render, in order |
+| `currentTab` | `string` | `id` of the selected tab |
+| `onChange` | `(id: string) => void` | Called with the tab `id` when a different, enabled tab is clicked |
+
+**TabHeaderTab:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier, matched against `currentTab` |
+| `icon` | `IconDefinition` | FontAwesome icon (always visible, incl. mobile) |
+| `title` | `string` | Optional title next to the icon |
+| `subtitle` | `string` | Optional subtitle beneath the title |
+| `disabled` | `boolean` | Dim the tab and prevent selection |
+
+**Slots:** `root` `tab` `icon` `labels` `title` `subtitle`

package/docs/VirtualList.md

@@ -3,7 +3,7 @@
 **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'`
+**Types:** `import type { VirtualListProps, VirtualListColumn, VirtualListHandle } from '@ahrowe/ui'`
 
 ```tsx
 import { VirtualList } from '@ahrowe/ui';
@@ -105,4 +105,28 @@ const columns: VirtualListColumn<User>[] = [
 | `loadMoreThreshold` | `number` | Distance from bottom that triggers `onLoadMore` (default `100`) |
 | `isLoading` | `boolean` | Replaces list body with a full-height spinner |
 
+**Imperative handle (`ref`):**
+
+Pass a `ref` typed as `VirtualListHandle` to control the list imperatively:
+
+```tsx
+import { useRef } from 'react';
+import { VirtualList } from '@ahrowe/ui';
+import type { VirtualListHandle } from '@ahrowe/ui';
+
+const listRef = useRef<VirtualListHandle>(null);
+
+<VirtualList ref={listRef} items={items} columns={columns} height={600} />;
+
+listRef.current?.scrollToKey(user.id, { align: 'center' });
+```
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `scrollToIndex` | `(index, options?) => void` | Scroll so the row at `index` is visible. `options`: `{ align?: 'start' \| 'center' \| 'end'; behavior?: ScrollBehavior }` |
+| `scrollToKey` | `(key, options?) => void` | Scroll to the row whose `getItemKey` matches `key` (no-op if not found) |
+| `scrollToTop` | `(options?) => void` | Scroll back to the top |
+| `getScrollElement` | `() => HTMLDivElement \| null` | The underlying scroll container, for advanced use |
+| `recalculateColumns` | `() => void` | Re-measure `fit` columns on the next layout. Only needed after an out-of-band content change that doesn't flow through a new `items` array or `columns` set — those re-measure automatically, as does content first appearing in a cell |
+
 **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.18",
+  "version": "0.1.20",
   "publishConfig": {
     "access": "public"
   },