torch-glare 2.5.4 → 2.5.6

package/apps/lib/components/Table.tsx

@@ -6,6 +6,7 @@ import { useRef } from "react";
 import { Button } from "./Button";
 import { Checkbox } from "./Checkbox";
 import { useResize } from "../hooks/useResize";
+import { horizontalScrollerStyles } from "../utils/scroller";
 
 type TableHeadVariantsProps = VariantProps<typeof tableHeadVariants>;
 
@@ -18,18 +19,20 @@ const Table = React.forwardRef<
   <table
     data-theme={theme}
     ref={ref}
-    // `overflow-hidden` is the default, and it is load-bearing twice over: the table is `w-auto`,
-    // so one wider than its container would otherwise push the whole page wide and put a horizontal
-    // scrollbar on the layout; and callers that give the table a radius rely on it to clip the
-    // square header band out of the rounded corners.
+    // `overflow-visible` is the default, so the table does NOT clip or scroll itself. That is what
+    // lets `TableHeader`'s `sticky` reach past the table to the nearest real scrollport and
+    // actually pin — which is the whole point of it being sticky.
     //
-    // The cost is that it makes the table its own scroll container, and `TableHeader`'s `sticky`
-    // resolves against the *nearest* scrollport — so inside a clipping table the header pins to a
-    // box that never scrolls, i.e. does nothing. That is the right default: a header only benefits
-    // from sticking when the table sits in a scroller, and such a caller passes `overflow-visible`
-    // (tailwind-merge lets theirs win) to bind it to that scroller instead. Only do that where the
-    // scroller is `min-w-0`, or the width problem above comes back — `DataViews`' table view is the
-    // worked example.
+    // The consequence is that the table is `w-auto` and unclipped, so **a wider-than-its-container
+    // table is the container's problem**. Every table therefore needs a scrolling ancestor, or it
+    // pushes its container — and eventually the page — wide. Two provide one:
+    //   • `TableScroller` (below), wrapping the table directly. `FormBuilder.Table` uses it.
+    //   • `SectionBlock`'s body, which is `overflow-x-auto` — so a bare `<Table>` dropped into any
+    //     section card scrolls inside the card. That covers the app's detail tabs.
+    // `DataViews`' table view supplies its own `min-w-0 overflow-auto` scroller instead.
+    //
+    // A caller that wants the old self-clipping behaviour passes `overflow-hidden`
+    // (tailwind-merge lets theirs win) and gives up the sticky header in exchange.
     //
     // `[border-collapse:separate]` is what lets the header cells keep their borders while stuck.
     className={cn("overflow-visible w-auto [border-collapse:separate] border-spacing-0", className)}
@@ -388,23 +391,7 @@ TableEndAction.displayName = "TableEndAction";
  */
 const TableScroller = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
   ({ className, children, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(
-        "w-full overflow-x-auto overflow-y-hidden",
-        "[&::-webkit-scrollbar]:h-[14px]",
-        "[&::-webkit-scrollbar-track]:bg-transparent",
-        "[&::-webkit-scrollbar-thumb]:rounded-[7px]",
-        "[&::-webkit-scrollbar-thumb]:border-[5px] [&::-webkit-scrollbar-thumb]:border-solid",
-        "[&::-webkit-scrollbar-thumb]:border-transparent",
-        "[&::-webkit-scrollbar-thumb]:bg-clip-content",
-        "[&::-webkit-scrollbar-thumb]:bg-background-presentation-body-scroller-default",
-        "[&::-webkit-scrollbar-thumb:hover]:border-[3px]",
-        "[&::-webkit-scrollbar-thumb:hover]:bg-background-presentation-body-scroller-hover",
-        className,
-      )}
-      {...props}
-    >
+    <div ref={ref} className={cn("w-full", horizontalScrollerStyles, className)} {...props}>
       {children}
     </div>
   ),

package/apps/lib/hooks/useActiveTreeItem.ts

@@ -5,10 +5,13 @@ export function useActiveTreeItem(itemIds: string[]) {
   const [activeId, setActiveId] = useState<string | null>(null);
 
   useEffect(() => {
-    if (!itemIds || itemIds.length === 0) {
+    // An empty list is a legitimate answer — a page with no Quick Nav has nothing to track. Only a
+    // missing list is a caller mistake worth a warning.
+    if (!itemIds) {
       console.warn("No itemIds provided to useActiveTreeItem.");
       return;
     }
+    if (itemIds.length === 0) return;
 
     const observer = new IntersectionObserver(
       (entries) => {

package/apps/lib/hooks/useHtmlDir.ts

@@ -0,0 +1,31 @@
+import * as React from "react";
+
+/**
+ * Track the document's text direction from `<html dir>`, updating when it
+ * changes (e.g. on a language switch).
+ *
+ * Several Radix primitives (Tabs, etc.) default to `"ltr"` when no `dir` prop
+ * or `DirectionProvider` is supplied, which leaves them rendered left-to-right
+ * even on an RTL page. Forwarding this value as their `dir` makes them mirror
+ * correctly in Arabic.
+ */
+export function useHtmlDir(): "ltr" | "rtl" {
+  const read = () =>
+    typeof document !== "undefined" && document.documentElement.dir === "rtl"
+      ? "rtl"
+      : "ltr";
+
+  const [dir, setDir] = React.useState<"ltr" | "rtl">(read);
+
+  React.useEffect(() => {
+    if (typeof document === "undefined") return;
+    const html = document.documentElement;
+    const sync = () => setDir(read());
+    sync();
+    const observer = new MutationObserver(sync);
+    observer.observe(html, { attributes: true, attributeFilter: ["dir"] });
+    return () => observer.disconnect();
+  }, []);
+
+  return dir;
+}

package/apps/lib/hooks/useTagSelection.ts

@@ -1,4 +1,4 @@
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 
 export interface Tag {
   id: string;
@@ -9,16 +9,22 @@ export interface Tag {
   [key: string]: unknown;
 }
 
+/** Stable key for a selection, used to tell an external change from one we just made. */
+const signatureOf = (tags: Tag[]) => tags.map((t) => t.id).join("\0");
+
 export const useTagSelection = ({
   Tags,
   onTagsChange,
   inputRef,
   singleSelect = false,
+  creatable = false,
 }: {
   Tags: Tag[];
   onTagsChange?: (selectedTags: Tag[]) => void;
   inputRef?: React.RefObject<HTMLInputElement | null>;
   singleSelect?: boolean;
+  /** Allow typed text to become a selected tag that was never in `Tags`. */
+  creatable?: boolean;
 }) => {
   // Split initial tags into selected and unselected
   const initialSelectedTags = Tags.filter((tag) => tag.isSelected);
@@ -36,18 +42,63 @@ export const useTagSelection = ({
   const [focusedPopoverIndex, setFocusedPopoverIndex] = useState<number | null>(null);
   const [isPopoverOpen, setIsPopoverOpen] = useState(false);
 
-  // Update internal state when Tags prop changes
+  // LOCAL PATCH (Contact Center): key both effects below off a SIGNATURE of `Tags`, not the array
+  // reference. A caller that builds its tag list inline — `MultiSelectField` does, from the form
+  // value — hands over a fresh array every render, so the upstream `[Tags]` dependency changed on
+  // every pass: effect → setTags → re-render → new array → effect, an infinite render loop.
+  const tagsSignature = Tags.map((tag) => `${tag.id}:${tag.isSelected ? 1 : 0}`).join(" ");
+
+  // Update internal state when Tags actually changes.
+  //
+  // Filter against the INCOMING selection as well as the one we hold: on an external sync (the
+  // hydration case below) `selectedTagsStack` is still the pre-sync value at this point, so
+  // filtering by it alone left the freshly selected values sitting in the dropdown as if they
+  // were still available to add.
   useEffect(() => {
-    // Only update if the Tags array reference has changed
-    const selectedIds = selectedTagsStack.map((tag) => tag.id);
-    setTags(Tags.filter((tag) => !selectedIds.includes(tag.id)));
-  }, [Tags]);
+    const selectedIds = new Set([
+      ...selectedTagsStack.map((tag) => tag.id),
+      ...Tags.filter((tag) => tag.isSelected).map((tag) => tag.id),
+    ]);
+    setTags(Tags.filter((tag) => !selectedIds.has(tag.id)));
+  }, [tagsSignature]);
+
+  // LOCAL PATCH (Contact Center): follow the incoming selection.
+  //
+  // Upstream seeded `selectedTagsStack` from `Tags` ONCE, and the effect above refreshed only the
+  // AVAILABLE list — never the selection. That made the component effectively uncontrolled: on an
+  // edit form, react-hook-form's `reset()` hydration lands after mount, so a person's saved emails
+  // and tags rendered as an empty field. Re-sync whenever the incoming selected set differs from
+  // what we hold, and mark the change as external so it isn't echoed straight back to the parent.
+  const incomingSelected = Tags.filter((tag) => tag.isSelected);
+  const incomingSignature = signatureOf(incomingSelected);
+  const lastSyncedRef = useRef<string | null>(null);
+  // Starts true so the mount pass below is swallowed — see the notify effect.
+  const skipNotifyRef = useRef(true);
 
-  // Notify parent component when tags change
   useEffect(() => {
-    if (onTagsChange) {
-      onTagsChange(selectedTagsStack);
+    if (lastSyncedRef.current === incomingSignature) return;
+    lastSyncedRef.current = incomingSignature;
+    // Already matches (we made this change ourselves) — don't re-set state, so the notify flag
+    // stays untouched and the user's next real edit still reaches the parent.
+    if (signatureOf(selectedTagsStack) === incomingSignature) return;
+    skipNotifyRef.current = true;
+    setSelectedTagsStack(
+      singleSelect && incomingSelected.length > 0 ? [incomingSelected[0]] : incomingSelected,
+    );
+  }, [incomingSignature]);
+
+  // Notify parent component when tags change.
+  //
+  // LOCAL PATCH (Contact Center): upstream fired this on MOUNT too, so an untouched field wrote
+  // `[]` into the form — marking it dirty and adding an empty-array key to the request payload for
+  // a value nobody entered. It also fires for a sync from the parent, which would echo the value
+  // straight back. Both are skipped via the flag.
+  useEffect(() => {
+    if (skipNotifyRef.current) {
+      skipNotifyRef.current = false;
+      return;
     }
+    onTagsChange?.(selectedTagsStack);
   }, [selectedTagsStack]);
 
   // Filter tags based on search input
@@ -92,6 +143,38 @@ export const useTagSelection = ({
     setFocusedTagIndex(null);
   };
 
+  /**
+   * LOCAL PATCH (Contact Center): turn typed text into a selected tag.
+   *
+   * Upstream had no way in but `handleSelectTag(id)` against the fixed `Tags` list, so a free-text
+   * list (a person's emails, an organization's aliases) could not be expressed as a badge field at
+   * all — which is why those lists were built as one-column tables instead. Matching an existing
+   * tag by name selects it rather than creating a duplicate; the id IS the text, so a value the
+   * caller round-trips keeps a stable identity.
+   */
+  const handleCreateTag = (rawName: string) => {
+    const name = rawName.trim();
+    if (!name) return;
+    const sameName = (tag: Tag) => tag.name.toLowerCase() === name.toLowerCase();
+
+    // Already chosen — just clear the box so the user sees their text was accepted.
+    if (selectedTagsStack.some(sameName)) {
+      filterTagsBySearch("");
+      return;
+    }
+    // Offered in the list — select it instead of creating a look-alike.
+    const existing = tags.find(sameName);
+    if (existing) {
+      handleSelectTag(existing.id);
+      return;
+    }
+
+    const created: Tag = { id: name, name, value: name, isSelected: true };
+    setSelectedTagsStack((prev) => (singleSelect ? [created] : [...prev, created]));
+    filterTagsBySearch("");
+    setFocusedPopoverIndex(null);
+  };
+
   // Reset the hook state with new data
   const reset = (newTags: Tag[] = [], newSelectedTags: Tag[] = []) => {
     // In single select mode, ensure we only have at most one selected tag
@@ -198,6 +281,9 @@ export const useTagSelection = ({
     searchTags,
     handleSelectTag,
     handleUnselectTag,
+    // LOCAL PATCH (Contact Center) — see above.
+    handleCreateTag,
+    creatable,
     handleKeyDown,
     setFocusedTagIndex,
     setFocusedPopoverIndex,

package/apps/lib/layouts/FieldSection.tsx

@@ -27,6 +27,14 @@ export function FieldSection({
   childrenUnderLabel,
   ...props
 }: Props) {
+  // Which copy of `childrenUnderLabel` is visible, driven purely by the `@md` container
+  // breakpoint (this section's own width reaching 650px) — deliberately not by `direction`.
+  // Pinning it per-direction breaks the common case: `FormRenderer` forces `direction="vertical"`
+  // inside a drawer and FormBuilder puts the field's validation error in this slot, so a vertical
+  // form would strand every error under the label at any width.
+  const underLabelSlot = direction === "vertical" ? "hidden" : "hidden @md:block";
+  const underChildrenSlot = direction === "vertical" ? "block" : "block @md:hidden";
+
   return (
     <section
       {...props}
@@ -54,11 +62,29 @@ export function FieldSection({
           )}
 
           {secondaryLabel && <Label size={size} secondaryLabel={secondaryLabel} />}
-          {childrenUnderLabel}
+
+          {/* Stacked (below `@md`): the label column IS the full width, so under the label is the
+              natural spot. Hidden once `@md` splits the row into two columns — the copy in the
+              children column takes over there. Exactly one of the two is ever displayed. */}
+          {childrenUnderLabel && (
+            <div data-slot="under-label" className={cn(underLabelSlot)}>
+              {childrenUnderLabel}
+            </div>
+          )}
         </div>
 
         {/* Flexible section that takes up the remaining space */}
-        <div className="grid grid-cols-1 place-items-end gap-[12px]">{children}</div>
+        <div className="grid grid-cols-1 place-items-end gap-[12px]">
+          {children}
+
+          {/* Two-column (`@md` and up): the hint belongs under the control it describes, not
+              stranded at the bottom of the 350px label column. */}
+          {childrenUnderLabel && (
+            <div data-slot="under-children" className={cn("w-full", underChildrenSlot)}>
+              {childrenUnderLabel}
+            </div>
+          )}
+        </div>
       </div>
     </section>
   );

package/apps/lib/registry.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.5.4",
+  "version": "2.5.6",
   "generatedBy": "scripts/bin/generateRegistry",
   "npmVersions": {
     "@dnd-kit/core": "^6.3.1",
@@ -439,7 +439,6 @@
         "components/Table",
         "components/TextEditor",
         "components/Textarea",
-        "components/Tooltip",
         "hooks/useTagSelection",
         "layouts/FieldSection",
         "utils/cn"
@@ -461,6 +460,7 @@
         "components/SectionBlock",
         "components/Stepper",
         "components/TabFormItem",
+        "hooks/useHtmlDir",
         "utils/cn"
       ]
     },
@@ -772,7 +772,8 @@
         "class-variance-authority"
       ],
       "registryDependencies": [
-        "utils/cn"
+        "utils/cn",
+        "utils/scroller"
       ]
     },
     {
@@ -786,7 +787,6 @@
       "registryDependencies": [
         "components/ActionButton",
         "components/DropdownMenu",
-        "components/Tooltip",
         "utils/cn",
         "utils/types"
       ]
@@ -884,7 +884,8 @@
         "components/Button",
         "components/Checkbox",
         "hooks/useResize",
-        "utils/cn"
+        "utils/cn",
+        "utils/scroller"
       ]
     },
     {
@@ -1063,6 +1064,13 @@
       ],
       "registryDependencies": []
     },
+    {
+      "name": "useHtmlDir",
+      "type": "hooks",
+      "path": "hooks/useHtmlDir.ts",
+      "npmDependencies": [],
+      "registryDependencies": []
+    },
     {
       "name": "useInfiniteScroll",
       "type": "hooks",
@@ -1191,6 +1199,13 @@
       "npmDependencies": [],
       "registryDependencies": []
     },
+    {
+      "name": "scroller",
+      "type": "utils",
+      "path": "utils/scroller.ts",
+      "npmDependencies": [],
+      "registryDependencies": []
+    },
     {
       "name": "types",
       "type": "utils",

package/apps/lib/utils/scroller.ts

@@ -0,0 +1,26 @@
+/**
+ * LOCAL PATCH (Contact Center): the design's 14px horizontal scroller — a thin track that thickens
+ * and turns blue on hover.
+ *
+ * Lives here, not on `Table`, because two unrelated components wear it: `TableScroller` (the
+ * wrapper `FormBuilder.Table` puts around its grid) and `SectionBlock`'s body (which scrolls any
+ * wide content dropped into a section card). A section card should not have to import the table
+ * component — and its consumers should not pull in the table's dependencies — just to share a
+ * scrollbar.
+ *
+ * `overflow-y-hidden` is part of the set on purpose: CSS computes `overflow-y: visible` to `auto`
+ * whenever `overflow-x` is not `visible`, so omitting it gives every consumer a spurious vertical
+ * scrollbar.
+ */
+export const horizontalScrollerStyles = [
+  "overflow-x-auto overflow-y-hidden",
+  "[&::-webkit-scrollbar]:h-[14px]",
+  "[&::-webkit-scrollbar-track]:bg-transparent",
+  "[&::-webkit-scrollbar-thumb]:rounded-[7px]",
+  "[&::-webkit-scrollbar-thumb]:border-[5px] [&::-webkit-scrollbar-thumb]:border-solid",
+  "[&::-webkit-scrollbar-thumb]:border-transparent",
+  "[&::-webkit-scrollbar-thumb]:bg-clip-content",
+  "[&::-webkit-scrollbar-thumb]:bg-background-presentation-body-scroller-default",
+  "[&::-webkit-scrollbar-thumb:hover]:border-[3px]",
+  "[&::-webkit-scrollbar-thumb:hover]:bg-background-presentation-body-scroller-hover",
+].join(" ");

package/docs/components/badge-field.md

@@ -335,7 +335,7 @@ export function BadgeFieldWithIcon() {
 
 ### With Error State
 
-Display validation errors with tooltip.
+Display validation errors. `errorMessage` turns on the field's negative border.
 
 ```tsx
 export function BadgeFieldWithError() {
@@ -467,9 +467,9 @@ Extends all Input element props (except size and variant).
 | size | `'XS' \| 'S' \| 'M'` | `'M'` | Field size |
 | variant | `'PresentationStyle'` | `'PresentationStyle'` | Visual variant |
 | icon | `ReactNode` | - | Leading icon |
-| errorMessage | `string` | - | Error message (shows tooltip) |
+| errorMessage | `string` | - | Marks the field invalid — any non-undefined value turns on the negative border |
 | onTable | `boolean` | `false` | Table-specific styling |
-| toolTipSide | `ToolTipSide` | - | Tooltip position |
+| toolTipSide | `ToolTipSide` | - | **Deprecated, ignored.** The error tooltip was removed; an invalid field is shown by its border alone |
 | label | `string` | - | Field label |
 | required | `boolean` | `false` | Required indicator |
 | theme | `Themes` | - | Theme override |
@@ -477,6 +477,32 @@ Extends all Input element props (except size and variant).
 | addLabel | `string` | `'add'` | Label for the add action shown in the field |
 | dir | `string` | `'ltr'` | Reading direction (`'rtl'` for right-to-left) |
 | placeholder | `string` | - | Input placeholder text |
+| creatable | `boolean` | `false` | Let the user type a value that is not in `tags` and commit it as a badge |
+| createLabel | `(value: string) => string` | ``value => `Create "${value}"` `` | Label for the create row; receives the typed text |
+
+### Creatable tags
+
+With `creatable`, the field stops being a picker over a fixed list: whatever the user types can
+become a badge. Enter or comma commits it; Backspace on an empty box removes the last badge. Pass
+`tags={[]}` for a pure free-text list — emails, aliases, arbitrary labels — which otherwise has to be
+modelled as a one-column table.
+
+```tsx
+<BadgeField
+  creatable
+  tags={recipients}
+  onValueChange={setRecipients}
+  placeholder="Add an email…"
+  createLabel={(value) => `Invite ${value}`}
+/>
+```
+
+The create row is suppressed when the typed text already matches a selected or listed tag
+(case-insensitive), so you cannot produce duplicates. With `creatable` set, the empty-list message
+becomes "Type a value and press Enter" rather than "All tags selected".
+
+> `FormBuilder.MultiSelect` / `.Tags` forward `creatable`, but **not** `createLabel` — inside a form
+> the create row keeps the default label.
 
 ### Tag Type
 
@@ -674,7 +700,7 @@ describe('BadgeField', () => {
 - **ARIA Labels**: Proper labels for screen readers
 - **Focus Management**: Clear focus indicators
 - **Screen Reader**: Announces selected/removed tags
-- **Error Messages**: Accessible error tooltips
+- **Error Messages**: Invalid fields are marked with the negative border token
 - **Tab Order**: Logical tab navigation
 
 ## Performance

package/docs/components/context-menu.md

@@ -230,6 +230,8 @@ function RtlMenu() {
 
 Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
 
+The panel itself does not scroll — it clips, and an inner viewport inside it does the scrolling. That keeps the panel's 4px frosted gutter fixed instead of scrolling away with the rows. Submenus behave identically and take their own `maxHeight` (same `320`px default).
+
 ```typescript
 import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLabel } from "@/components/ContextMenu";
 
@@ -425,7 +427,7 @@ export const ContextMenuRadioItem: React.ForwardRefExoticComponent<ContextMenuRa
 - **Opens at the pointer**: the menu opens on right-click (`contextmenu`) at the exact cursor position, not anchored to a fixed trigger button.
 - **Second right-click closes it**: the Root is made controlled and tracks `open` in context. The Trigger listens in the capture phase, and when the menu is already open it `preventDefault()` / `stopPropagation()` and closes — so a second right-click dismisses instead of re-anchoring (which Radix handles unreliably).
 - **Auto-grouping**: by default (`autoGroup` on `ContextMenuContent`, default `true`) consecutive loose items (`ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, and `ContextMenuSub`) are automatically wrapped in a `Boxed` `ContextMenuGroup`, so they render inside a boxed container like DropdownMenu even when you do not write a group. Labels and explicit groups act as boundaries and pass through unchanged. Set `autoGroup={false}` to render children verbatim.
-- **Max height & scrolling**: the surface caps its height at `min(maxHeight, available-height)` (where `maxHeight` defaults to `320`px and `available-height` is the space Radix has after collision handling). A taller menu scrolls vertically instead of overflowing off-screen — items and groups keep their full height rather than squishing. Pass `maxHeight={N}` to change the cap.
+- **Max height & scrolling**: the surface caps its height at `min(maxHeight, available-height)` (where `maxHeight` defaults to `320`px and `available-height` is the space Radix has after collision handling). A taller menu scrolls vertically instead of overflowing off-screen — items and groups keep their full height rather than squishing. The panel clips and an inner viewport scrolls, so the panel's frosted gutter stays put. Pass `maxHeight={N}` to change the cap; `ContextMenuSubContent` accepts it too.
 - **Checkbox / radio keep the menu open**: `ContextMenuCheckboxItem` and `ContextMenuRadioItem` call `event.preventDefault()` inside `onSelect`, stopping Radix's default auto-close so users can toggle multiple options in one pass.
 - **Open-only animation**: only the open (enter) state animates (`fade-in`). There is intentionally no exit animation — holding the old DOM node during close breaks close/reposition on a second right-click, so it is omitted to keep repositioning reliable.
 - **Submenus and RTL**: nested `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent` are supported, and `dir="rtl"` on the Root mirrors the layout (including the submenu chevron).

package/docs/components/data-views/examples/filters.md

@@ -231,7 +231,6 @@ export default function FiltersExample() {
 
         {/* The active query, as removable chips — including the search term. */}
         <div className="border-border-presentation-global-primary border-b px-4 py-2 empty:hidden">
-          <DataViews.Filters.Summary />
         </div>
 
         <DataViews.Table />

package/docs/components/data-views/index.md

@@ -39,7 +39,7 @@ import {
   useDataViewsFilters, useDataViewsPanel, useDataViewsPanelTabs,
   useActiveRow,                                // the row behind `activeId`
   Cell,                                        // paint one field the way the views paint it
-  markView, markHeader, markPanel,             // register a part of your own
+  markView, markHeader, markPanel, markEmpty,  // register a part of your own
   SkeletonBar, skeletonKeys,                   // the loading pieces every view is built from
   getByPath, formatPathLabel, defaultGetRowId, // read a value by dotted path
   buildCardRows, resolveBadgeVariant,
@@ -135,10 +135,35 @@ see the change, "new filter" and "new page" have already become one object.
 
 ## Empty and loading
 
-Neither is a part you render. When there is nothing to show, the view shows **nothing** — the table
-keeps its header band and has no rows; the board keeps its columns and has no cards. While
-`loading` is set, each view paints a **skeleton in its own shape**: the table shimmers rows at the
-real row height and column widths, the board shimmers cards inside its columns.
+**Loading is not a part you render.** While `loading` is set, each view paints a **skeleton in its
+own shape**: the table shimmers rows at the real row height and column widths, the board shimmers
+cards inside its columns.
+
+**Empty is opt-in.** By default the view simply shows nothing — the table keeps its header band and
+has no rows, the board keeps its columns and has no cards. That default is deliberate: a centred
+message in place of the view throws away the chrome, and it cannot tell "no results" from "not
+fetched yet".
+
+When you do want something there, render `DataViews.Empty` anywhere among the children. It is a
+passthrough with a marker — it holds no opinion about what an empty state looks like, it only tells
+the root to put its content where the view goes. The root swaps it in when the query has settled and
+returned nothing (`!loading && rows.length === 0`):
+
+```tsx
+<DataViews rows={rows} fields={fields} loading={loading}>
+  <DataViews.Table />
+  <DataViews.Empty>
+    <div className="flex flex-1 flex-col items-center justify-center gap-2">
+      <p>No invoices match these filters.</p>
+      <Button onClick={clearFilters}>Clear filters</Button>
+    </div>
+  </DataViews.Empty>
+</DataViews>
+```
+
+Your content is what receives the body slot's height, so give it `flex-1` if it should centre.
+Wrapping `DataViews.Empty` in a component of your own? Mark that wrapper with `markEmpty` so the
+root still recognises it, the same way `markView` / `markHeader` / `markPanel` work.
 
 ## Large datasets
 
@@ -183,6 +208,7 @@ and that is not built.
 | `DataViews.Board` | a kanban board | `groups` — it never groups rows itself | [`views`](./examples/views.md) |
 | `DataViews.Inbox` | a master list beside a detail pane | the pane, as `children` | [`inbox-routing`](./examples/inbox-routing.md) |
 | `DataViews.Tree` | a hierarchy, optionally beside a pane | `nodes` — it never builds one | [`tree-custom`](./examples/tree-custom.md) |
+| `DataViews.Empty` | your content, in place of the view, once a settled query returns no rows | the content — it holds no opinion about what empty looks like | — |
 
 Each takes `id`, `label` and `icon` to control how it appears in the switcher, so the same view can
 be registered twice with different data. Full props are under
@@ -406,21 +432,13 @@ control at its neutral position emits no key at all, is under
 </DataViews.Filters>
 ```
 
-`Filters.Summary` paints whatever is active as removable chips. It reads the same context, so it
-works anywhere — most usefully **outside** the rail, where it tells the user what is filtering the
-rows they are looking at:
-
-```tsx
-<DataViews.Filters.Summary className="px-4 py-2" />
-```
-
 ### Questions this design gets asked
 
 | Question | Answer |
 | --- | --- |
 | Is there an in-view filter panel *and* a Filters tab — which is canonical? | **One surface.** `DataViews.Filters` is a single component. Render it inside a `Panel.Tab` or as a standalone bar; author against the component, not against a tab. |
 | What orders the sections? | **The order you write the children.** There is no `order` prop for filters. |
-| Does the applied-count badge count constrained *fields* or selected *values*? | **There is no count badge.** `PanelToggle` carries none. `Filters.Summary` is the equivalent, and it renders **one chip per constrained field** — Status with three values selected is one chip. |
+| Is there an applied-count badge or a chip summary of active filters? | **No.** `PanelToggle` carries no count, and there is no summary component — the controls themselves show what is set. Render your own above the rows if you want one. |
 | Do `BadgeField` chip colours and `FieldConfig.variants` share a token set? | **They never meet.** Chips come from the field's own `options`; `variants` (`BadgeVariant`) styles `enum-badge` **columns**. Filters and columns are independent. |
 
 And the behaviours worth stating because they are easy to assume wrongly:
@@ -771,14 +789,6 @@ A filter no FormBuilder field covers.
 | `render` | `(args: { value: FilterValue \| undefined; setValue: (v: FilterValue \| undefined) => void }) => ReactNode` | — | **yes** | |
 | `label` | `ReactNode` | derived from `path` | no | |
 
-### DataViews.Filters.Summary
-
-| Prop | Type | Default | Required | Notes |
-| --- | --- | --- | --- | --- |
-| `className` | `string` | — | no | |
-
-Active filters — and the search term — as removable chips. Renders `null` when there are none.
-
 ### Cell
 
 Paint one field of one row exactly as the views paint it.

package/docs/components/data-views/migration.md

@@ -56,11 +56,13 @@ Three parts of `DataViews` itself went in the same release.
 `rows`; whether there is more is derived from `rows.length < total`, so there is no `hasMore` prop.
 See the *Large datasets* section of the [DataViews doc](./index.md).
 
-**`DataViews.Empty`** — when there is nothing to show, the view shows nothing: the table keeps its
-header band and has no rows, the board keeps its columns and has no cards. A centred message in
-place of the view threw away the chrome, and it could not tell "no results" apart from "not fetched
-yet" — so the first load of every page announced that nothing matched before anything had been
-asked for.
+**`DataViews.Empty`** — *removed, then re-added as opt-in.* It was dropped because rendering a
+centred message in place of the view threw away the chrome, and it could not tell "no results" apart
+from "not fetched yet" — so the first load of every page announced that nothing matched before
+anything had been asked for. It is back on different terms: the default is still to show nothing,
+and `DataViews.Empty` now renders **only** once the query has settled with no rows
+(`!loading && rows.length === 0`). Nothing to migrate — omit it and behaviour is unchanged. See the
+*Empty and loading* section of the [DataViews doc](./index.md).
 
 **`DataViews.Loading`** — each view now paints its own skeleton, in its own shape, driven by the
 `loading` prop. A custom view registered with `markView` gets the same thing: read `loading` from