@poodle64/ui 2026.10.16 → 2026.10.18

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.10.16",
+	"version": "2026.10.18",
 	"description": "Household shared component layer: shadcn-svelte primitives (bits-ui) plus the composed page chrome every app builds its routes from, restyled by each app's @poodle64/design-tokens alias layer. One fix reaches every app.",
 	"type": "module",
 	"license": "MIT",
@@ -83,6 +83,7 @@
 		"@lucide/svelte": "^1.25.0",
 		"@tanstack/table-core": "^8.21.3",
 		"clsx": "^2.1.1",
+		"d3-force": "^3.0.0",
 		"esm-env": "^1.2.2",
 		"html-to-image": "^1.11.13",
 		"tailwind-merge": "^3.6.0",
@@ -97,6 +98,7 @@
 		"@tailwindcss/cli": "^4.3.2",
 		"@testing-library/jest-dom": "^7.0.0",
 		"@testing-library/svelte": "^5.4.2",
+		"@types/d3-force": "^3.0.10",
 		"@types/node": "^22.20.1",
 		"bits-ui": "^2.18.1",
 		"formsnap": "^2.0.1",
@@ -119,7 +121,7 @@
 		"registry:check": "node scripts/generate-registry.mjs --check",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"test": "pnpm run build && vitest run",
-		"test:browser": "pnpm run harness:build && node harness/drive.mjs",
+		"test:browser": "pnpm run harness:build && node harness/drive.mjs && node harness/graph.mjs",
 		"prepublishOnly": "pnpm run build",
 		"harness:build": "vite build --config harness/vite.config.ts && tailwindcss -i harness/harness.css -o harness/dist/app.css --minify",
 		"harness:serve": "python3 -m http.server 4180 --directory harness/dist"

package/registry/component-map.json

@@ -1,11 +1,11 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.10.16",
+		"version": "2026.10.18",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 69,
-		"situationCount": 19
+		"componentCount": 76,
+		"situationCount": 20
 	},
 	"situations": [
 		{
@@ -291,7 +291,7 @@
 		{
 			"key": "library-data",
 			"title": "Library data the app fetched",
-			"description": "The estate's shared document-library surfaces — a faceted catalogue, one collection's detail, one document's detail, a ranked search answer — rendered from plain props the app maps its own API responses into. The package never fetches and never routes: the app owns the query, the offset and every link. Configuration is the schema-driven half (SchemaForm); library data is fixed components because its shape is stable.",
+			"description": "The estate's shared document-library surfaces — a faceted catalogue, one collection's detail, one document's detail, a document to read with its contents, a ranked search answer — rendered from plain props the app maps its own API responses into. The package never fetches and never routes: the app owns the query, the offset and every link. Configuration is the schema-driven half (SchemaForm); library data is fixed components because its shape is stable.",
 			"components": [
 				{
 					"name": "LibraryBrowse",
@@ -314,6 +314,13 @@
 					"props": "document, loading?, error?, collectionHref?, onOpenCollection?, actions?, children?",
 					"insteadOf": "a bespoke document page: identity dl, locations, tags and memberships hand-laid-out per app"
 				},
+				{
+					"name": "DocumentReader",
+					"dir": "document-reader",
+					"import": "@poodle64/ui/document-reader",
+					"props": "title?, subtitle?, breadcrumbs?, meta?, actions?, html?, children?, contents?, contentsLabel?, aside?, footer?, loading?, error?, onRetry?",
+					"insteadOf": "a hand-built markdown page: its own h1, back row, table of contents, scroll-spy and max-w-4xl; or a document body in a box under DocumentDetail"
+				},
 				{
 					"name": "SearchResults",
 					"dir": "search-results",
@@ -344,10 +351,24 @@
 				}
 			]
 		},
+		{
+			"key": "relations-between-things",
+			"title": "Who is connected to what",
+			"description": "People, organisations, sources or any entities as nodes and their relations as edges: a live, explorable network rather than a list of links.",
+			"components": [
+				{
+					"name": "GraphCanvas",
+					"dir": "graph-canvas",
+					"import": "@poodle64/ui/graph-canvas",
+					"props": "nodes, edges, kinds?, selected?, hiddenKinds?, directed?, onselect?, onactivate?, detail?",
+					"insteadOf": "a hand-built canvas or SVG force layout, or a graph library's own chrome and colours"
+				}
+			]
+		},
 		{
 			"key": "page-frame",
 			"title": "The frame every route shares",
-			"description": "The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column, a foldable working list beside the page's own content.",
+			"description": "The standing chrome — the app shell and its nav, the one page-title treatment and its trail, the page's own container and sections, the persistent right-hand context column, a foldable working list beside the page's own content.",
 			"components": [
 				{
 					"name": "AppShell",
@@ -377,6 +398,27 @@
 					"props": "title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?",
 					"insteadOf": "a hand-written <h1> and title bar (the drift gate fails this)"
 				},
+				{
+					"name": "Breadcrumbs",
+					"dir": "breadcrumbs",
+					"import": "@poodle64/ui/breadcrumbs",
+					"props": "items, label?",
+					"insteadOf": "a hand-written chevron trail in PageHeader's breadcrumbs snippet; PageHeader takes the same items as `breadcrumbs={[…]}`"
+				},
+				{
+					"name": "PageContainer",
+					"dir": "page-container",
+					"import": "@poodle64/ui/page-container",
+					"props": "children",
+					"insteadOf": "a per-page wrapper picking its own vertical rhythm (space-y-6, gap-10, …)"
+				},
+				{
+					"name": "PageSection",
+					"dir": "page-section",
+					"import": "@poodle64/ui/page-section",
+					"props": "title, level?, description?, count?, actions?, children?, id?",
+					"insteadOf": "a hand-styled section heading (an uppercase kicker, text-lg font-semibold, a display h2) and its own gap to the content under it"
+				},
 				{
 					"name": "RecordSwitcher",
 					"dir": "record-switcher",
@@ -489,6 +531,13 @@
 					"props": "message?",
 					"insteadOf": "a bare spinner or 'Loading…' you place by hand"
 				},
+				{
+					"name": "ContentSkeleton",
+					"dir": "content-skeleton",
+					"import": "@poodle64/ui/content-skeleton",
+					"props": "shape?, count?, label?",
+					"insteadOf": "bare Skeleton boxes sized by hand (h-44 rounded-xl, h-24) standing in for a list, tiles or a document body while the page's header is already drawn"
+				},
 				{
 					"name": "ErrorState",
 					"dir": "error-state",
@@ -576,6 +625,10 @@
 			"dir": "separator",
 			"import": "@poodle64/ui/separator"
 		},
+		{
+			"dir": "sheet",
+			"import": "@poodle64/ui/sheet"
+		},
 		{
 			"dir": "skeleton",
 			"import": "@poodle64/ui/skeleton"

package/registry/component-map.md

@@ -1,7 +1,7 @@
 # @poodle64/ui — situation → component map
 
 <!-- GENERATED by scripts/generate-registry.mjs from scripts/situations.json + package source. DO NOT EDIT. -->
-Generated from `@poodle64/ui@2026.10.16`. 69 components, 19 situations.
+Generated from `@poodle64/ui@2026.10.18`. 76 components, 20 situations.
 
 **Read this before writing a `<div>`.** Find the SITUATION you are in below, then compose the component named for it — do not hand-build it from raw `Card` or utility classes. Import is `import { Name } from '<import path>'`. Props marked `?` are optional. This map is the retrieval step the [`frontend-design` skill] makes mandatory; the [CHI 2026 study] measured composing-from-a-registry at 95% design-system compliance against 71% for writing the CSS from a prose style guide.
 
@@ -128,13 +128,14 @@ _A config object whose shape arrives at runtime as a JSON Schema plus a JSON For
 
 ## Library data the app fetched
 
-_The estate's shared document-library surfaces — a faceted catalogue, one collection's detail, one document's detail, a ranked search answer — rendered from plain props the app maps its own API responses into. The package never fetches and never routes: the app owns the query, the offset and every link. Configuration is the schema-driven half (SchemaForm); library data is fixed components because its shape is stable._
+_The estate's shared document-library surfaces — a faceted catalogue, one collection's detail, one document's detail, a document to read with its contents, a ranked search answer — rendered from plain props the app maps its own API responses into. The package never fetches and never routes: the app owns the query, the offset and every link. Configuration is the schema-driven half (SchemaForm); library data is fixed components because its shape is stable._
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
 | `LibraryBrowse` | `@poodle64/ui/library-browse` | `documents, facets?, query?, total?, offset?, limit?, loading?, error?, onQueryChange?, onFacetChange?, onPageChange?, documentHref?, onOpenDocument?, toolbar?` | a hand-built catalogue page: search box, facet rail, filter chips, results table and pager re-derived per app |
 | `CollectionDetail` | `@poodle64/ui/collection-detail` | `collection, stats?, documents?, documentsTotal?, loading?, error?, documentsLoading?, documentsError?, onPageChange?, documentHref?, onOpenDocument?, actions?, children?` | a bespoke collection page assembled from raw Card, a hand-built table and its own stat rows |
 | `DocumentDetail` | `@poodle64/ui/document-detail` | `document, loading?, error?, collectionHref?, onOpenCollection?, actions?, children?` | a bespoke document page: identity dl, locations, tags and memberships hand-laid-out per app |
+| `DocumentReader` | `@poodle64/ui/document-reader` | `title?, subtitle?, breadcrumbs?, meta?, actions?, html?, children?, contents?, contentsLabel?, aside?, footer?, loading?, error?, onRetry?` | a hand-built markdown page: its own h1, back row, table of contents, scroll-spy and max-w-4xl; or a document body in a box under DocumentDetail |
 | `SearchResults` | `@poodle64/ui/search-results` | `results, query?, total?, loading?, error?, resultHref?, onOpen?, onRetry?` | a hand-built ranked hit list minting its own highlight and relevance styling |
 
 ## A document a machine read, with evidence outlined
@@ -146,9 +147,17 @@ _One page at a time, fitted to its pane both ways so an A4 statement and a tall
 | `PageCanvas` | `@poodle64/ui/page-canvas` | `pageCount, page, currentPage?, regions?, lookedRegions?, activeRegionId?, focusedRegionId?, zoom?` | a hand-built page viewer per app (godswood's DocumentViewer, pebblestone's PdfViewer) each re-deriving fit/zoom/pan, now with no way to outline what was read (#839) |
 | `DocumentPane` | `@poodle64/ui/document-pane` | `title, subtitle?, pages?, pageCount?, page?, currentPage?, zoom?, actions?, onClose?` | a PageCanvas framed by hand with its own title row, download and close; the pane the record page opens a document in, beside the column or in its place |
 
+## Who is connected to what
+
+_People, organisations, sources or any entities as nodes and their relations as edges: a live, explorable network rather than a list of links._
+
+| Component | Import | Key props | Reach for it instead of |
+| --- | --- | --- | --- |
+| `GraphCanvas` | `@poodle64/ui/graph-canvas` | `nodes, edges, kinds?, selected?, hiddenKinds?, directed?, onselect?, onactivate?, detail?` | a hand-built canvas or SVG force layout, or a graph library's own chrome and colours |
+
 ## The frame every route shares
 
-_The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column, a foldable working list beside the page's own content._
+_The standing chrome — the app shell and its nav, the one page-title treatment and its trail, the page's own container and sections, the persistent right-hand context column, a foldable working list beside the page's own content._
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
@@ -156,6 +165,9 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | `ShellControls` | `@poodle64/ui/app-shell` | `children` | a scope row (entity, financial year, chart/table) hand-placed above the page body; the shell's top bar carries it |
 | `Segmented` | `@poodle64/ui/segmented` | `value, options, label, size?` | a hand-built row of aria-pressed buttons for a small fixed choice |
 | `PageHeader` | `@poodle64/ui/page-header` | `title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?` | a hand-written <h1> and title bar (the drift gate fails this) |
+| `Breadcrumbs` | `@poodle64/ui/breadcrumbs` | `items, label?` | a hand-written chevron trail in PageHeader's breadcrumbs snippet; PageHeader takes the same items as `breadcrumbs={[…]}` |
+| `PageContainer` | `@poodle64/ui/page-container` | `children` | a per-page wrapper picking its own vertical rhythm (space-y-6, gap-10, …) |
+| `PageSection` | `@poodle64/ui/page-section` | `title, level?, description?, count?, actions?, children?, id?` | a hand-styled section heading (an uppercase kicker, text-lg font-semibold, a display h2) and its own gap to the content under it |
 | `RecordSwitcher` | `@poodle64/ui/record-switcher` | `name, groups, current?, noun?, placeholder?, icon?, all?, pages?, separator?` | a bare record name beside a small chevrons button in the top bar, and a dropdown of names with no search, groups or thumbnails; the record's own page tabs come with it |
 | `ContextColumn` | `@poodle64/ui/context-column` | `stats?, statsTitle?, statsInfo?, detail?, title?, subtitle?, onClose?, children?, documentPane?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane; on a record page, the one opened item (title, close, an inner scroll) and its DocumentPane, in the column's place or beside it once the page's row has room |
 | `ListShell` | `@poodle64/ui/list-shell` | `title, children, label?, open?, actions?` | a module hand-rolling its own foldable second column beside the rail — a queue, an inbox, a working list |
@@ -190,11 +202,12 @@ _A surface with nothing to show yet, still loading, or that failed to load — t
 | --- | --- | --- | --- |
 | `EmptyState` | `@poodle64/ui/empty-state` | `title, icon?, description?, action?` | a hand-centred 'Nothing here' message |
 | `LoadingState` | `@poodle64/ui/loading-state` | `message?` | a bare spinner or 'Loading…' you place by hand |
+| `ContentSkeleton` | `@poodle64/ui/content-skeleton` | `shape?, count?, label?` | bare Skeleton boxes sized by hand (h-44 rounded-xl, h-24) standing in for a list, tiles or a document body while the page's header is already drawn |
 | `ErrorState` | `@poodle64/ui/error-state` | `message, action?` | a hand-built error message with a retry button |
 
 ## Primitives you already know
 
 _Standard shadcn-svelte / bits-ui primitives — reach for them the same way; no situation lookup needed. Import each from its path below._
 
-`@poodle64/ui/alert` · `@poodle64/ui/alert-dialog` · `@poodle64/ui/avatar` · `@poodle64/ui/badge` · `@poodle64/ui/button` · `@poodle64/ui/card` · `@poodle64/ui/checkbox` · `@poodle64/ui/command` · `@poodle64/ui/data-table` · `@poodle64/ui/dialog` · `@poodle64/ui/dropdown-menu` · `@poodle64/ui/input` · `@poodle64/ui/input-group` · `@poodle64/ui/label` · `@poodle64/ui/password-input` · `@poodle64/ui/popover` · `@poodle64/ui/progress` · `@poodle64/ui/select` · `@poodle64/ui/separator` · `@poodle64/ui/skeleton` · `@poodle64/ui/sonner` · `@poodle64/ui/switch` · `@poodle64/ui/table` · `@poodle64/ui/tabs` · `@poodle64/ui/textarea` · `@poodle64/ui/tooltip`
+`@poodle64/ui/alert` · `@poodle64/ui/alert-dialog` · `@poodle64/ui/avatar` · `@poodle64/ui/badge` · `@poodle64/ui/button` · `@poodle64/ui/card` · `@poodle64/ui/checkbox` · `@poodle64/ui/command` · `@poodle64/ui/data-table` · `@poodle64/ui/dialog` · `@poodle64/ui/dropdown-menu` · `@poodle64/ui/input` · `@poodle64/ui/input-group` · `@poodle64/ui/label` · `@poodle64/ui/password-input` · `@poodle64/ui/popover` · `@poodle64/ui/progress` · `@poodle64/ui/select` · `@poodle64/ui/separator` · `@poodle64/ui/sheet` · `@poodle64/ui/skeleton` · `@poodle64/ui/sonner` · `@poodle64/ui/switch` · `@poodle64/ui/table` · `@poodle64/ui/tabs` · `@poodle64/ui/textarea` · `@poodle64/ui/tooltip`