@assure-one/design-system 1.48.0 → 1.50.0

package/dist/suite/index.js

@@ -1,6 +1,6 @@
 "use client";
-export { AgreementPaneHeading, AgreementViewer, AssureAuditBrandIcon, AssureBooksBrandIcon, AssureProBrandIcon, AssureTaxBrandIcon, BRAND_PRODUCTS, ClientSelect, ComingSoon, Grid, Logo, ProposalAddOn, ProposalBillingTerms, ProposalConsentGate, ProposalCustomPage, ProposalNote, ProposalPackageCard, ProposalPaymentCapture, ProposalPricingSummary, ProposalServiceRow, ProposalSignatureBlock, ProposalSignerList, QUESTION_TYPES, QUESTION_TYPE_CONTRACT_VERSION, Questions, SidebarBrandSwitcher, SidebarBrandSwitcherTile, TaxSoftwareLogo, brandLabel } from '../chunk-FO2WSYUA.js';
-export { DocumentDetailActions, DocumentDetailBody, DocumentDetailHeader, DocumentDetailMetaRow, DocumentDetailPanel, DocumentDetailRequester, DocumentDetailTitle, DocumentList, DocumentListSection, DocumentRow } from '../chunk-HV24JSRN.js';
+export { AgreementPaneHeading, AgreementViewer, AssureAuditBrandIcon, AssureBooksBrandIcon, AssureProBrandIcon, AssureTaxBrandIcon, BRAND_PRODUCTS, ClientSelect, ComingSoon, Grid, Logo, ProposalAddOn, ProposalBillingTerms, ProposalConsentGate, ProposalCustomPage, ProposalNote, ProposalPackageCard, ProposalPaymentCapture, ProposalPricingSummary, ProposalServiceRow, ProposalSignatureBlock, ProposalSignerList, QUESTION_TYPES, QUESTION_TYPE_CONTRACT_VERSION, Questions, SidebarBrandSwitcher, SidebarBrandSwitcherTile, TaxSoftwareLogo, brandLabel } from '../chunk-GT7A7HP4.js';
+export { DocumentDetailActions, DocumentDetailBody, DocumentDetailHeader, DocumentDetailMetaRow, DocumentDetailPanel, DocumentDetailRequester, DocumentDetailTitle, DocumentList, DocumentListSection, DocumentRow } from '../chunk-CRA6WJZ6.js';
 import '../chunk-ARCWF2S3.js';
 import '../chunk-EUHGZA6Q.js';
 import '../chunk-YRHRVOLV.js';

package/docs/components.md

@@ -2,7 +2,7 @@
 
 <!-- Generated by `pnpm docs:catalogue` from api/*.api.md and docs/components.registry.json. Do not edit by hand; edit the registry and regenerate. -->
 
-Every public component of `@assure-one/design-system`, in one place: **543 component exports** — 189 component families with 243 compound parts, and 195 icons — plus the hooks, utilities, tokens and testing helpers the package exports. The list is derived from the API reports, so a public component cannot be missing from this page (`pnpm docs:catalogue --check` runs in `pnpm test:contracts`).
+Every public component of `@assure-one/design-system`, in one place: **548 component exports** — 194 component families with 243 compound parts, and 195 icons — plus the hooks, utilities, tokens and testing helpers the package exports. The list is derived from the API reports, so a public component cannot be missing from this page (`pnpm docs:catalogue --check` runs in `pnpm test:contracts`).
 
 **How to use this page.** Start from the ["Pick a component"](#pick-a-component) table with the UI need you have, or from ["Never hand-roll"](#never-hand-roll) with the raw element you were about to write; links land on the category section that holds the row. Every row links to the story that shows the states. The short rulebook for agents and new contributors is [`docs/for-ai-agents.md`](./for-ai-agents.md).
 
@@ -219,7 +219,7 @@ Layers above the page: dialogs, sheets, menus, popovers and tooltips. All portal
 | **Popover**<br>parts: `PopoverTrigger`, `PopoverAnchor`, `PopoverPortal`, `PopoverContent`, `PopoverClose`<br>since 0.0.0 | Interactive content anchored to a trigger: a small form, a picker, a filter panel. | A short non-interactive label (`Tooltip`), a preview on hover (`HoverCard`) or a list of actions (`DropdownMenu`). | `absolute-positioned div toggled by state` | [Tooltip](#overlays), [HoverCard](#overlays), [DropdownMenu](#overlays) | — |
 | **HoverCard**<br>parts: `HoverCardTrigger`, `HoverCardPortal`, `HoverCardContent`<br>since 0.0.0 | A rich preview when hovering a link or name (a person card, a record summary), for sighted pointer users. | The content is essential (it is hover-only) or interactive (`Popover`). | — | [Popover](#overlays), [Tooltip](#overlays) | — |
 | **Tooltip**<br>parts: `TooltipProvider`, `TooltipTrigger`, `TooltipPortal`, `TooltipContent`<br>since 0.0.0 | A short label for a control on hover and focus; the sealed `Tooltip` takes `content`, the parts compose. | The text is essential to use the control (make it visible) or interactive (`Popover`). | `title="…"` | [IconButton](#actions), [Popover](#overlays), [Kbd](#typography) | — |
-| **DropdownMenu**<br>parts: `DropdownMenuTrigger`, `DropdownMenuPortal`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuGroup`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`<br>since 0.0.0 | A menu of actions from a button: items, checkbox and radio items, groups, shortcuts, submenus; `/testing` ships `openMenu`. | Choosing a form value (`Select`), right-click (`ContextMenu`) or a form inside (`Popover`). | `<ul> shown on click`, `<select> used as a menu` | [ContextMenu](#overlays), [NewMenu](#actions), [Select](#selection), [Popover](#overlays) | — |
+| **DropdownMenu**<br>parts: `DropdownMenuTrigger`, `DropdownMenuPortal`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuGroup`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`<br>since 0.0.0 | A menu of actions from a button: items, checkbox and radio items, groups, shortcuts, submenus; `/testing` ships `openMenu`. Radio items that lead with their own glyph (a status dot, an icon) take `indicator="check"`. | Choosing a form value (`Select`), right-click (`ContextMenu`) or a form inside (`Popover`). | `<ul> shown on click`, `<select> used as a menu` | [ContextMenu](#overlays), [NewMenu](#actions), [Select](#selection), [Popover](#overlays) | — |
 | **ContextMenu**<br>parts: `ContextMenuTrigger`, `ContextMenuPortal`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuGroup`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent`<br>since 0.0.0 | Actions on right-click or long-press over a region, with the same item model as `DropdownMenu`. | The actions must be discoverable (`DropdownMenu` from a visible trigger). | `onContextMenu + positioned div` | [DropdownMenu](#overlays) | — |
 | **CommandPalette**<br>since 0.0.0 | The ⌘K command and search dialog: `cmdk` inside `Dialog`, groups, shortcuts, async results. | Searching one list (`SearchInput`) or picking a form value (`Combobox`). | — | [Dialog](#overlays), [KeyboardShortcutsDialog](#overlays), [Combobox](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/command-palette.stories.tsx) |
 | **KeyboardShortcutsDialog**<br>since 0.0.0 | The "?" help dialog listing keyboard shortcuts by section; no props shows the universal General section. | Showing one shortcut next to a control (`Kbd`, `KbdHint`). | — | [Kbd](#typography), [CommandPalette](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/keyboard-shortcuts-dialog.stories.tsx) |
@@ -267,6 +267,8 @@ Arrange content: stacks, surfaces, cards, separators, section and page framing.
 | **RouteTransition**<br>since 1.3.0 | Fade and slide a page panel in when `routeKey` changes; respects reduced motion. | Animating a component's own presence (the overlays already do) or a list (leave static). | — | [Shell](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/route-transition.stories.tsx) |
 | **VisuallyHidden**<br>since 0.0.0 | Text for assistive technology that must not be seen: the name of an icon-only control you compose yourself, a live-region message. | Hiding from everyone (`hidden`) or an `IconButton` (it names itself). | `class="sr-only"` | [IconButton](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/visually-hidden.stories.tsx) |
 | **ListPage** (experimental)<br>parts: `ListPageToolbar`, `ListPageResultCount`, `ListPageTable`, `ListPageScroll`<br>since unreleased | A list screen: full available height and never scrolls itself; stats, a toolbar (search left, filter chips, spacer, result count, actions), a table card that is the only scroll region (sticky header, pinned footer, shrinks to short content) and a bulk bar. | A table embedded in a detail page or card (Table / DataTable directly), or a page whose body is not one list. | `<div class="flex h-full flex-col overflow-hidden"> around a toolbar and an overflow-auto table` | [DataTable](#data-display), [FilterChips](#actions), [DisplayMenu](#actions), [BulkActionBar](#actions), [Table](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/list-page.stories.tsx) |
+| **ThreadDivider** (experimental)<br>since unreleased | The day break in a conversation: hairline, label in sentence case ("Today", "October 20"), hairline. Pass the formatted `label` and the ISO `dateTime`; `action` wraps the label in a control such as a jump-to-date menu trigger. Differs from `Separator`, which carries no label. | Separating sections of a page (`Separator`) or a run of items by category (`CategoryDivider`). | `<div> uppercase day pill`, `<hr> with a date` | [ThreadEvent](#data-display), [Separator](#layout), [MessageBubble](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/patterns/messaging/thread-divider.stories.tsx) |
+| **ConversationHeader** (experimental)<br>since unreleased | The top of an open conversation: the subject as `title`, at most one `badge`, one `meta` line of quiet facts (each an icon and a short label; a fact with `detail` opens it in a Popover, one with `onSelect` acts as a button), `actions` and `secondaryActions` on the right, an optional `back` button for one-pane layouts, and `embedded` inside a sheet that already shows a title. Differs from `PageHeader`, which titles a page, not a conversation. | A page or section title (`PageHeader`, `Heading`) or a dialog title (`DialogHeader`). | `<header> with chips for every fact` | [ConversationRow](#data-display), [PeopleList](#data-display), [Popover](#overlays), [Badge](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/patterns/messaging/conversation-header.stories.tsx) |
 
 ## Typography
 
@@ -317,7 +319,7 @@ Show records and status: tables, key/value grids, badges, dots, avatars, lists a
 | **Kanban**<br>parts: `KanbanColumn`, `KanbanCard`<br>since 0.3.0 | A board of columns and cards for stage-based work. | The data is tabular (`DataTableView`). | — | [DataTableView](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/kanban.stories.tsx) |
 | **EngagementCard** (deprecated) (`/legacy`)<br>since 1.2.0 | The client-portal card for one engagement: service, tone, title, progress and next step. | A generic card (`Card`) or a KPI (`KpiCard`). | — | [EngagementTimeline](#data-display), [Card](#layout), [serviceToneStyle](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/legacy/engagement-card.stories.tsx) |
 | **EngagementTimeline** (deprecated) (`/legacy`)<br>parts: `EngagementTimelineStep` (`/legacy`)<br>since 1.2.0 | The steps of an engagement as a toned vertical timeline. | A flow the user navigates (`Stepper`) or an activity feed (`ActivityList`). | — | [EngagementCard](#data-display), [Stepper](#navigation), [ActivityList](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/legacy/engagement-timeline.stories.tsx) |
-| **MessageBubble**<br>parts: `MessageBubbleAction`, `MessageBubbleTombstone`<br>since 0.12.0 | One chat message in a thread, inbound or outbound, with hover actions and a tombstone for deleted messages. | An email (`EmailMessageCard`) or an AI draft (`AiDraftCard`). | — | [EmailMessageCard](#data-display), [MessageComposer](#forms), [ChannelTabs](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/message-bubble.stories.tsx) |
+| **MessageBubble**<br>parts: `MessageBubbleAction`, `MessageBubbleTombstone`<br>since 0.12.0 | One chat message in a thread, with hover actions and a tombstone for deleted messages. Set `direction` (`inbound` left with the avatar, `outbound` right in the brand fill) for a conversation: `groupStart`/`groupEnd` show the avatar, name and time once per run and `meta` ("3:32 PM · Seen") under the run's last bubble; `footer` holds attachments or reactions; `tone="note"` is an internal note. Without `direction` the original comment-row layout is kept. | An email (`EmailMessageCard`) or an AI draft (`AiDraftCard`). | — | [ThreadEvent](#data-display), [ThreadDivider](#layout), [MessageComposer](#forms), [EmailMessageCard](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/message-bubble.stories.tsx) |
 | **EmailMessageCard** (deprecated) (`/legacy`)<br>since 1.5.0 | An email in a thread as an envelope card (header, readable body, footer) with auto-clamp and show-full toggle; you sanitise the HTML. | A chat message (`MessageBubble`). | — | [MessageBubble](#data-display), [AttachmentChip](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/legacy/email-message-card.stories.tsx) |
 | **DocumentChecklist** (deprecated) (`/legacy`)<br>since 1.21.0 | The client's view of requested documents by lifecycle: awaiting, in review, received, complete. | The firm's missing-documents view (`MissingDocumentsPanel`). | — | [MissingDocumentsPanel](#feedback), [DocumentRequestUpload](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/legacy/document-checklist.stories.tsx) |
 | **DocumentDetailPanel** (`/suite`)<br>parts: `DocumentDetailHeader` (`/suite`), `DocumentDetailTitle` (`/suite`), `DocumentDetailRequester` (`/suite`), `DocumentDetailMetaRow` (`/suite`), `DocumentDetailBody` (`/suite`), `DocumentDetailActions` (`/suite`), `DocumentList` (`/suite`), `DocumentListSection` (`/suite`), `DocumentRow` (`/suite`)<br>since 1.8.0 | The document detail side panel and the document list it opens from: header, title, requester, meta, body, actions; `DocumentList` sections of `DocumentRow`s. | A file outside the documents workspace (`AttachmentChip`). | — | [DocumentsWorkspaceLayout](#layout), [DocumentFileRow](#data-display), [DocumentSourceTag](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/suite/documents/document-detail-panel.stories.tsx) |
@@ -330,6 +332,9 @@ Show records and status: tables, key/value grids, badges, dots, avatars, lists a
 | **EmptyValue** (experimental)<br>since unreleased | A table or detail cell has no value: renders the em dash placeholder consistently. | The value is genuinely empty text a user typed — render it as-is. | `<span>—</span>` | — | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/data-table-view.stories.tsx) |
 | **DataTableHeaderMenu** (experimental)<br>since unreleased | A column's options menu in a header cell's `menu` slot: sort ascending / descending / clear, move left / right, hide, pin, autosize, reset columns — each item only when its callback is given. | A table-wide column picker (DisplayMenu columns section) or row actions (DropdownMenu in a cell). | — | [Table](#data-display), [DataTable](#data-display), [DisplayMenu](#actions) | — |
 | **DataTableLoadMore** (experimental)<br>parts: `DataTableSpacerRow`<br>also: `useDataTableVirtualRows`, `useScrollRestoration`<br>since unreleased | The foot of a virtualised infinite list: an IntersectionObserver sentinel plus a visible "Load more" button and an end-of-list status; `useDataTableVirtualRows` windows the rows with spacer rows, `useScrollRestoration` returns the user to the same rows. | A paged list (DataTablePagination) or a short list that renders every row. | — | [DataTable](#data-display), [ListPage](#layout), [Table](#data-display) | — |
+| **ThreadEvent** (experimental)<br>since unreleased | A quiet history line between messages in a conversation: something that happened, not something said ("You escalated this chat", "Mike Ross resolved this escalation"). Pass the sentence in the reader's voice as `children`, an optional `icon` (the only part `intent` tints) and the formatted `time` with `dateTime`. Differs from `ActivityEventItem`, which is a row in a feed, not a line inside a thread. | A message someone wrote (`MessageBubble`), a feed of activity (`ActivityList`) or a status the reader must act on (`Alert`). | `<div> centred pill for a system message` | [ThreadDivider](#layout), [MessageBubble](#data-display), [ActivityList](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/patterns/messaging/thread-event.stories.tsx) |
+| **ConversationRow** (experimental)<br>since unreleased | One conversation in an inbox or a messages list: `leading` avatar, `title` with an optional `marker` (e.g. an escalation flag) and `unread` dot, `meta` with `metaIcon`, `preview`, `time` and at most one `status`. `selected` gives the open conversation a soft fill, a brand bar on its left edge and `aria-current`. `selection` (a checkbox) and `actions` (a menu) sit beside the open button, never inside it; rest props land on the root so `data-*` hooks stay there. Differs from `DocumentRow`/`ClientRailItem`, which are not conversations. | A notification with read state and filters (`NotificationItem` in `NotificationPanel`) or a table row (`DataTable`). | `<li onClick> inbox row`, `<div> thread card` | [ConversationHeader](#layout), [Avatar](#data-display), [Badge](#data-display), [StatusBadge](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/patterns/messaging/conversation-row.stories.tsx) |
+| **PeopleList** (experimental)<br>since unreleased | Who can see something, grouped: a `title` and `description`, `sections` (each with an icon, a label, a count and people), one row per person (avatar, name, a `tag` such as "You", and their role or reasons as `detail`, which wraps) and a `footer` for who cannot see it. No chrome of its own: put it in `PopoverContent padding="none"` or a side panel. | Picking people (`PeoplePicker`) or a stack of faces (`AvatarGroup`). | `a sentence listing who can see a thread` | [ConversationHeader](#layout), [PeoplePicker](#selection), [AvatarGroup](#data-display), [Popover](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/patterns/messaging/people-list.stories.tsx) |
 
 ## Media
 
@@ -452,7 +457,10 @@ The raw element or pattern on the left already has a design-system component. Wr
 | `<div onClick>` | [Button](#actions), [Pressable](#actions) |
 | `<div role="alert">` | [Alert](#feedback) |
 | `<div role="group">` | [Fieldset](#forms) |
+| `<div> centred pill for a system message` | [ThreadEvent](#data-display) |
 | `<div> of <button> with a manual active class` | [SegmentedControl](#selection) |
+| `<div> thread card` | [ConversationRow](#data-display) |
+| `<div> uppercase day pill` | [ThreadDivider](#layout) |
 | `<dl>` | [MetadataGrid](#data-display) |
 | `<fieldset>` | [Fieldset](#forms) |
 | `<h1>` | [Heading](#typography) |
@@ -460,7 +468,9 @@ The raw element or pattern on the left already has a design-system component. Wr
 | `<h2> + <p> pair` | [SectionHeader](#layout) |
 | `<h3>` | [Heading](#typography) |
 | `<h4>` | [Heading](#typography) |
+| `<header> with chips for every fact` | [ConversationHeader](#layout) |
 | `<hr>` | [Separator](#layout) |
+| `<hr> with a date` | [ThreadDivider](#layout) |
 | `<img class="rounded-full">` | [Avatar](#data-display) |
 | `<img src="…logo.svg">` | [Brand icons](#icons) |
 | `<img src="…vendor-logo.svg">` | [TaxSoftwareLogo](#media) |
@@ -487,6 +497,7 @@ The raw element or pattern on the left already has a design-system component. Wr
 | `<label>` | [Label](#forms) |
 | `<legend>` | [Fieldset](#forms) |
 | `<li onClick>` | [Pressable](#actions) |
+| `<li onClick> inbox row` | [ConversationRow](#data-display) |
 | `<nav aria-label="breadcrumb"><ol>` | [Breadcrumb](#navigation) |
 | `<nav> of page number buttons` | [Pagination](#navigation) |
 | `<option>` | [Select](#selection) |
@@ -523,6 +534,7 @@ The raw element or pattern on the left already has a design-system component. Wr
 | `<ul role="tablist">` | [Tabs](#navigation) |
 | `<ul> of hand-styled feed rows` | [ActivityList](#data-display) |
 | `<ul> shown on click` | [DropdownMenu](#overlays) |
+| `a sentence listing who can see a thread` | [PeopleList](#data-display) |
 | `absolute-positioned div toggled by state` | [Popover](#overlays) |
 | `ad-hoc recharts with hex colours` | [AreaChart](#media) |
 | `alert()` | [ToastProvider](#feedback) |

package/docs/components.registry.json

@@ -1833,7 +1833,7 @@
         "DropdownMenuSubTrigger",
         "DropdownMenuSubContent"
       ],
-      "useWhen": "A menu of actions from a button: items, checkbox and radio items, groups, shortcuts, submenus; `/testing` ships `openMenu`.",
+      "useWhen": "A menu of actions from a button: items, checkbox and radio items, groups, shortcuts, submenus; `/testing` ships `openMenu`. Radio items that lead with their own glyph (a status dot, an icon) take `indicator=\"check\"`.",
       "dontUseWhen": "Choosing a form value (`Select`), right-click (`ContextMenu`) or a form inside (`Popover`).",
       "replacesRawHtml": [
         "<ul> shown on click",
@@ -2864,12 +2864,13 @@
         "MessageBubbleAction",
         "MessageBubbleTombstone"
       ],
-      "useWhen": "One chat message in a thread, inbound or outbound, with hover actions and a tombstone for deleted messages.",
+      "useWhen": "One chat message in a thread, with hover actions and a tombstone for deleted messages. Set `direction` (`inbound` left with the avatar, `outbound` right in the brand fill) for a conversation: `groupStart`/`groupEnd` show the avatar, name and time once per run and `meta` (\"3:32 PM · Seen\") under the run's last bubble; `footer` holds attachments or reactions; `tone=\"note\"` is an internal note. Without `direction` the original comment-row layout is kept.",
       "dontUseWhen": "An email (`EmailMessageCard`) or an AI draft (`AiDraftCard`).",
       "related": [
-        "EmailMessageCard",
+        "ThreadEvent",
+        "ThreadDivider",
         "MessageComposer",
-        "ChannelTabs"
+        "EmailMessageCard"
       ],
       "since": "0.12.0"
     },
@@ -3551,6 +3552,81 @@
         "Table"
       ],
       "since": "unreleased"
+    },
+    "ThreadEvent": {
+      "category": "data display",
+      "useWhen": "A quiet history line between messages in a conversation: something that happened, not something said (\"You escalated this chat\", \"Mike Ross resolved this escalation\"). Pass the sentence in the reader's voice as `children`, an optional `icon` (the only part `intent` tints) and the formatted `time` with `dateTime`. Differs from `ActivityEventItem`, which is a row in a feed, not a line inside a thread.",
+      "dontUseWhen": "A message someone wrote (`MessageBubble`), a feed of activity (`ActivityList`) or a status the reader must act on (`Alert`).",
+      "replacesRawHtml": [
+        "<div> centred pill for a system message"
+      ],
+      "related": [
+        "ThreadDivider",
+        "MessageBubble",
+        "ActivityList"
+      ],
+      "since": "unreleased"
+    },
+    "ThreadDivider": {
+      "category": "layout",
+      "useWhen": "The day break in a conversation: hairline, label in sentence case (\"Today\", \"October 20\"), hairline. Pass the formatted `label` and the ISO `dateTime`; `action` wraps the label in a control such as a jump-to-date menu trigger. Differs from `Separator`, which carries no label.",
+      "dontUseWhen": "Separating sections of a page (`Separator`) or a run of items by category (`CategoryDivider`).",
+      "replacesRawHtml": [
+        "<div> uppercase day pill",
+        "<hr> with a date"
+      ],
+      "related": [
+        "ThreadEvent",
+        "Separator",
+        "MessageBubble"
+      ],
+      "since": "unreleased"
+    },
+    "ConversationRow": {
+      "category": "data display",
+      "useWhen": "One conversation in an inbox or a messages list: `leading` avatar, `title` with an optional `marker` (e.g. an escalation flag) and `unread` dot, `meta` with `metaIcon`, `preview`, `time` and at most one `status`. `selected` gives the open conversation a soft fill, a brand bar on its left edge and `aria-current`. `selection` (a checkbox) and `actions` (a menu) sit beside the open button, never inside it; rest props land on the root so `data-*` hooks stay there. Differs from `DocumentRow`/`ClientRailItem`, which are not conversations.",
+      "dontUseWhen": "A notification with read state and filters (`NotificationItem` in `NotificationPanel`) or a table row (`DataTable`).",
+      "replacesRawHtml": [
+        "<li onClick> inbox row",
+        "<div> thread card"
+      ],
+      "related": [
+        "ConversationHeader",
+        "Avatar",
+        "Badge",
+        "StatusBadge"
+      ],
+      "since": "unreleased"
+    },
+    "ConversationHeader": {
+      "category": "layout",
+      "useWhen": "The top of an open conversation: the subject as `title`, at most one `badge`, one `meta` line of quiet facts (each an icon and a short label; a fact with `detail` opens it in a Popover, one with `onSelect` acts as a button), `actions` and `secondaryActions` on the right, an optional `back` button for one-pane layouts, and `embedded` inside a sheet that already shows a title. Differs from `PageHeader`, which titles a page, not a conversation.",
+      "dontUseWhen": "A page or section title (`PageHeader`, `Heading`) or a dialog title (`DialogHeader`).",
+      "replacesRawHtml": [
+        "<header> with chips for every fact"
+      ],
+      "related": [
+        "ConversationRow",
+        "PeopleList",
+        "Popover",
+        "Badge"
+      ],
+      "since": "unreleased"
+    },
+    "PeopleList": {
+      "category": "data display",
+      "useWhen": "Who can see something, grouped: a `title` and `description`, `sections` (each with an icon, a label, a count and people), one row per person (avatar, name, a `tag` such as \"You\", and their role or reasons as `detail`, which wraps) and a `footer` for who cannot see it. No chrome of its own: put it in `PopoverContent padding=\"none\"` or a side panel.",
+      "dontUseWhen": "Picking people (`PeoplePicker`) or a stack of faces (`AvatarGroup`).",
+      "replacesRawHtml": [
+        "a sentence listing who can see a thread"
+      ],
+      "related": [
+        "ConversationHeader",
+        "PeoplePicker",
+        "AvatarGroup",
+        "Popover"
+      ],
+      "since": "unreleased"
     }
   },
   "entries": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assure-one/design-system",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "Assure One design system — tokens, primitives, and patterns for the Assure Suite.",
   "license": "UNLICENSED",
   "private": false,