@ahrowe/ui 0.14.1 → 0.15.0

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

@@ -16,6 +16,13 @@ export interface KanbanColumnDef {
      * Use for a workflow rule like "cards in Done can't be moved back out."
      */
     disabled?: boolean;
+    /**
+     * Whether more items exist for this column beyond what's currently in `itemIds` — enables the
+     * scroll-triggered `onLoadMore` request. Only meaningful alongside `KanbanBoardProps.onLoadMore`;
+     * a column without it never asks for more regardless of this flag. Set `false` (or omit) once
+     * the column's source is exhausted to stop asking.
+     */
+    hasMore?: boolean;
 }
 export type KanbanBoardSlots = 'dragOverlay';
 export interface KanbanBoardProps<T = unknown> extends HtmlProps {
@@ -70,12 +77,33 @@ export interface KanbanBoardProps<T = unknown> extends HtmlProps {
      * via `ThemeProvider`'s `variables`, or per board via `style`.
      */
     collapseEmptyColumns?: boolean;
+    /**
+     * Bounds each column's height (any CSS length, e.g. `'70vh'`, `'600px'`) and makes its card
+     * list scroll independently once content overflows, instead of growing the whole page. Leave
+     * unset for the default unbounded height. Required for `onLoadMore` to ever trigger, since an
+     * unbounded column never scrolls.
+     */
+    columnMaxHeight?: string;
+    /**
+     * Called with a column's `id` when that column has `hasMore` set and its card list is scrolled
+     * within `loadMoreThreshold` of the bottom — fetch and append the next page of items for it.
+     * `KanbanColumn` tracks its own in-flight state per column (shown as a spinner at the bottom of
+     * the list), so overlapping calls for the same column are never made concurrently. Also
+     * retried automatically if a loaded batch doesn't fill the column's visible height, since a
+     * column shorter than its own viewport never generates a scroll event to trigger a next page.
+     */
+    onLoadMore?: (columnId: string) => void | Promise<void>;
+    /**
+     * Distance in px from the bottom of a column's scroll area that triggers `onLoadMore` (default
+     * `100`, matching `VirtualList`'s `loadMoreThreshold`).
+     */
+    loadMoreThreshold?: number;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<KanbanBoardSlots>;
     styles?: SlotStyles<KanbanBoardSlots>;
 }
-export type KanbanColumnSlots = 'header' | 'items' | 'count' | 'placeholder' | 'actions';
+export type KanbanColumnSlots = 'header' | 'items' | 'count' | 'placeholder' | 'actions' | 'loadingIndicator';
 export interface KanbanColumnProps extends HtmlProps {
     id: string;
     title: string;

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

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

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

@@ -0,0 +1,2 @@
+import { TimelineProps } from './timeline.types';
+export default function Timeline({ items, alignment, className, style, classNames, styles: slotStyles, ...rest }: TimelineProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,51 @@
+import { default as React } from 'react';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+/** Layout of entries relative to the connecting line. */
+export declare enum TimelineAlignment {
+    /** Line and markers on the left, content to the right (the default). */
+    Left = "left",
+    /** Line and markers on the right, content to the left. */
+    Right = "right",
+    /** Line down the center, entries alternating left/right. */
+    Alternate = "alternate"
+}
+/** Semantic colour for an entry's marker, matching the theme's status colours. */
+export declare enum TimelineItemStatus {
+    Default = "default",
+    Primary = "primary",
+    Success = "success",
+    Warn = "warn",
+    Error = "error"
+}
+export type TimelineSlots = 'root' | 'item' | 'marker' | 'dot' | 'connector' | 'content' | 'title' | 'description' | 'timestamp';
+export interface TimelineItem {
+    /** Stable identity for the entry, used as its React key. Falls back to its array index when omitted; pass one whenever `items` can be reordered or have entries prepended (e.g. a live "newest first" audit log), so React doesn't misattribute row state across the shift. */
+    id?: string | number;
+    /** Primary label for the entry. */
+    title: React.ReactNode;
+    /** Secondary line under the title. */
+    description?: React.ReactNode;
+    /** Rendered next to the title, e.g. a date or relative time ("2 hours ago"). */
+    timestamp?: React.ReactNode;
+    /** FontAwesome icon shown in the marker instead of a plain dot. */
+    icon?: IconDefinition;
+    /** Semantic marker colour (default `Default`). */
+    status?: TimelineItemStatus;
+    /** Extra content rendered under the description, e.g. a diff, an attachment, an actor avatar. */
+    content?: React.ReactNode;
+    /** Makes the whole entry clickable (e.g. to open the full record), rendering it as an accessible button. */
+    onClick?: (event: React.MouseEvent<HTMLDivElement>) => void;
+    /** Disables the entry: never clickable, dimmed. Only relevant alongside `onClick`. */
+    disabled?: boolean;
+}
+export interface TimelineProps extends HtmlProps {
+    /** The entries to render, in display order (typically newest first for an audit log). */
+    items?: TimelineItem[];
+    /** Layout of entries relative to the connecting line (default `Left`). */
+    alignment?: TimelineAlignment;
+    className?: string;
+    style?: React.CSSProperties;
+    classNames?: SlotClassNames<TimelineSlots>;
+    styles?: SlotStyles<TimelineSlots>;
+}

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

@@ -47,6 +47,8 @@ export { default as Dropdown } from './common/dropdown';
 export * from './common/dropdown';
 export { default as EmptyState } from './common/emptyState';
 export * from './common/emptyState';
+export { default as ErrorBoundary } from './common/errorBoundary';
+export * from './common/errorBoundary';
 export { default as Fab } from './common/fab';
 export * from './common/fab';
 export { default as FloatingMenu } from './common/floatingMenu';
@@ -117,6 +119,8 @@ export * from './common/themeProvider';
 export { useTheme } from './common/themeProvider/useTheme';
 export { default as TimeInput } from './common/timeInput';
 export * from './common/timeInput';
+export { default as Timeline } from './common/timeline';
+export * from './common/timeline';
 export { default as ToastProvider } from './common/toast';
 export * from './common/toast';
 export { default as Tooltip } from './common/tooltip';

package/docs/CLAUDE.md

@@ -117,6 +117,7 @@ Slot keys per component are documented in each component's doc file below.
 @Dropdown.md
 @DropZone.md
 @EmptyState.md
+@ErrorBoundary.md
 @Fab.md
 @FloatingMenu.md
 @FormValidator.md
@@ -154,6 +155,7 @@ Slot keys per component are documented in each component's doc file below.
 @Textarea.md
 @ThemeProvider.md
 @TimeInput.md
+@Timeline.md
 @Toast.md
 @Tooltip.md
 @VirtualList.md

package/docs/ErrorBoundary.md

@@ -0,0 +1,93 @@
+# ErrorBoundary
+
+**When to use:** Wrap any subtree whose render errors shouldn't take down the rest of the app — a widget, a route, a third-party embed, a list row. It catches JavaScript errors thrown while rendering descendants (via React's `getDerivedStateFromError` / `componentDidCatch`) and swaps in a fallback UI instead of unmounting the whole tree. Only errors thrown during rendering, in lifecycle methods, or in constructors of the tree below it are caught — event handlers, async code, and errors in the boundary itself are not, same as any React error boundary.
+
+**Import:** `import { ErrorBoundary } from '@ahrowe/ui'`
+
+```tsx
+import { ErrorBoundary } from '@ahrowe/ui';
+
+// Basic — default fallback with a "Try again" button
+<ErrorBoundary>
+  <Widget />
+</ErrorBoundary>
+
+// Report to your error tracker, and re-arm whatever caused the crash on reset
+<ErrorBoundary
+  onError={(error, errorInfo) => reportToSentry(error, errorInfo)}
+  onReset={() => setWidgetKey((k) => k + 1)}
+>
+  <Widget />
+</ErrorBoundary>
+
+// Custom copy, no stack-trace section (e.g. for a small inline widget)
+<ErrorBoundary
+  title="Widget crashed"
+  description="This panel failed to load. The rest of the page is unaffected."
+  hideStack
+>
+  <Widget />
+</ErrorBoundary>
+
+// Fully custom fallback UI — render function receives the error and a reset callback
+<ErrorBoundary
+  fallback={({ error, resetErrorBoundary }) => (
+    <div>
+      Something broke: {error.message}
+      <button onClick={resetErrorBoundary}>Retry</button>
+    </div>
+  )}
+>
+  <Widget />
+</ErrorBoundary>
+
+// Auto-reset when inputs the crash depends on change (e.g. a route or record id)
+<ErrorBoundary resetKeys={[recordId]}>
+  <RecordDetail id={recordId} />
+</ErrorBoundary>
+
+// Translated strings for a non-English app — title/description are their own
+// props (see above); labels covers everything else the built-in fallback renders
+<ErrorBoundary
+  title="Etwas ist schiefgelaufen"
+  labels={{
+    stackTrace: 'Stapelverfolgung',
+    copy: 'Kopieren',
+    copied: 'Kopiert',
+    reset: 'Erneut versuchen',
+    copySuccessToast: 'Stapelverfolgung kopiert',
+    copyErrorToast: 'Kopieren fehlgeschlagen',
+  }}
+>
+  <Widget />
+</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".
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `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 |
+| `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 |
+| `resetKeys` | `unknown[]` | When any value in this array changes while the boundary is showing an error, it resets automatically — mirrors the common `react-error-boundary` pattern |
+| `hideStack` | `boolean` | Hide the collapsible stack-trace section. Default `false` |
+
+**`ErrorBoundaryLabels`:**
+
+| 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 |
+| `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 |
+
+**Slots:** `root` `header` `badge` `icon` `title` `description` `stack` `stackHeader` `stackLabel` `stackTrace` `copyButton` `actions` `resetButton`

package/docs/KanbanBoard.md

@@ -135,6 +135,38 @@ const columnsWithLock: KanbanColumnDef[] = [
   collapseEmptyColumns={false}
   onChange={(updatedColumns) => setColumns(updatedColumns)}
 />
+
+// Bound each column's height and let its card list scroll independently, instead
+// of growing the whole page — useful once a column can hold a lot of cards
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  columnMaxHeight="70vh"
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Paginate a column instead of loading everything up front — mark it `hasMore`
+// and fetch/append the next page in `onLoadMore` once it's scrolled near the
+// bottom. Requires `columnMaxHeight`, since an unbounded column never scrolls.
+// KanbanBoard tracks its own in-flight state per column (shown as a spinner at
+// the bottom of the list) and retries automatically if a page doesn't fill the
+// column's visible height, so pagination doesn't dead-end on a short first batch.
+const columnsPaged: KanbanColumnDef[] = [
+  { id: 'done', title: 'Done', itemIds: doneTaskIds, hasMore: doneHasMore },
+];
+
+<KanbanBoard
+  columns={columnsPaged}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  columnMaxHeight="70vh"
+  onLoadMore={async (columnId) => {
+    const nextPage = await fetchNextPage(columnId);
+    appendItemsToColumn(columnId, nextPage); // your own state update
+  }}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
 ```
 
 **Keyboard support:** cards are focusable and can be picked up and moved with the keyboard — Space or Enter to pick up, Space or Enter again to drop, Escape to cancel (reverts to the original position). Arrow keys move the card: Up/Down reorders within its current column; Left/Right moves it into the adjacent column, landing on the nearest card there (or the column itself, if it's empty). This uses a board-aware coordinate getter rather than `dnd-kit`'s generic `sortableKeyboardCoordinates`, which — across multiple per-column `SortableContext`s — can't reliably tell "next card in this column" from "some other column's droppable" and ends up mixing up Up/Down and Left/Right. With `reorderableColumns`, a column's header is focusable the same way — Space/Enter to pick it up, Left/Right to move it, Up/Down does nothing (columns are a single row).
@@ -158,6 +190,9 @@ const columnsWithLock: KanbanColumnDef[] = [
 | `renderColumnActions` | `(column: KanbanColumnDef) => ReactNode` | Custom actions rendered in a column's header, next to its title (e.g. an "add card" button, a column menu) |
 | `reorderableColumns` | `boolean` | Allow whole columns to be reordered by dragging their header, alongside card dragging (default `false`) |
 | `collapseEmptyColumns` | `boolean` | Shrink a column to a narrow strip once it has no cards (default `true`). Set `false` to keep every column the same width regardless of card count. The collapsed width is set via `--kanban-empty-column-width` (falls back to `140px`) — override it theme-wide via `ThemeProvider`, or per board via `style` |
+| `columnMaxHeight` | `string` | Bounds each column's height (any CSS length, e.g. `'70vh'`) and makes its card list scroll independently once content overflows, instead of growing the whole page. Unset by default (unbounded height). Required for `onLoadMore` to ever trigger |
+| `onLoadMore` | `(columnId: string) => void \| Promise<void>` | Called when a column with `hasMore` is scrolled within `loadMoreThreshold` of the bottom — fetch and append the next page for that column. Tracked per column, so overlapping calls for the same column are never made concurrently; retried automatically if a loaded batch doesn't fill the column's own visible height |
+| `loadMoreThreshold` | `number` | Distance in px from the bottom of a column's scroll area that triggers `onLoadMore` (default `100`, matching `VirtualList`) |
 | `id` / `role` / `aria-*` / `data-*` | | Passed through to the root element |
 
 `KanbanColumn`'s own props accept the same `id` / `role` / `aria-*` / `data-*` pass-through on its root element.
@@ -171,10 +206,11 @@ const columnsWithLock: KanbanColumnDef[] = [
   itemIds: string[];
   maxItems?: number; // work-in-progress limit — display-only, see above
   disabled?: boolean; // freezes the column — cards inside can't be dragged, nothing can drop in
+  hasMore?: boolean; // more items exist beyond itemIds — enables onLoadMore, see above
 }
 ```
 
 **Note on item ids:** don't give a card an id starting with `column-` — the board uses that prefix internally to identify a column's own droppable (the empty space above/below its cards) versus a specific card. A colliding card id is silently misread as a column reference, and drops involving it silently no-op instead of throwing, so the bug can be easy to miss.
 
 **Slots (KanbanBoard):** `dragOverlay`  
-**Slots (KanbanColumn):** `header` `items` `count` (the `count/maxItems` badge, only rendered when `maxItems` is set) `placeholder` (the `renderEmptyColumn` wrapper, only rendered when the column has no cards and `renderEmptyColumn` is set) `actions` (the `renderColumnActions` wrapper, only rendered when `renderColumnActions` is set)
+**Slots (KanbanColumn):** `header` `items` `count` (the `count/maxItems` badge, only rendered when `maxItems` is set) `placeholder` (the `renderEmptyColumn` wrapper, only rendered when the column has no cards and `renderEmptyColumn` is set) `actions` (the `renderColumnActions` wrapper, only rendered when `renderColumnActions` is set) `loadingIndicator` (the spinner shown while an `onLoadMore` request for that column is in flight)

package/docs/Timeline.md

@@ -0,0 +1,127 @@
+# Timeline
+
+**When to use:** A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs. Each entry can carry a title, timestamp, description, an icon or status colour, and arbitrary extra content.
+
+**Import:** `import { Timeline, TimelineAlignment, TimelineItemStatus } from '@ahrowe/ui'`
+**Types:** `import type { TimelineItem, TimelineProps } from '@ahrowe/ui'`
+
+**Enums:**
+- `TimelineAlignment`: `Left` (default) | `Right` | `Alternate`
+- `TimelineItemStatus`: `Default` (default) | `Primary` | `Success` | `Warn` | `Error`
+
+```tsx
+import { Timeline, TimelineItemStatus } from '@ahrowe/ui';
+import type { TimelineItem } from '@ahrowe/ui';
+
+const items: TimelineItem[] = [
+  { title: 'Invoice created', description: 'by Jane Doe', timestamp: '09:12' },
+  { title: 'Invoice sent to client', description: 'via email', timestamp: '09:15' },
+  { title: 'Payment received', status: TimelineItemStatus.Success, timestamp: '2 days later' },
+  { title: 'Invoice closed', status: TimelineItemStatus.Success, timestamp: 'Today' },
+];
+
+// Default: left-aligned line and markers, content to the right
+<Timeline items={items} />
+
+// Icon markers instead of plain dots
+import { faUserPlus, faCheck } from '@fortawesome/free-solid-svg-icons';
+<Timeline
+  items={[
+    { title: 'Account created', icon: faUserPlus, timestamp: 'Mon' },
+    { title: 'Email verified', icon: faCheck, status: TimelineItemStatus.Success, timestamp: 'Wed' },
+  ]}
+/>
+
+// Right-aligned: line and markers on the right, content on the left
+import { TimelineAlignment } from '@ahrowe/ui';
+<Timeline items={items} alignment={TimelineAlignment.Right} />
+
+// Alternate: entries alternate either side of a centered line
+<Timeline items={items} alignment={TimelineAlignment.Alternate} />
+
+// Extra content per entry: a diff, an attachment, an actor avatar
+<Timeline
+  items={[
+    {
+      title: 'Deploy #128 started',
+      description: 'main @ a93d12d',
+      timestamp: '14:02',
+      content: <p>Triggered by Jon Snow.</p>,
+    },
+  ]}
+/>
+
+// Clickable entries: e.g. open the full audit log record in a Modal.
+// An item without onClick stays a plain, non-interactive row.
+import { Modal } from '@ahrowe/ui';
+
+function AuditLog() {
+  const [selected, setSelected] = useState<(typeof items)[number] | null>(null);
+  return (
+    <>
+      <Timeline
+        items={items.map((entry) => ({ ...entry, onClick: () => setSelected(entry) }))}
+      />
+      <Modal isOpen={selected != null} title={selected?.title} onClose={() => setSelected(null)}>
+        {selected?.description}
+      </Modal>
+    </>
+  );
+}
+
+// Lock an individual entry: dimmed, never clickable, even with onClick set
+<Timeline
+  items={[
+    { title: 'Archived entry', onClick: () => openDetail(), disabled: true },
+  ]}
+/>
+```
+
+**TimelineItem:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string \| number` | Stable identity used as the entry's React key. Falls back to its array index when omitted; pass one whenever `items` can be reordered or have entries prepended (e.g. a live "newest first" audit log) |
+| `title` | `ReactNode` | Primary label for the entry |
+| `description` | `ReactNode` | Secondary line under the title |
+| `timestamp` | `ReactNode` | Rendered next to the title, e.g. a date or relative time ("2 hours ago") |
+| `icon` | `IconDefinition` | FontAwesome icon shown in the marker instead of a plain dot |
+| `status` | `TimelineItemStatus` | Semantic marker colour (default `Default`) |
+| `content` | `ReactNode` | Extra content rendered under the description, e.g. a diff, an attachment, an actor avatar |
+| `onClick` | `(event: MouseEvent<HTMLDivElement>) => void` | Makes the whole entry clickable, rendering it as an accessible button (`role="button"`, focusable, click and Enter both fire it). Omit to render a plain, non-interactive row |
+| `disabled` | `boolean` | Disables the entry: never clickable, dimmed. Only relevant alongside `onClick` |
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `TimelineItem[]` | The entries to render, in display order (typically newest first for an audit log) |
+| `alignment` | `TimelineAlignment` | Layout of entries relative to the connecting line (default `Left`) |
+
+**Theming:** these are theme variables (typed on `ThemeVariables`). Set them theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`, without fighting specificity. Each falls back to a built-in default when unset:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--timeline-dot-size` | `14px` |
+| `--timeline-dot-color` | `var(--primary-color)` |
+| `--timeline-dot-border` | `var(--background)` |
+| `--timeline-line-color` | `var(--border-color)` |
+| `--timeline-line-thickness` | `2px` |
+| `--timeline-gap` | `16px` (gap between marker column and content) |
+| `--timeline-item-gap` | `20px` (vertical gap between entries) |
+| `--timeline-icon-dot-size` | `28px` (marker size when an entry has `icon`) |
+
+`TimelineItemStatus` values other than `Default` resolve directly to the matching theme colour (`--primary-color`, `--success-color`, `--warn-color`, `--error-color`) rather than a dedicated `--timeline-*` variable, so they always match the rest of the app's semantic colours.
+
+```tsx
+// Theme-wide, via ThemeProvider: thicker line, larger dots
+const theme: Theme = {
+  id: 'brand',
+  variables: {
+    '--timeline-line-thickness': '3px',
+    '--timeline-dot-size': '18px',
+  },
+};
+```
+
+**Slots:** `root` `item` `marker` `dot` `connector` `content` `title` `description` `timestamp`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "publishConfig": {
     "access": "public"
   },