@ai-matrx/design-system 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # Changelog
 
+## 0.14.0 — 2026-09-10
+
+### `ArchivedDisclosure` — the card-list half of the ONE archive control
+
+0.13.0 shipped `ArchiveFilter` and the platform still had two archive controls,
+because the frontend kept the other one: `components/official/ArchivedDisclosure`,
+the "Archived (N)" one-click reveal proven in Transcript Studio, invented the
+same day in a different repo. Arman's ruling is that the control is the same
+primitive EVERYWHERE (`common-docs/policies/archived-items.md`), so a second
+home for half of it is the defect, not a convenience.
+
+`ArchivedDisclosure` now lives here, ported VERBATIM from that file (including
+its `countLabel` and `keepWhileOpen` additions): a one-click "Archived (N)"
+disclosure, closed by default, rendering archived rows in place underneath —
+or, with `children` omitted, the toggle alone for a host that merges archived
+rows into its own table. `count` is always the true number of archived rows:
+at zero the control renders NOTHING rather than an empty promise, unless
+`keepWhileOpen` marks a surface whose open state IS the archive view (a server
+request), where the way back must never vanish. `countLabel` covers the two
+cases a bare integer cannot tell the truth about: a capped server count
+(`"50+"`) and a count that has not landed (`null` prints no parenthetical).
+
+**Two shapes, one vocabulary.** `ArchiveFilter` for table/browse surfaces whose
+reader takes an archive parameter; `ArchivedDisclosure` for card lists, panels
+and pickers that are not table shaped. Never a third. Both speak the single set
+of words, now exported from one module: `ArchiveFilterValue`,
+`ARCHIVE_FILTER_VALUES`, `DEFAULT_ARCHIVE_FILTER` (`active`),
+`ARCHIVE_FILTER_LABELS`, plus two new exports — `ARCHIVE_LABEL`, the ONE noun
+both controls print (`ARCHIVE_FILTER_LABELS.archived` is derived from it, so
+renaming it renames both by construction), and
+`archiveFilterFromDisclosure(open)`, which says a disclosure's state in the
+tri-state words (`open` → `all`, because a disclosure reveals archived rows
+BESIDE the live ones) for hosts whose toggle is a server request.
+
+Icons stay inlined (C19): lucide `chevron-down` and `archive` joined
+`src/icons.tsx`, so the port renders the same glyphs with no icon dependency.
+
+### Consumer action
+
+**matrx-frontend must delete `components/official/ArchivedDisclosure.tsx`** and
+repoint every importer to `@ai-matrx/design-system` — at the time of writing:
+`features/organizations/components/OrgResourceList.tsx`,
+`features/whatsapp-clone/conversation-list/ConversationListPane.tsx`,
+`features/pdf/scanner/components/desktop/ScannerDesktop.tsx`,
+`features/agents/agent-creators/templates/TemplatesGrid.tsx`,
+`features/canvas/core/SavedCanvasItems.tsx`,
+`features/page-extraction/components/SavedJobsList.tsx`,
+`features/transcript-studio/components/scribe/RecordingCardList.tsx`,
+`features/masterwork/browse/components/MasterworkBrowseCards.tsx`,
+`features/masterwork/home/MasterworkHomePage.tsx`,
+`features/masterwork/components/masterworks/MasterworksPage.tsx`,
+`features/masterwork/components/detail/RulebookDetailPage.tsx`,
+`features/hr/settings/fields/HrFieldsPanel.tsx`,
+`features/pdf-extractor/studio/PdfStudioSidebar.tsx`,
+`features/pdf-extractor/components/PdfExtractorWorkspace.tsx`.
+`lib/entity-list`'s Archived radio renders `<ArchiveFilter>` (its URL and
+preference plumbing is unchanged — only the control component is the package's),
+and `lib/entity-list`'s `ArchivedFilter` type is now an alias of
+`ArchiveFilterValue`. Every other host: a local "Archived (N)" toggle or a
+local tri-state archive segmented control is a twin — delete it and import
+these.
+
+## 0.13.0 — 2026-09-09
+
+### `ArchiveFilter` — THE ARCHIVED-ITEMS LAW made a control
+
+Arman ruled on 2026-09-09 that archived rows of every entity are treated
+identically everywhere: every list carries an archive filter, the default hides
+archived, and revealing them is one or two clicks
+(`common-docs/policies/archived-items.md`). Before this release each host
+invented its own answer — a boolean `includeArchived` that nothing ever passed,
+a badge that showed archived rows mixed in, or nothing at all — so the reveal
+the platform intended was unreachable in most clients.
+
+`ArchiveFilter` is that control, once: a three-state segmented toggle over
+`active` (default) / `archived` / `all`, speaking the same words the Next.js
+app already uses (`lib/entity-list`'s "Active only" / "Archived only" /
+"Active + archived"). Shipped alongside it: `ARCHIVE_FILTER_VALUES`,
+`DEFAULT_ARCHIVE_FILTER`, `ARCHIVE_FILTER_LABELS`, the `ArchiveFilterValue`
+type, and `toArchiveFilter()` — which narrows an untrusted value (URL param,
+stored preference, API echo) to the tri-state and falls back to `active`, so a
+bad value can never silently widen a list to archived rows.
+
+Optional `counts` render a per-state number beside each label. Pass a count
+only when it describes what the list would actually render: a screen never
+lies.
+
+The control is a REQUEST, not a client-side sieve. Hand its value to the reader
+(an RPC's `p_archived`, an endpoint's `archived=`) so counts, badges and
+pagination agree with the rows on screen.
+
+### Consumer action
+
+Any list over an entity with `is_archived` / `archived_at` / an archived status
+must render `<ArchiveFilter>` and pass its value through to the server-side
+reader. Delete local `showArchived` booleans and hardcoded archive predicates —
+a boolean cannot express "archived only", which is why the law names three
+states.
+
 ## 0.12.1 — 2026-09-09
 
 Dialog, AlertDialog, Drawer, Sheet, and BottomSheet footer actions now carry a

package/README.md

@@ -5,7 +5,7 @@ The small, semantic UI foundation shared by AI Matrx React applications — prim
 **Controls:** Button, Badge, Label, Separator, the Input family, the Textarea family, Checkbox, Switch, RadioGroup, Slider, Toggle + ToggleGroup, Avatar, Progress.
 **Surfaces:** Card, Table, Tabs, Accordion, Collapsible, ScrollArea, Popover, Tooltip, HoverCard, Sheet, Dialog, AlertDialog, Drawer, BottomSheet + TabbedBottomSheet, Alert, Resizable, Skeleton.
 **Menus:** DropdownMenu, ContextMenu, Command / CommandDialog, Select, CreatablePicker.
-**Composed:** EditableLabel, SegmentedControl, ScoreRing, OverflowToolbar, ConfirmDialog + ConfirmDialogHost.
+**Composed:** EditableLabel, SegmentedControl, ArchiveFilter, ScoreRing, OverflowToolbar, ConfirmDialog + ConfirmDialogHost.
 **Hooks + utilities:** `useScrollFade`, `useIsMobile`, `usePortalContainer`, `useDialogContainer`, `useDrawerDirection`, `cn`.
 
 **The confirm dialog lives here; the imperative `confirm()` lives in `@ai-matrx/kit`.** Since 0.11.0 / kit 0.9.0 the surface is one implementation, in the package that owns AlertDialog, the motion layer and the overlay scrim token. Mount the host once near your provider root and call `confirm()` from anywhere — they share one registry through a `globalThis` slot:
@@ -29,6 +29,19 @@ Use the declarative `<ConfirmDialog open … busy />` inline instead when the di
 
 **Footer actions stay touch-sized through portals.** Dialog, AlertDialog, Drawer, Sheet, and BottomSheet footers apply a 44px action floor on coarse pointers or below 1024px. Import the package stylesheet; no host subtree class is required. Fine-pointer desktop keeps its declared density. State controls and prose links retain their sizing; exceptional compact actions can use `data-touch-exempt` with a call-site reason.
 
+**Every list over an archivable entity uses `ArchiveFilter`.** THE ARCHIVED-ITEMS LAW (Arman, 2026-09-09 — `common-docs/policies/archived-items.md`): an archive filter on every list, the default hides archived rows, and seeing them is one click. `ArchiveFilter` is the one control — `active` (default) / `archived` / `all`, in the same words the Next.js app uses.
+
+```tsx
+import { ArchiveFilter, DEFAULT_ARCHIVE_FILTER, type ArchiveFilterValue } from "@ai-matrx/design-system";
+
+const [archived, setArchived] = React.useState<ArchiveFilterValue>(DEFAULT_ARCHIVE_FILTER);
+const rows = useRows({ archived });   // the SERVER applies the predicate
+
+<ArchiveFilter value={archived} onValueChange={setArchived} counts={{ active: rows.activeCount }} />
+```
+
+Pass the value to the reader, never filter the already-fetched page: counts, badges and pagination must describe what the list renders. `toArchiveFilter()` narrows an untrusted value (URL param, stored preference) back to the tri-state, defaulting to `active` so nothing silently widens.
+
 **The Tooltip lives here, and only here.** `@ai-matrx/tap-target` used to ship its own copy; since design-system 0.7.0 / tap-target 0.2.0 it consumes this one and re-exports nothing.
 
 Where hosts had forked a primitive over DENSITY, density is a prop, not a fork: `Card size="sm|md|lg"`, `Table size="sm|md"`, `Accordion size="sm|md"`, `Switch`/`Avatar`/`Checkbox`/`Slider`/`RadioGroup`/`Toggle` `size`, `ResizableHandle size="xs".."4xl"`. It is declared once on the root and every item reads it from context, so a card cannot mix paddings and a radio group cannot mix control sizes.