@ahrowe/ui 0.14.0 → 0.15.0

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.0",
+  "version": "0.15.0",
   "publishConfig": {
     "access": "public"
   },
@@ -55,7 +55,7 @@
     "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",
+    "gc": "bash src/scripts/generateComponent.sh",
     "changeset": "changeset",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -84,7 +84,6 @@
     "@mona-health/react-input-mask": "^3.0.3",
     "classnames": "^2.5.1",
     "downshift": "^9.3.3",
-    "prop-types": "^15.8.1",
     "react-number-format": "^5.4.5",
     "zod": "^4.4.3"
   },
@@ -101,7 +100,6 @@
     "@types/node": "^25.9.1",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "@types/react-helmet": "^6.1.11",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/ui": "^4.1.7",