Pattern reference — P1-P23 and groups A-K

Each page pattern maps to the inventory entries that build it, the gallery page of each entry and the file that holds the code. One pattern = one implementation (invariant 6). Sources: - Pattern names and groups: `findings/hms-pattern-audit/catalog.md` (plan-time audit, 2026-10-23). - Entry ids, groups and pattern tags: `ddx-web/src/inventory/entries/*.ts` (the ONE registry). The generated full reference is [inventory.md](/en/docs/inventory). - Gallery route: `ddx-web/src/app/[locale]/(app)/gallery/[entryId]/page.tsx`. A link `/[locale]/gallery/<id>` opens one entry; the docs route fills in the locale. Paths in the **File** column are relative to `ddx-web/src/`. Import rules (`ddx-web/src/inventory/README.md`): - A `page.tsx` imports components only from `@/inventory`. - A `'use client'` file imports from `@/inventory/client/<family>`, a client-safe slice (`data` · `entity` · `families` · `feedback` · `forms` · `portal` · `primitives` · `realtime` · `site`). The `@/inventory/client` barrel is deleted and `./ddx-manage.sh lint` rejects it. `@/inventory` pulls server data code (`use cache`) into the browser bundle. - `PdfDocument` / `renderPdfDocument` are server-only: import them from `@/inventory/media-server`, not `@/inventory/media`. - A component inside a family may import its siblings by path. - Tailwind: never `max-w-`/`min-w-`/`basis-` with `xs..xl` (they resolve to 4-32 px brand spacing); use the numeric scale (`max-w-112`). `./ddx-manage.sh lint` gates it. List stack (P2 list pages: `projects`, `members`, project tasks, `data`, `media`, `workspace`): `DataToolbar` (`components/data/DataToolbar.tsx`) is the action bar: primary create action, view switch, density, debounced search (`?q=`), facets (`?<field>=`, resets the page; from the descriptor's `filterFields`, single-select), group-by (`?group=<field>`). When rows are selected a bulk bar shows the count, clear, delete (confirm dialog, offered only when `can` holds `delete`; one request per id) and CSV export of the selection. Views via `?view=`: table, cards, compact list (`rows`), timeline (grouped by day, or by month when the span exceeds 31 days), board, calendar, export. An entity collection offers `timeline` only when it has a date field. Grouped table and list show collapsible headers with counts. The header is sticky, the pager is pinned to the bottom (`FOOTER_STICKY_CLASS`), and a pending navigation dims the rows and shows shimmer filler rows instead of a second scroller. `fill` is off by default in `PortalPageList`; a page can still set `fill` and `fillerRows` on `DataTable`. Files: `components/data/{DataTable,DataTableList,DataToolbar,Timeline, Pagination,grouping,export-rows,list-navigation,url-state}`, `components/entity/{EntityView,EntityViewClient, useEntityToolbar}`, `components/portal/templates/PortalPageList.tsx`, `lib/kernel/view-modes.ts`. Layout: page frames (`PortalPage` variants, `SITE_CONTAINER`, state screens) are `w-full` with the shell gutter; only long-form prose (`max-w-prose`), auth cards, call cards and print previews stay capped. Entity forms are `@container` grids: 1 column, 2 from `@3xl`, 3 from `@6xl`. Loading and consent: hard loads of `/portal/*` render `PortalShellSkeleton` (static header, side nav, status bar) instead of a shell-less skeleton. `CookieConsent` reopens from the site footer, the portal status bar and the portal user menu (`components/consent/{consent-store,CookieSettingsButton}`). ## Page patterns ### P1 — Portal shell and page wrapper | Entry | Group | File | |---|---|---| | [PortalShell](/en/gallery/PortalShell) | A | `components/portal/shell/PortalShell` | | [PortalHeader](/en/gallery/PortalHeader), [PortalSideNav](/en/gallery/PortalSideNav), [PortalMobileMenu](/en/gallery/PortalMobileMenu), [PortalMain](/en/gallery/PortalMain), [PortalStatusLine](/en/gallery/PortalStatusLine), [PortalFooter](/en/gallery/PortalFooter) | A | `components/portal/shell/` | | [PortalGlobalRecordingIndicator](/en/gallery/PortalGlobalRecordingIndicator) | A | `components/portal/shell/PortalGlobalRecordingIndicator` | | [PortalPage](/en/gallery/PortalPage) | B | `components/portal/page/PortalPage` | | `buildPortalPageMetadata` (helper/hook, not an entry) | B | `components/portal/page/types` | ### P2 — Page header and content frame | Entry | Group | File | |---|---|---| | [PortalPageHeader](/en/gallery/PortalPageHeader) | B | `components/portal/page/PortalPageHeader` | | [PortalPageContent](/en/gallery/PortalPageContent) | B | `components/portal/page/PortalPageContent` | | [PortalPageSideNav](/en/gallery/PortalPageSideNav) | B | `components/portal/page/PortalPageSideNav` | ### P3 — List page | Entry | Group | File | |---|---|---| | [PortalPageList](/en/gallery/PortalPageList) | B | `components/portal/templates/PortalPageList` | | [DataTable](/en/gallery/DataTable) | C | `components/data/DataTable` | | [FilterBar](/en/gallery/FilterBar), [SearchField](/en/gallery/SearchField), [Pagination](/en/gallery/Pagination) | C | `components/data/` | | [RowActions](/en/gallery/RowActions), [Badge](/en/gallery/Badge), `parseListState` (helper/hook, not an entry) | C | `components/data/` | ### P4 — List view modes (`?view=`) Descriptor entities (projects, tasks, members) get these modes from `EntityView` ([P23](#p23--entity-kernel-view-entityview-modes)); the entries below serve the non-descriptor lists. | Entry | Group | File | |---|---|---| | `resolveListView` (helper/hook, not an entry) | B | `components/portal/templates/list-view` | | [ViewModeSwitch](/en/gallery/ViewModeSwitch), [KanbanBoard](/en/gallery/KanbanBoard), [Timeline](/en/gallery/Timeline), `useListUrlState` (helper/hook, not an entry) | C | `components/data/` | ### P5 — Record page | Entry | Group | File | |---|---|---| | [PortalPageRecord](/en/gallery/PortalPageRecord) | B | `components/portal/templates/PortalPageRecord` | | [PortalRecordDelete](/en/gallery/PortalRecordDelete) | B | `components/portal/templates/PortalRecordDelete` | | [EntityLink](/en/gallery/EntityLink) | C | `components/data/entity-nav/EntityLink` | | [StatusPill](/en/gallery/StatusPill) | C | `components/data/StatusPill` | ### P6 — Workspace (entity rail + nested tabs) | Entry | Group | File | |---|---|---| | [PortalPageWorkspace](/en/gallery/PortalPageWorkspace) | B | `components/portal/templates/PortalPageWorkspace` | | `useWorkspaceRecord` (helper/hook, not an entry) | B | `components/portal/templates/PortalWorkspaceScope` | ### P7 — Form (create, edit, dialog, inline) A descriptor entity's form spec and zod schema come from the descriptor (`formSpecFor`, `zodFor` in `lib/kernel/form-spec`); `EntityView` `form` mode renders it ([P23](#p23--entity-kernel-view-entityview-modes)). | Entry | Group | File | |---|---|---| | [PortalPageForm](/en/gallery/PortalPageForm), [SitePageForm](/en/gallery/SitePageForm) | B | `components/families/form/PageForm` | | [EntityForm](/en/gallery/EntityForm) | D | `components/forms/EntityForm` | | [Field](/en/gallery/Field) | D | `components/forms/Field` | | [FileDropzone](/en/gallery/FileDropzone), [AvatarUpload](/en/gallery/AvatarUpload) | D | `components/forms/` | Uploads go to ddx-api through the BFF proxy; no presigned URL ([ADR 0011](/en/docs/adr/0011-media-proxy) supersedes [ADR 0010](/en/docs/adr/0010-media-path)). ### P8 — Print | Entry | Group | File | |---|---|---| | [PortalPagePrint](/en/gallery/PortalPagePrint) | I | `components/portal/viewer/PortalPagePrint` | | [PrintLayout](/en/gallery/PrintLayout) | I | `components/media/PrintLayout` | | [PdfDocument](/en/gallery/PdfDocument), `renderPdfDocument` (helper/hook, not an entry) | I | `components/media/PdfDocument` | | [QrCode](/en/gallery/QrCode) | I | `components/media/QrCode` | ### P9 — Document and media viewer | Entry | Group | File | |---|---|---| | [PortalPageViewer](/en/gallery/PortalPageViewer) | I | `components/portal/viewer/PortalPageViewer` | | [MediaViewer](/en/gallery/MediaViewer) | I | `components/media/MediaViewer` | | [DocumentViewer](/en/gallery/DocumentViewer) | I | `components/media/DocumentViewer` | | [PdfViewer](/en/gallery/PdfViewer) | I | `components/media/PdfViewer` | | [DicomViewer](/en/gallery/DicomViewer) | I | `components/media/DicomViewer` | ### P10 — Dashboard | Entry | Group | File | |---|---|---| | [PortalPageDashboard](/en/gallery/PortalPageDashboard) | B | `components/portal/templates/PortalPageDashboard` | | [StatTile](/en/gallery/StatTile), [KpiTile](/en/gallery/KpiTile) | C | `components/data/StatTile` | | [Chart](/en/gallery/Chart) | C | `components/data/Chart` | ### P11 — Calendar | Entry | Group | File | |---|---|---| | [PortalPageCalendar](/en/gallery/PortalPageCalendar) | B | `components/portal/templates/PortalPageCalendar` | ### P12 — Chat | Entry | Group | File | |---|---|---| | [PortalPageChat](/en/gallery/PortalPageChat) | B | `components/chat/PortalPageChat` | | [ChatSurface](/en/gallery/ChatSurface) | G | `components/chat/ChatSurface` | | [ChatMessage](/en/gallery/ChatMessage), [ChatComposer](/en/gallery/ChatComposer), [ChatThreadList](/en/gallery/ChatThreadList) | G | `components/chat/` | | [ToolCallCard](/en/gallery/ToolCallCard), [HitlCard](/en/gallery/HitlCard) | G | `components/chat/` | ### P13 — Voice assistant | Entry | Group | File | |---|---|---| | [PortalPageVoice](/en/gallery/PortalPageVoice) | H | `components/voice/PortalPageVoice` | | [VoiceAssistantPanel](/en/gallery/VoiceAssistantPanel) | H | `components/voice/VoiceAssistantPanel` | | [VoiceOrb](/en/gallery/VoiceOrb) | H | `components/voice/VoiceOrb` | | `useVoiceSession` (helper/hook, not an entry) | H | `components/voice/` | ### P14 — Streaming and real-time | Entry | Group | File | |---|---|---| | [PortalPageStream](/en/gallery/PortalPageStream) | B | `components/realtime/PortalPageStream` | | [StreamingText](/en/gallery/StreamingText) | F | `components/realtime/StreamingText` | | [SseBusProvider](/en/gallery/SseBusProvider) | F | `components/providers/SseProvider` | | `useStream` (helper/hook, not an entry) | F | `components/realtime/` | | [NotificationFeed](/en/gallery/NotificationFeed), [NotificationCount](/en/gallery/NotificationCount) | F | `components/realtime/NotificationFeed` | | [SseConnectionState](/en/gallery/SseConnectionState) | F | `components/realtime/SseConnectionState` | `StreamingText` is the ONE markdown engine. This docs route renders with it too. ### P15 — Recorder and audio | Entry | Group | File | |---|---|---| | [PortalPageRecorder](/en/gallery/PortalPageRecorder) | H | `components/audio/PortalPageRecorder` | | [AudioRecorder](/en/gallery/AudioRecorder), [AudioPlayer](/en/gallery/AudioPlayer) | H | `components/audio/` | | [Waveform](/en/gallery/Waveform), [DeviceSelector](/en/gallery/DeviceSelector), [TranscriptView](/en/gallery/TranscriptView) | H | `components/audio/` | | `useAudioCapture` (helper/hook, not an entry) | H | `components/audio/` | ### P16 — Video call room | Entry | Group | File | |---|---|---| | [PortalPageRoom](/en/gallery/PortalPageRoom) | B | `components/call/PortalPageRoom` | | [CallRoom](/en/gallery/CallRoom) | J | `components/call/CallSurface` | | `useCallRoom` (helper/hook, not an entry) | J | `components/call/hooks/use-call-room` | | `resolveCallAdapter` (helper/hook, not an entry) | J | `components/call/adapter` | ### P17 — Rich text editor | Entry | Group | File | |---|---|---| | [RichTextEditor](/en/gallery/RichTextEditor) | D | `components/forms/RichTextEditor` | ### P18 — Inbox | Entry | Group | File | |---|---|---| | [PortalPageInbox](/en/gallery/PortalPageInbox) | B | `components/portal/templates/PortalPageInbox` | ### P19 — Settings | Entry | Group | File | |---|---|---| | [PortalPageSettings](/en/gallery/PortalPageSettings) | B | `components/portal/templates/PortalPageSettings` | Registry-driven ([ADR 0014](/en/docs/adr/0014-unified-settings)). The page makes one read, `GET settings/effective`, and renders what ddx-api returns; it never merges tiers. - **Tiers.** Each key resolves user → org → platform default. A key shows in a section when the API returns that tier block for the caller's role. - **Sections.** Personal (user tier) and Organization (org tier); theme, density and motion are ordinary `portal.display.*` keys in those sections. A section with no keys is omitted. - **Editable vs read-only.** Keys with `editable.<tier>` render in one save form; the others render in a read-only form. Writes call `updateOrg` / `updateUser`, send the tier's `version`, and show a 409 inline. - **Source hint.** The first field of each key names the tier of the shown value (platform, org, your personal setting). A stored personal value has a "reset to organization" action (`resetUser`). - **Fields.** `SETTING_FIELDS` in `settings/_islands/model.ts` is exhaustive over the contract keys; labels live in `messages/{en,fr,de,es}/portal.json` under `pages.settings.keys.*`. File: `ddx-web/src/app/[locale]/(app)/portal/[orgSlug]/[role]/settings/` (`page.tsx`, `_islands/SettingsTierForm.tsx`, `_islands/model.ts`). ### P20 — Wizard | Entry | Group | File | |---|---|---| | [PortalPageWizard](/en/gallery/PortalPageWizard), [SitePageWizard](/en/gallery/SitePageWizard) | B | `components/families/wizard/PageWizard` | ### P21 — Redirects (alias, legacy, catch-all) | Entry | Group | File | |---|---|---| | `portalRedirect` (helper/hook, not an entry) | B | `lib/portal/redirect` | ### P22 — Empty, loading, error and not-found states | Entry | Group | File | |---|---|---| | [PortalPageEmpty](/en/gallery/PortalPageEmpty), [PortalPageLoading](/en/gallery/PortalPageLoading), [PortalPageError](/en/gallery/PortalPageError), [PortalPageNotFound](/en/gallery/PortalPageNotFound) | B | `components/portal/templates/PortalTemplateStates` | | [PortalLoading](/en/gallery/PortalLoading), [PortalNotFound](/en/gallery/PortalNotFound) | B | `components/portal/page/PortalStates` | | [PortalError](/en/gallery/PortalError) | B | `components/portal/page/PortalError` | | [PortalConnectionBanner](/en/gallery/PortalConnectionBanner) | A | `components/portal/shell/PortalConnectionBanner` | | [BrandLoader](/en/gallery/BrandLoader), [ClientBrandLoader](/en/gallery/ClientBrandLoader), [LoadingPanel](/en/gallery/LoadingPanel), [PageSkeleton](/en/gallery/PageSkeleton) | E | `components/feedback/brand-loader/` | | [EmptyState](/en/gallery/EmptyState) | E | `components/feedback/EmptyState` | | [Notify](/en/gallery/Notify), [NotifyBanner](/en/gallery/NotifyBanner) | E | `components/feedback/Notify` | | [Dialog](/en/gallery/Dialog), [ConfirmDialog](/en/gallery/ConfirmDialog), `useConfirmDialog` (helper/hook, not an entry), [Drawer](/en/gallery/Drawer) | E | `components/feedback/` | ### P23 — Entity kernel view (EntityView modes) One descriptor-driven component renders an entity in every mode; the mode is `?view=` (`table`, `cards`, `list`, `kanban`, `calendar`, `detail`, `form`, `wizard`, `print`, `export`). `kanban` needs a lifecycle enum, `calendar` a date field; an unoffered mode falls back to the first offered one. A record page adds the panels `EntityAccessPanel`, `EntityAttachmentsPanel` and `EntityAuditPanel`, which take the entity name. Server-rendered modes refresh through `EntityLiveRefresh` (SSE). Import from `@/inventory/entity`. Guide: [entity-kernel.md](/en/docs/entity-kernel). | Entry | Group | File | |---|---|---| | `EntityView`, `FieldValue` | C | `components/entity/` | | `EntityAccessPanel`, `EntityAttachmentsPanel`, `EntityAuditPanel` | C | `components/entity/` | | view-mode rules (`ENTITY_VIEW_MODES`, `isEntityViewMode`) | C | `lib/kernel/view-modes` | ## Operator entries (outside P1-P23) Entries tagged `pattern: 'operator'` were asked for by the operator, not found in the HMS pattern audit. | Entry | Group | File | |---|---|---| | [SiteShell](/en/gallery/SiteShell), [SiteMain](/en/gallery/SiteMain) | A | `components/site/` | | [SitePage](/en/gallery/SitePage), `buildSitePageMetadata` (helper/hook, not an entry) | B | `components/site/` | | [SitePageHeader](/en/gallery/SitePageHeader) | B | `components/families/header/SitePageHeader` | | [PortalBreadcrumb](/en/gallery/PortalBreadcrumb), [PortalActionBar](/en/gallery/PortalActionBar), [PortalDockableActions](/en/gallery/PortalDockableActions), [PortalCommandPalette](/en/gallery/PortalCommandPalette) | A | `components/portal/page/` | | [PortalPageCard](/en/gallery/PortalPageCard), [SitePageCard](/en/gallery/SitePageCard) | B | `components/families/card/PageCard` | | [PortalPageTable](/en/gallery/PortalPageTable), [SitePageTable](/en/gallery/SitePageTable) | B | `components/families/table/PageTable` | | [PortalPageGrid](/en/gallery/PortalPageGrid), [SitePageGrid](/en/gallery/SitePageGrid) | B | `components/families/grid/PageGrid` | | [PortalPageHeroSection](/en/gallery/PortalPageHeroSection), [SitePageHeroSection](/en/gallery/SitePageHeroSection) | B | `components/families/hero/PageHeroSection` | | [PortalPageCtaSection](/en/gallery/PortalPageCtaSection), [SitePageCtaSection](/en/gallery/SitePageCtaSection) | B | `components/families/cta/PageCtaSection` | | [PortalPageBanner](/en/gallery/PortalPageBanner), [SitePageBanner](/en/gallery/SitePageBanner) | B | `components/families/banner/PageBanner` | | [PortalPageDialog](/en/gallery/PortalPageDialog), [SitePageDialog](/en/gallery/SitePageDialog) | B | `components/families/dialog/PageDialog` | | [PortalPageCarousel](/en/gallery/PortalPageCarousel), [SitePageCarousel](/en/gallery/SitePageCarousel) | B | `components/families/carousel/PageCarousel` | | [Heading](/en/gallery/Heading), [Text](/en/gallery/Text), [Label](/en/gallery/Label), [Code](/en/gallery/Code), [Numeric](/en/gallery/Numeric) | K | `components/primitives` | | [Surface](/en/gallery/Surface), [Icon](/en/gallery/Icon) | K | `components/primitives` | | [ThemeSwitcher](/en/gallery/ThemeSwitcher), [DensitySwitcher](/en/gallery/DensitySwitcher), [PaletteSwitcher](/en/gallery/PaletteSwitcher) | K | `components/primitives` | ## Groups A-K | Group | Scope | Entry file | |---|---|---| | A | Shells and chrome | `inventory/entries/site.ts`, `portal.ts` | | B | Page templates and families | `portal-page.ts`, `templates.ts`, `families.ts` | | C | Data display | `data.ts`, `entity-nav.ts` | | D | Forms and input | `forms.ts` | | E | Overlays and feedback | `feedback.ts` | | F | Real-time and streaming | `realtime.ts` | | G | Conversational surfaces | `chat.ts` | | H | Voice and audio | `voice-audio.ts` | | I | Media and documents | `media.ts` | | J | Video calls | `call.ts` | | K | Design system primitives | `primitives.ts` | Some group B entries live in a feature entry file (for example `PortalPageChat` in `chat.ts`); the **Group** column above is the registry `group` value. --- Last reconciled: 2026-10-23 · task 009 Last reconciled: 2026-10-24 · plan ddx-web-speed-ui Last reconciled: 2026-10-25 · plan harness-alignment task 038