@ai-matrx/design-system 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 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.