@elliemae/ds-filter-bar 3.70.0-next.3 → 3.70.0-next.30

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@elliemae/ds-filter-bar",
-  "version": "3.70.0-next.3",
+  "version": "3.70.0-next.30",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Filter Bar",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "module": "./dist/esm/index.js",
   "main": "./dist/cjs/index.js",
@@ -38,19 +39,19 @@
   "dependencies": {
     "@xstyled/system": "~3.8.1",
     "uid": "^2.0.2",
-    "@elliemae/ds-button-v2": "3.70.0-next.3",
-    "@elliemae/ds-grid": "3.70.0-next.3",
-    "@elliemae/ds-menu-button": "3.70.0-next.3",
-    "@elliemae/ds-props-helpers": "3.70.0-next.3",
-    "@elliemae/ds-system": "3.70.0-next.3",
-    "@elliemae/ds-icons": "3.70.0-next.3"
+    "@elliemae/ds-grid": "3.70.0-next.30",
+    "@elliemae/ds-button-v2": "3.70.0-next.30",
+    "@elliemae/ds-menu-button": "3.70.0-next.30",
+    "@elliemae/ds-props-helpers": "3.70.0-next.30",
+    "@elliemae/ds-system": "3.70.0-next.30",
+    "@elliemae/ds-icons": "3.70.0-next.30"
   },
   "devDependencies": {
     "jest": "^30.0.0",
     "styled-components": "~5.3.9",
-    "@elliemae/ds-test-utils": "3.70.0-next.3",
-    "@elliemae/ds-monorepo-devops": "3.70.0-next.3",
-    "@elliemae/ds-typescript-helpers": "3.70.0-next.3"
+    "@elliemae/ds-test-utils": "3.70.0-next.30",
+    "@elliemae/ds-monorepo-devops": "3.70.0-next.30",
+    "@elliemae/ds-typescript-helpers": "3.70.0-next.30"
   },
   "peerDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/skills/ds-filter-bar-health-check/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ds-filter-bar-health-check
+description: >
+  Audit the current state of a @elliemae/ds-filter-bar implementation. Use before starting
+  a task that depends on the filter bar, to verify a foundation before building on it, or
+  when diagnosing unexpected behavior. Produces a complete state report: what is correct and
+  sound, what requires fixing, what is suboptimal, and what gaps may affect the current task.
+type: health-check
+library: ds-filter-bar
+library_version: '3.60.0'
+requires:
+  - ds-filter-bar-setup
+  - ds-filter-bar-slots
+---
+
+## Purpose
+
+This skill audits an existing `@elliemae/ds-filter-bar` integration. It is not a setup guide. It tells you the current state of a filter bar implementation that already exists.
+
+**Use it:**
+
+- Before starting a task that involves a filter bar — to understand what you are about to touch
+- Before making filter bar interactions load-bearing for a new feature — to verify the foundation
+- When focus, keyboard navigation, or screen reader feedback is broken — to surface what the implementation gets wrong
+
+---
+
+## Load the embedded knowledge
+
+Load the following skills **as reference knowledge only**. You are reading their embedded understanding of correct patterns. You are not running them as tasks.
+
+- `ds-filter-bar-setup` — assembly, focus management, `runAfterRemoval`, `ScreenReaderOnly`, `fallbackRef`, `filterBarRef`, state management
+- `ds-filter-bar-slots` — slot injection surface, valid uses, event listener red flag
+
+---
+
+## Procedure
+
+### Step 1 — Locate and read the implementation
+
+Find every file where `@elliemae/ds-filter-bar` components are rendered. For each instance:
+
+- Record which components are used: `DSFilterBar`, `DSFilterBarContent`, `DSFilterBarActions`, `DSFilterBarMenuButton`
+- Record whether `useFilterBarPrevNextFocus` is imported and used
+- Read where filter state lives (active filters, pills) — state manager, store, atoms, or `useState`
+- Read every `onRemove` handler on pill components — is each one wrapped in `runAfterRemoval`?
+- Read the `onClearFilters` handler on `DSFilterBarMenuButton` — this one should NOT use `runAfterRemoval`
+- Check whether `ScreenReaderOnly aria-live="polite"` is present inside `DSFilterBar`
+- Check whether `filterBarRef` is passed to `DSFilterBar`
+- Check whether `fallbackRef` (or equivalent) is shared between `useFilterBarPrevNextFocus` and `DSFilterBarMenuButton.innerRef`
+- Check whether `RemovableFilterPill` (or equivalent pill component) is defined at module level
+- Check whether the filter bar is inside a DataTable context — if so, `withFilterBar=true` on DataTable may have been the correct choice instead of standalone
+
+### Step 2 — Apply diagnostic checks
+
+**CRITICAL** — prevents correct function or WCAG failure; fix before proceeding
+**HIGH** — meaningful risk; should fix
+**MEDIUM** — suboptimal; worth addressing
+**SOUND** — correct; rely on it
+
+#### Focus management checks
+
+- [ ] `useFilterBarPrevNextFocus` is used — without it, focus management is manual and likely incorrect
+- [ ] Every individual pill `onRemove` handler is wrapped in `runAfterRemoval` — omission is a silent WCAG 2.4.3 (Focus Order) failure
+- [ ] `DSFilterBarMenuButton.onClearFilters` is NOT wrapped in `runAfterRemoval` — the menu button persists after clearing; this handler is the correct exception
+- [ ] `filterBarRef` is passed to `DSFilterBar` — without it, the hook cannot scan focusable elements and immediately jumps to `fallbackRef` on every removal
+- [ ] `fallbackRef` (hook) and `innerRef` (DSFilterBarMenuButton) are the same ref object — separate refs leave `fallbackRef.current` null at focus-return time
+
+#### Screen reader checks
+
+- [ ] `ScreenReaderOnly aria-live="polite"` is rendered inside `DSFilterBar`
+- [ ] The announcement string is updated on every filter state change (remove single, clear all, restore) — not only on one type of change
+- [ ] `ScreenReaderOnly` is imported from `@elliemae/ds-accessibility` — not from `@elliemae/ds-filter-bar`
+
+#### Assembly checks
+
+- [ ] `RemovableFilterPill` (or equivalent pill wrapper) is defined at module level — not inside the parent component body
+- [ ] Filter state (active filters list) lives in the project's state manager — not `useState`
+- [ ] The one acceptable `useState` is the `announcement` string — ephemeral UI feedback only
+- [ ] No `useEffect` watches filter state to dispatch API calls — consequences belong inside callbacks
+- [ ] If the filter bar is inside a DataTable view: was `withFilterBar=true` on DataTable evaluated first? Standalone `ds-filter-bar` is for non-DataTable contexts
+
+#### Slot checks
+
+- [ ] No event listeners (`onClick`, `onKeyDown`) injected through slot props — the filter bar manages its own interaction model
+
+#### Memoization checks
+
+- [ ] `onClearFilters` is wrapped in `useCallback`
+- [ ] `options` for `DSFilterBarMenuButton` is stable (`useMemo` if constructed inline)
+- [ ] Per-pill `onRemove` handlers: each callback is stable (either `useCallback` per item or using a handler factory)
+
+### Step 3 — Produce the state report
+
+**Foundation — what is correct and sound**
+What the implementation gets right. Be specific — this is what you can rely on.
+
+**Critical issues — fix before proceeding**
+Each item with file, location, and pointer to the `ds-filter-bar-setup` skill section covering the fix. A11y failures (runAfterRemoval, ScreenReaderOnly) are always critical.
+
+**Warnings — should address, not blocking**
+Each item with context on the risk.
+
+**Awareness — no action needed, good to know**
+Suboptimal patterns that are not breaking.
+
+**Gaps relevant to this task**
+What the current task will require that is not yet present.
+
+---
+
+## What this skill does NOT do
+
+- It does not generate or modify code
+- It does not run the setup skill as a task
+- It does not replace human judgment on trade-offs
+
+## When this isn't enough
+
+**ICE internal:** Microsoft Teams — Dimsum channel (informal) / Jira Dimsum board (formal)
+**Partners:** Your organization's Dimsum point of contact

package/skills/ds-filter-bar-setup/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: ds-filter-bar-setup
+description: >
+  Filter bar assembly for @elliemae/ds-filter-bar. DSFilterBar (filterBarRef required),
+  DSFilterBarContent (pills area), DSFilterBarActions, DSFilterBarMenuButton (onClearFilters,
+  options, innerRef). useFilterBarPrevNextFocus hook with filterBarRef + fallbackRef →
+  runAfterRemoval wraps every pill onRemove handler. ScreenReaderOnly aria-live="polite"
+  required for screen reader announcements. fallbackRef must be passed as both hook
+  fallbackRef and DSFilterBarMenuButton innerRef — same ref object.
+type: core
+library: ds-filter-bar
+library_version: '3.60.0'
+sources:
+  - '@elliemae/ds-filter-bar:dist/types/react-desc-prop-types.d.ts'
+  - '@elliemae/ds-filter-bar:dist/types/hooks/react-desc-prop-types.d.ts'
+  - '@elliemae/ds-filter-bar:dist/types/parts/DSFilterBarMenuButton/react-desc-prop-types.d.ts'
+---
+
+## Setup
+
+**Before using standalone `ds-filter-bar`:** if the consuming application already uses `@elliemae/ds-data-table`, check whether `withFilterBar=true` on the DataTable covers the requirement. The DataTable's built-in filter bar handles integration with its own filter state. Standalone `ds-filter-bar` is for filter UIs outside a DataTable context, or in applications that don't use DataTable.
+
+Define `RemovableFilterPill` at module level — never inside another component. A component defined inside a parent gets a new type identity on every render, causing React to unmount and remount the subtree on every cycle, which destroys focus mid-removal.
+
+Read filter state from the project's state manager (RTK is most common in ICE codebases; adapt to your project's convention — vanilla Redux, Redux-Saga, Zustand, or other). The one acceptable `useState` is the `announcement` string — it is ephemeral UI feedback with no cross-component visibility requirement.
+
+`filterBarRef` and `menuButtonRef` must be the same ref objects passed to both the hook and the components. `filterBarRef` wires `DSFilterBar`'s DOM node to the hook's focusable-element scan. `menuButtonRef` is the fallback focus target when no pills remain — it must be passed as `innerRef` to `DSFilterBarMenuButton` so it is populated when the hook needs it.
+
+```jsx
+import {
+  DSFilterBar,
+  DSFilterBarActions,
+  DSFilterBarContent,
+  DSFilterBarMenuButton,
+  useFilterBarPrevNextFocus,
+} from '@elliemae/ds-filter-bar';
+import { ScreenReaderOnly } from '@elliemae/ds-accessibility';
+import { DSPillV2 } from '@elliemae/ds-pills-v2';
+import { useCallback, useRef, useState } from 'react';
+
+const RemovableFilterPill = ({ label, onRemove }) => <DSPillV2 type="removable" label={label} onRemove={onRemove} />;
+
+const FilterBarComponent = () => {
+  const filters = useSelector(selectActiveFilters);
+  const dispatch = useDispatch();
+  const [announcement, setAnnouncement] = useState('');
+
+  const filterBarRef = useRef(null);
+  const menuButtonRef = useRef(null);
+
+  const { runAfterRemoval } = useFilterBarPrevNextFocus({
+    filterBarRef,
+    fallbackRef: menuButtonRef,
+  });
+
+  const handleSingleFilterRemove = useCallback(
+    (filter) => {
+      const newFilters = filters.filter((f) => f !== filter);
+      dispatch(setFilters(newFilters));
+      dispatch(fetchFilteredData(newFilters));
+      setAnnouncement(`Filter removed: ${filter}`);
+    },
+    [dispatch, filters],
+  );
+
+  const handleClearAll = useCallback(() => {
+    dispatch(setFilters([]));
+    dispatch(fetchFilteredData([]));
+    setAnnouncement('All filters cleared');
+  }, [dispatch]);
+
+  return (
+    <DSFilterBar filterBarRef={filterBarRef}>
+      <ScreenReaderOnly aria-live="polite">{announcement}</ScreenReaderOnly>
+      <DSFilterBarContent>
+        {filters.map((filter) => (
+          <RemovableFilterPill
+            key={filter}
+            label={filter}
+            onRemove={() => runAfterRemoval(() => handleSingleFilterRemove(filter))}
+          />
+        ))}
+      </DSFilterBarContent>
+      <DSFilterBarActions>
+        <DSFilterBarMenuButton innerRef={menuButtonRef} onClearFilters={handleClearAll} />
+      </DSFilterBarActions>
+    </DSFilterBar>
+  );
+};
+```
+
+## Core Patterns
+
+### useFilterBarPrevNextFocus — what it does and why it's required
+
+`useFilterBarPrevNextFocus` returns `runAfterRemoval(fn)`. Call it instead of the removal handler directly:
+
+1. Before the removal: scans all focusable elements inside the filter bar
+2. Executes the removal function
+3. After the DOM updates (via `requestAnimationFrame`): moves focus to the previous pill, the same index, or the last remaining pill
+4. If no pills remain: focuses `fallbackRef` (the menu button)
+
+Without this, keyboard users activating a pill's remove button lose focus when the pill disappears. This is a silent WCAG 2.4.3 (Focus Order) failure — no console error, no axe-core violation on the visible state, but broken keyboard navigation in practice.
+
+`runAfterRemoval` is NOT needed for `DSFilterBarMenuButton.onClearFilters`. That action is triggered from inside the menu button, which persists after clearing. Focus stays on the button naturally.
+
+**Testing note:** because `runAfterRemoval` uses `requestAnimationFrame` internally, Jest tests that assert focus state after removal may be flaky. If focus assertion tests are needed, use Playwright CT which runs in a real browser.
+
+### DSFilterBarMenuButton — options configuration
+
+`onClearFilters` is required — it wires the built-in "Clear filters" menu item. `options` adds custom items below it following the DSMenuButton item shape:
+
+```jsx
+<DSFilterBarMenuButton
+  innerRef={menuButtonRef}
+  onClearFilters={handleClearAll}
+  options={[
+    {
+      dsId: 'restore-defaults',
+      label: 'Restore default filters',
+      type: 'activable-item',
+      onClick: () => {
+        dispatch(restoreDefaultFilters());
+        setAnnouncement('Default filters restored');
+      },
+    },
+  ]}
+/>
+```
+
+## Common Mistakes
+
+### CRITICAL Not wrapping pill removal handlers with runAfterRemoval
+
+Wrong:
+
+```jsx
+<RemovableFilterPill label={filter} onRemove={() => handleSingleFilterRemove(filter)} />
+```
+
+Correct:
+
+```jsx
+<RemovableFilterPill label={filter} onRemove={() => runAfterRemoval(() => handleSingleFilterRemove(filter))} />
+```
+
+When a pill is removed via keyboard, focus is on the pill's remove button. The pill disappears after removal. Without `runAfterRemoval`, focus is stranded — a silent WCAG 2.4.3 (Focus Order) failure. The hook scans focusable elements before removal and moves focus correctly after the DOM updates.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+### CRITICAL Passing fallbackRef to hook but not as innerRef to DSFilterBarMenuButton
+
+Wrong:
+
+```jsx
+const menuButtonRef = useRef(null);
+const { runAfterRemoval } = useFilterBarPrevNextFocus({ filterBarRef, fallbackRef: menuButtonRef });
+<DSFilterBarMenuButton onClearFilters={handleClearAll} />;
+```
+
+Correct:
+
+```jsx
+const menuButtonRef = useRef(null);
+const { runAfterRemoval } = useFilterBarPrevNextFocus({ filterBarRef, fallbackRef: menuButtonRef });
+<DSFilterBarMenuButton innerRef={menuButtonRef} onClearFilters={handleClearAll} />;
+```
+
+`fallbackRef.current` is null until `innerRef` connects it to the DOM element. When the last pill is removed, the hook calls `fallbackRef.current?.focus?.()` — if the ref is null, focus is lost silently. The keyboard user must Tab from the beginning of the page to re-orient.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+### HIGH Omitting ScreenReaderOnly aria-live announcements
+
+Wrong:
+
+```jsx
+const handleSingleFilterRemove = (filter) => {
+  dispatch(removeFilter(filter));
+};
+```
+
+Correct:
+
+```jsx
+const [announcement, setAnnouncement] = useState('');
+
+const handleSingleFilterRemove = (filter) => {
+  dispatch(removeFilter(filter));
+  setAnnouncement(`Filter removed: ${filter}`);
+};
+
+// Inside DSFilterBar:
+<ScreenReaderOnly aria-live="polite">{announcement}</ScreenReaderOnly>;
+```
+
+Screen readers do not announce dynamic DOM changes unless explicitly told to. Without `aria-live="polite"`, screen reader users receive no feedback on filter operations. Every state change (remove single, clear all, restore) must update the announcement string. This is a WCAG 4.1.3 (Status Messages) requirement.
+
+`ScreenReaderOnly` is from `@elliemae/ds-accessibility` — add this import separately alongside the `@elliemae/ds-filter-bar` imports.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+### HIGH Omitting filterBarRef from DSFilterBar
+
+Wrong:
+
+```jsx
+const filterBarRef = useRef(null);
+const { runAfterRemoval } = useFilterBarPrevNextFocus({ filterBarRef, fallbackRef });
+<DSFilterBar>...</DSFilterBar>;
+```
+
+Correct:
+
+```jsx
+<DSFilterBar filterBarRef={filterBarRef}>...</DSFilterBar>
+```
+
+Without `filterBarRef`, the hook's container is null. It skips the focusable-elements scan and immediately focuses `fallbackRef` on every removal — correct only for the last pill, wrong for all others.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+### HIGH Non-primitive filter bar props not memoized
+
+| Prop             | Component               | Memoization                     |
+| ---------------- | ----------------------- | ------------------------------- |
+| `onClearFilters` | `DSFilterBarMenuButton` | `useCallback`                   |
+| `options`        | `DSFilterBarMenuButton` | `useMemo` if constructed inline |
+| `filterBarRef`   | `DSFilterBar`           | `useRef` (stable by definition) |
+| `innerRef`       | `DSFilterBarMenuButton` | `useRef` (stable by definition) |
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+### HIGH Defining RemovableFilterPill inside parent component
+
+Wrong:
+
+```jsx
+const FilterBarComponent = () => {
+  const RemovableFilterPill = ({ label, onRemove }) => <DSPillV2 type="removable" label={label} onRemove={onRemove} />;
+  // ...
+};
+```
+
+Correct:
+
+```jsx
+const RemovableFilterPill = ({ label, onRemove }) => <DSPillV2 type="removable" label={label} onRemove={onRemove} />;
+
+const FilterBarComponent = () => {
+  /* ... */
+};
+```
+
+A component defined inside another component gets a new type identity on every render. React treats each new identity as a different component, unmounting and remounting the subtree — this destroys internal state, re-triggers effects, and causes focus to be lost during the render cycle that follows a pill removal.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+### HIGH Updating filter state without propagating to the data source
+
+The filter bar is UI-only — removing a pill has no effect on displayed data unless the consumer propagates the change to the data source. Before implementing, confirm whether the model is server-side (each filter change dispatches an API call — correct for any non-trivial dataset) or client-side (filters applied to an in-memory array — a temporary workaround while backend endpoints are built, not a design pattern). Client-side filtering is a legitimate interim state when explicitly owned by the team with a documented remediation plan; it becomes a problem when treated as the default.
+
+Source: https://dimsum.mortgagetech.ice.com/iframe.html?id=components-filterbar-features--basic
+
+---
+
+## When composable parts are not enough
+
+If the filter bar assembly cannot satisfy the layout or behavior requirement:
+
+1. Confirm the requirement with UI/UX — most variations are achievable via composition, ordering, and xstyled props on the primitives.
+2. Contact the Dimsum team to validate whether a first-class solution should be added.
+
+**ICE internal:** Microsoft Teams — Dimsum channel (informal) / Jira Dimsum board (formal)
+**Partners:** Your organization's Dimsum point of contact
+
+See also: `@elliemae/ds-data-table` `withFilterBar` integration — if this filter bar is used alongside a DataTable, load the DataTable filtering skill for the integration wiring.

package/skills/ds-filter-bar-slots/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: ds-filter-bar-slots
+description: >
+  Slot injection surface for @elliemae/ds-filter-bar. Verified against v3.60.0 via probe.
+  DSFilterBar (ROOT), DSFilterBarContent (CONTENT), DSFilterBarActions (ACTIONS) have
+  functional slot injection. DSFilterBarMenuButton slot props have no effect — use its
+  OOB props (innerRef, onClearFilters, options) instead. Valid uses: data-*, aria-*,
+  conditional styling. Event listeners through slots are a red flag.
+type: core
+library: ds-filter-bar
+library_version: '3.60.0'
+requires:
+  - ds-filter-bar-setup
+sources:
+  - '@elliemae/ds-filter-bar:dist/types/react-desc-prop-types.d.ts'
+  - '@elliemae/ds-filter-bar:dist/types/parts/DSFilterBarMenuButton/react-desc-prop-types.d.ts'
+---
+
+## Slot surface — DOM hierarchy
+
+Slots are injection points into specific rendered DOM nodes. Understanding the hierarchy is required to inject props at the correct level — injecting `aria-*` at the wrong node produces silent accessibility failures.
+
+**About this map:** Verified against `@elliemae/ds-filter-bar@3.60.0` via probe tests. Slot names are governed by the Dimsum breaking change protocol — renames are intentional and documented. If something doesn't match your installed version, inspect the rendered HTML in your environment. If you cannot do it autonomously, ask the human in the loop to render the component with synthetic data only — not production data containing real user information.
+
+Each entry shows: `slot-key (data-dimsum-slot="value") · tag[role] · notes`.
+
+```
+DSFilterBar renders:
+
+ROOT (dsFilterbarRoot) · div[role="region"]  ← ★ semantic region landmark
+│  inject aria-label here — it labels the landmark for screen readers
+│  inject data-* tracking attributes here
+├── CONTENT (dsFilterbarContent) · div
+│   └── (pill components — DSPillV2 or custom)
+└── ACTIONS (dsFilterbarActions) · div
+    └── DSFilterBarMenuButton  ← no dsFilterbarMenuButton in DOM
+        └── dsMenubuttonRoot · div  (the DOM shows this instead of dsFilterbarMenuButton)
+            └── dsButtonRoot · button
+                └── dsIconRoot · span
+                    └── dsIconSvg · svg
+```
+
+**Key finding — ROOT has `role="region"`:** `dsFilterbarRoot` renders as a semantic region landmark. This means:
+
+- Screen readers announce it as a navigable region
+- `aria-label` passed to `DSFilterBar` (or via `dsFilterbarRoot` slot) labels that region
+- Do not inject a second `role` attribute — it is already set correctly
+
+## When to reach for slots
+
+Try OOB first. `DSFilterBar` accepts standard HTML global attributes (`aria-*`, `data-*`, `className`, `style`) directly as props. Slots are for injecting into a specific internal DOM node rather than the root.
+
+**Event listeners through slots are a red flag.** The filter bar manages its own interaction model. If you need to respond to filter bar interactions, use the OOB callbacks (`onRemove`, `onClearFilters`). If no OOB callback covers your requirement, stop and surface this to the human in the loop.
+
+## Setup
+
+```jsx
+import {
+  DSFilterBar,
+  DSFilterBarContent,
+  DSFilterBarActions,
+} from '@elliemae/ds-filter-bar';
+
+// Inject into the region root
+<DSFilterBar
+  filterBarRef={filterBarRef}
+  dsFilterbarRoot={{ 'aria-label': 'Active loan filters', 'data-section': 'filters' }}
+>
+  ...
+</DSFilterBar>
+
+// Inject into the content area
+<DSFilterBarContent dsFilterbarContent={{ 'data-pills-zone': 'true' }}>
+  ...
+</DSFilterBarContent>
+
+// Inject into the actions area
+<DSFilterBarActions dsFilterbarActions={{ 'data-actions-zone': 'true' }}>
+  ...
+</DSFilterBarActions>
+```
+
+### DSFilterBarMenuButton — no dsFilterbarMenuButton in DOM
+
+`dsFilterbarMenuButton` does not appear in the DOM — the DOM shows `dsMenubuttonRoot` in its place. Passing `dsFilterbarMenuButton` slot props has no effect. Use `innerRef`, `onClearFilters`, and `options` props to interact with this component instead.
+
+## Common Mistakes
+
+### HIGH Injecting event listeners through slot props
+
+The filter bar manages its own interaction model. Injecting `onClick`, `onKeyDown`, or similar through slot props bypasses it and can produce unpredictable behavior. Use OOB callbacks (`onRemove`, `onClearFilters`) instead. If no OOB callback exists for your requirement, surface this to the human in the loop before proceeding.
+
+---
+
+### MEDIUM Slot props not memoized
+
+```jsx
+// Wrong — new object reference on every render
+<DSFilterBar dsFilterbarRoot={{ 'data-id': computedId }} />;
+
+// Correct
+const rootSlotProps = useMemo(() => ({ 'data-id': computedId }), [computedId]);
+<DSFilterBar dsFilterbarRoot={rootSlotProps} />;
+```
+
+## When this isn't enough
+
+**ICE internal:** Microsoft Teams — Dimsum channel (informal) / Jira Dimsum board (formal)
+**Partners:** Your organization's Dimsum point of contact