@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/filter-chips.md

@@ -0,0 +1,323 @@
+# FilterChips
+
+> A wrapping row that summarises the filters currently applied to a data set (the Figma `FilterChips` component): one removable `Chip` per filter, closed by a ghost "Reset filters" action that clears them all at once. Pure layout — it owns no visual styling of its own besides the two gaps. Figma's nested `ListChips` slot maps to `FilterChipsList`'s children.
+
+**Status:** ready · **Category:** data-display · **Since:** v0.63.0
+
+## Import
+
+```tsx
+import { FilterChips, FilterChipsList, FilterChipsReset, Chip } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<FilterChips>
+  <FilterChipsList>
+    {applied.map((filter) => (
+      <Chip
+        key={filter.id}
+        removeLabel={`Remove ${filter.id} filter`}
+        onRemove={() => removeFilter(filter.id)}
+      >
+        {filter.label}
+      </Chip>
+    ))}
+    <FilterChipsReset onClick={resetFilters} />
+  </FilterChipsList>
+</FilterChips>
+```
+
+A wrapping row that summarises the filters currently applied to a data set: one
+removable chip per filter, closed by a ghost "Reset filters" action that clears
+them all at once.
+
+It is pure layout. The only thing it owns is the two gaps the design specifies —
+16px between the root's children and 8px between the items in the chip list. The
+chips are `Chip`s you pass in, and the reset action is a ghost `Button`.
+
+## When to use
+
+- Below a filter toolbar, to show which filters are currently narrowing a table,
+  list or dashboard, and to let a user drop them individually.
+- Wherever a filter selection needs to stay visible after the popover or panel
+  that produced it has closed.
+- When you want the composition under your control — you decide what each chip's
+  label says, whether it carries a leading icon, and whether a reset action is
+  offered at all.
+
+## When not to use
+
+- **To offer the filters themselves.** This row reports a selection; it does not
+  make one. Use `FilterSearchFilters` (a filter popover) or the appropriate input
+  for that.
+- **When you just want the row wired to a filter record.** Use
+  `FilterSearchAppliedFilters`, which renders through these parts and derives the
+  chips from a `filters` object, including hiding itself when the object is empty.
+- **For a single chip, or for chips that select rather than remove.** Use `Chip`
+  directly (`variant="selectable"` / `variant="operational"`).
+- **As a general tag row.** The group is named "Applied filters" and the reset
+  action is a clear-all; a row of non-filter tokens should compose `Chip` itself.
+
+## Examples
+
+### Applied filters with a clear-all
+
+```tsx
+import {
+  Chip,
+  FilterChips,
+  FilterChipsList,
+  FilterChipsReset,
+} from '@acronis-platform/ui-react';
+
+<FilterChips>
+  <FilterChipsList>
+    {applied.map((filter) => (
+      <Chip
+        key={filter.id}
+        removeLabel={`Remove ${filter.id} filter`}
+        onRemove={() => removeFilter(filter.id)}
+      >
+        {filter.label}
+      </Chip>
+    ))}
+    <FilterChipsReset onClick={resetFilters} />
+  </FilterChipsList>
+</FilterChips>;
+```
+
+### Chips with a leading icon
+
+```tsx
+<FilterChips>
+  <FilterChipsList>
+    <Chip icon={<TagIcon size={16} />} removeLabel="Remove type filter">
+      Type: Server
+    </Chip>
+    <Chip icon={<TagIcon size={16} />} removeLabel="Remove OS filter">
+      OS: Linux
+    </Chip>
+    <FilterChipsReset />
+  </FilterChipsList>
+</FilterChips>
+```
+
+### No reset action
+
+Omit `FilterChipsReset` when the surrounding UI already offers a way to clear the
+filters.
+
+```tsx
+<FilterChips ariaLabel="Applied workload filters">
+  <FilterChipsList>
+    <Chip removeLabel="Remove type filter">Type: Server</Chip>
+    <Chip removeLabel="Remove OS filter">OS: Linux</Chip>
+  </FilterChipsList>
+</FilterChips>
+```
+
+### A localized reset label
+
+Every string in the row is consumer-supplied. `FilterChipsReset`'s "Reset filters"
+is only a default; pass your own translated label as its children, and override
+the region's name with `ariaLabel`.
+
+```tsx
+<FilterChips ariaLabel={t('appliedFilters')}>
+  <FilterChipsList>
+    <Chip removeLabel={t('removeTypeFilter')}>{t('filterType')}</Chip>
+    <FilterChipsReset>{t('resetFilters')}</FilterChipsReset>
+  </FilterChipsList>
+</FilterChips>
+```
+
+## Parts
+
+| Part               | Element                   | Notes                                                                                                                                                    |
+| ------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FilterChips`      | `div` (`role="group"`)    | Root row. Carries the region's accessible name (`ariaLabel`, default "Applied filters") and the 16px gap between its children. Polymorphic via `render`. |
+| `FilterChipsList`  | `div`                     | The wrapping chip container — 8px gap in both axes, wrapped lines centered. Maps to the Figma `ListChips` slot.                                          |
+| `FilterChipsReset` | `button` (ghost `Button`) | The clear-all action. Label is `children`, defaulting to "Reset filters". Composed as the **last child of the list**, not beside it.                     |
+
+`Chip` is not a part of this component — the chips are your children. Use
+`variant="removable"` (Chip's default) and give each one a `removeLabel` that
+names the filter it drops.
+
+## Notes
+
+- **The reset action belongs inside the list.** The design measures 8px between
+  the last chip and the button, which is the list's gap. Placing it as a sibling
+  of the list would render it 16px away and wrap independently of the chips.
+- **No empty state.** The row renders whatever it is given, including nothing;
+  the design defines no empty appearance. Deciding not to render the row when no
+  filters are applied is the consumer's call —
+  `FilterSearchAppliedFilters` makes that call for you.
+- **Theming.** No `--ui-filter-chips-*` tier exists and none is needed. The row
+  consumes `--ui-gap-16` and `--ui-gap-8`; everything visible comes from
+  `--ui-chip-*` and `--ui-button-ghost-*`.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `ariaLabel` | `string` | `Applied filters` | no | `FilterChips` (root) only. Accessible name for the applied-filter region, which the root exposes as `role="group"`. Override to localize. |
+| `render` | `RenderProp` | `undefined` | no | Base UI composition prop on `FilterChips` (root, replaces the `<div>`) and on `FilterChipsReset` (replaces the `<button>`) — merges props and classes onto the supplied element or component. React-only; other frameworks use their own polymorphism. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | `FilterChipsReset` only. Emitted when the clear-all action is pressed. Removing an individual filter is the chip's own `remove` event — see Chip's spec. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | On `FilterChips`, the `FilterChipsList` (plus anything a consumer places beside the whole list, separated by the root's 16px gap). On `FilterChipsList`, one removable `Chip` per applied filter followed by an optional `FilterChipsReset`. On `FilterChipsReset`, the action's label, defaulting to "Reset filters". |
+
+## Behavior
+
+`FilterChips` is a layout composition: it renders whatever chips and actions the
+consumer passes in and owns no state of its own. The scenarios below describe
+the contract the parts establish together; the chip's own remove button and the
+reset button's press feedback are specified in Chip's and Button's behavior docs.
+
+### Layout
+
+**Given** a `FilterChips` root containing a `FilterChipsList`
+**When** the list holds several chips
+**Then** the chips sit in a single row 8px apart, vertically centered against the
+32px row height (the reset button's height), and the root leaves 16px between the
+list and any sibling placed beside it.
+
+**Given** a `FilterChipsList` whose chips exceed the available width
+**When** the row is laid out
+**Then** the chips wrap onto additional lines, keeping the same 8px gap between
+lines, and the wrapped lines stay centered against the row (`content-center`).
+The component never clips a chip and never scrolls; the row grows taller instead.
+
+**Given** a chip whose label is wider than the space available to it
+**When** the row is laid out
+**Then** the chip truncates its own label with an ellipsis rather than pushing the
+row wider — see Chip's spec.
+
+### Removing a single filter
+
+**Given** a removable `Chip` inside the list
+**When** the user presses the chip's × button
+**Then** the chip emits `remove`; the consumer drops that filter from its state
+and the chip disappears on the next render, with the remaining chips reflowing to
+close the gap. `FilterChips` does not remove the chip itself.
+
+### Clearing every filter
+
+**Given** a `FilterChipsReset` composed as the last child of the list
+**When** the user presses it
+**Then** it emits `click`; the consumer clears its filter state and every chip
+disappears on the next render.
+
+**Given** a `FilterChipsReset` with `disabled`
+**When** the user presses it
+**Then** nothing is emitted and the button shows the ghost variant's disabled
+styling.
+
+### Empty state
+
+**Given** a consumer with no applied filters
+**When** it renders
+**Then** it is the consumer's decision whether to render an empty
+`FilterChips` (a 32px-tall empty row) or nothing at all. `FilterChips` renders
+whatever it is given and does not hide itself — the design has no empty state.
+The data-driven `FilterSearchAppliedFilters` wrapper, which owns the filter
+record, is the part that returns nothing when there are no filters.
+
+### Composition
+
+**Given** the reset action
+**When** it is composed
+**Then** it belongs inside `FilterChipsList`, not beside it — the design measures
+8px between the last chip and the button, which is the list's gap, not the root's
+16px.
+
+**Given** a `render` prop on the root
+**When** it is supplied
+**Then** the root renders as that element or component instead of a `<div>`, with
+the group role, accessible name and layout classes merged onto it.
+
+### Right-to-left
+
+**Given** an ancestor with `dir="rtl"`
+**When** the row is laid out
+**Then** the chips and the reset action flow from the right edge and wrap
+right-to-left; the chip's × sits at the label's trailing (left) edge. The row
+uses no physical directional utilities, so this needs no extra prop.
+
+## Accessibility
+
+## Roles and ARIA
+
+- The **root** is a `role="group"` with an accessible name from `ariaLabel`
+  (default `"Applied filters"`). This gives the region a landmark-like
+  announcement so a screen-reader user can tell the applied-filter summary apart
+  from the controls that produced it. Override `ariaLabel` to localize it or to
+  name the specific data set ("Applied workload filters").
+- The **list** is a plain container with no role. It is deliberately not a
+  `list`/`listitem` structure: `Chip` renders a `<div>`, so imposing list
+  semantics would require the consumer to wrap every chip in an `<li>`, and the
+  chips are already individually announced through their remove buttons.
+- Each **chip** is presentational apart from its remove button; that button
+  carries its own accessible name via Chip's `removeLabel`. Always give it a name
+  that identifies _which_ filter it removes ("Remove type filter") — a row of
+  buttons all named "Remove" is ambiguous out of context.
+- The **reset** action is a native `<button type="button">` whose accessible name
+  is its visible label. It is not `aria-disabled`-only: when it is unavailable it
+  is really `disabled`, so it leaves the tab order.
+
+## Keyboard
+
+- The row adds no keyboard behavior of its own: it is a sequence of native
+  buttons in DOM order. `Tab` / `Shift+Tab` moves through each chip's remove
+  button and then the reset action; `Enter` / `Space` activates the focused
+  button.
+- No arrow-key roving is implemented. The chips are independent controls rather
+  than a single composite widget, so the sequential tab order is the expected
+  pattern; adding roving focus would hide the remove buttons from users who
+  navigate by `Tab` alone.
+- Removing the last chip in the list moves focus out of the removed element.
+  Consumers that clear filters one by one should move focus deliberately — to the
+  reset action, or to the filter trigger once the row empties — so focus never
+  lands on `<body>`.
+
+## Screen reader
+
+- Entering the region announces the group and its name, then each chip's label
+  followed by its remove button's name.
+- Removals and resets are not announced by the component. A consumer whose result
+  set changes as a result should own that announcement (for example a live region
+  reporting the new result count), because only the consumer knows what the
+  filter change did.
+
+## Focus visibility
+
+- Focus indication comes from the composed parts: the chip shows the 3px
+  `--ui-focus-primary` ring around the whole pill when its remove button takes
+  focus (`focus-within`), and the reset button shows the same ring on
+  `focus-visible`. The row itself is not focusable and draws no ring.
+
+## Contrast
+
+- The row contributes no colors, so contrast is Chip's and Button's
+  responsibility. Both are verified in their own specs against WCAG 2.1 AA in
+  light and dark themes.
+- The reset action is a ghost button — a text-only control. Its idle label color
+  (`--ui-button-ghost-label-color-idle`) must clear 4.5:1 against the surface the
+  row sits on, which is Button's contract; do not place the row on a custom
+  background that has not been checked against it.
+
+## Right-to-left
+
+- The row mirrors under `dir="rtl"` with no extra props: it uses logical flex
+  ordering only, and it contains no directional artwork. The chip's × is
+  direction-agnostic and must not be flipped.