@apliteni/apliteni-ui 0.85.1 → 0.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.85.1",
+  "version": "0.87.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -786,3 +786,36 @@ use it to stay the same whenever they run. `locale` names the months and weekday
 the trigger's trailing edge. Without `ariaLabel` the trigger's own text is its accessible
 name, so a control reading "17 September 2026" is heard as that rather than as its
 placeholder. The popover stays mounted while closed, and is `inert` while it is.
+
+## AccentPicker
+
+`AccentPicker` is a controlled group of the kit’s four accent swatches. Pass `value`
+and `onChange`; optionally pass `options` to choose a subset or its order. Values are
+`default`, `phoenix`, `ocean`, and `emerald` (`Accent`). Import the kit CSS.
+
+```tsx
+<AccentPicker value={accent} onChange={setAccent} />
+```
+
+Each button has an accessible name and a pressed state. Tab visits each choice;
+Enter and Space request a change without submitting a surrounding form. The host
+owns setting `data-accent` on the page and persisting the choice. The component does
+neither. A value outside `options` leaves every button unpressed; an empty list
+renders an empty group. Supply unique options.
+
+The group accepts native div attributes, an additional `className`, and a forwarded
+ref. Its default accessible name is “Accent”; override it with `aria-label` or
+`aria-labelledby` when multiple pickers need distinct names.
+
+It emits no `data-accent-pick` on its buttons, so a page that calls
+`wireTopbar(document)` — which a half-migrated page must, to wire its vanilla
+`footer({ switcher: accentPicker() })` — cannot adopt a picker React owns, apply the
+accent and persist it behind your `onChange`. This is the same decision `Dropdown`,
+`Drawer` and `ThemeToggle` make with their own wiring hooks.
+
+The selected swatch is marked by a tick inside the circle, in the kit's ink for a
+saturated fill. Focus is the kit ring (`--ring`) and it is the only accent edge the
+control ever draws: selection and focus are one signal each, and only focus is an
+accent. Accent names and swatch paints come from the kit's `ACCENTS` and
+`accentSwatchStyle`, which the vanilla factory also reads, so the two pickers cannot
+drift.

package/react/dist/index.css

@@ -58,6 +58,10 @@
     --tap-clear-x: var(--space-1, 4px);
     --tap-clear-y: var(--tap-gap);
   }
+  .ui-seg--underline {
+    row-gap: var(--space-1, 4px) !important;
+    --tap-clear-y: var(--space-1, 4px);
+  }
   .ui-tabs__list {
     --tap-clear-x: 2px;
     --tap-clear-y: var(--tap-gap);

package/react/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { InputHTMLAttributes, ReactNode, ButtonHTMLAttributes, RefAttributes, ReactElement, AnchorHTMLAttributes, HTMLAttributes, RefObject, MouseEvent, ElementType, ComponentPropsWithoutRef, SelectHTMLAttributes, TextareaHTMLAttributes, SVGAttributes } from 'react';
+import { ACCENTS } from '@apliteni/apliteni-ui';
 
 declare function Icon({ name }: {
     name: string;
@@ -931,7 +932,19 @@ declare const SidebarNav: react.ForwardRefExoticComponent<Omit<Omit<react.Detail
     renderLink?: (item: SidebarNavItem, props: ComponentPropsWithoutRef<"a">) => ReactNode;
 } & react.RefAttributes<HTMLElement>>;
 
+type Accent = (typeof ACCENTS)[number];
+type AccentPickerProps = Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> & {
+    value: Accent;
+    onChange: (value: Accent) => void;
+    options?: readonly Accent[];
+};
+declare const AccentPicker: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    value: Accent;
+    onChange: (value: Accent) => void;
+    options?: readonly Accent[];
+} & react.RefAttributes<HTMLDivElement>>;
+
 declare const PAGE_SIZES: readonly number[];
 declare const DEFAULT_PAGE_SIZE: number;
 
-export { AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };
+export { type Accent, AccentPicker, type AccentPickerProps, AppShell, type AppShellProps, type AppShellSection, BackLink, type BackLinkOwnProps, type BackLinkProps, Badge, BusyRegion, type BusyRegionProps, Button, type ButtonLinkProps, type ButtonProps, Callout, type CalloutProps, type CalloutVariant, Card, Checkbox, type CheckboxProps, type Column, type CommandGroup, type CommandItem, CommandPalette, type CommandPaletteProps, Confirm, type ConfirmProps, DEFAULT_PAGE_SIZE, DataTable, type DataTableProps, DatePicker, type DatePickerMode, type DatePickerPreset, type DatePickerProps, type DatePickerRange, DeltaValue, type DeltaValueProps, Denied, type DeniedProps, Drawer, type DrawerProps, DrawerSection, type DrawerSectionProps, Dropdown, type DropdownBadge, type DropdownEntry, type DropdownItem, type DropdownProps, type DropdownRowProps, type DropdownSearch, type DropdownSection, type DropdownSeparator, EmptyState, type EmptyStateProps, type EmptyStateVariant, Field, type FieldControlProps, type FieldProps, FileDrop, type FileDropFile, type FileDropProps, type FileDropStatus, FileField, type FileFieldProps, type Filter, FilterBar, type FilterBarProps, Icon, KeyValueList, type KeyValueListProps, type KeyValueRow, Modal, type ModalProps, type NativeButtonProps, NumericValue, type NumericValueProps, PAGE_SIZES, Pagination, type PaginationProps, Pill, type PillProps, RowIdentity, type RowIdentityProps, SearchField, type SearchFieldProps, type SegmentOption, Segmented, type SegmentedProps, SelectField, type SelectFieldProps, SidebarNav, type SidebarNavBadge, type SidebarNavItem, type SidebarNavLeaf, type SidebarNavProps, type SidebarNavSection, Skeleton, type SkeletonProps, SkeletonTable, type SkeletonTableProps, Snippet, type SnippetProps, StatBand, type StatBandProps, type StatDelta, type StatFigure, type StatTone, type StatVariant, StatusDot, type StatusDotProps, Success, SuccessCheck, type SuccessCheckProps, type SuccessCountdown, SuccessPanel, type SuccessPanelProps, type SuccessProps, Switch, type SwitchProps, THEME_INIT_SCRIPT, type TabItem, type TableSort, Tabs, type TabsProps, TextArea, type TextAreaProps, TextField, type TextFieldProps, ThemeToggle, type ThemeToggleProps, Timeline, type TimelineEvent, type TimelineEventKind, type TimelineProps, Toast, type ToastNotice, type ToastProps, Tooltip, type TooltipProps, sortTableRows, useToast };

package/react/dist/index.js

@@ -2412,7 +2412,7 @@ function Segmented({ options, value, onChange, label, appearance = "pill", disab
 
 // src/FilterBar.tsx
 import { useRef as useRef12, useState as useState8 } from "react";
-import { filterChipText, filterChipName, filterChipUnset } from "@apliteni/apliteni-ui";
+import { filterChipText, filterChipName, filterChipUnset, focusNextStop } from "@apliteni/apliteni-ui";
 import { jsx as jsx24, jsxs as jsxs19 } from "react/jsx-runtime";
 function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters", disabled = false, busy = false, onRemove, onClear, onChange }) {
   const bar = useRef12(null);
@@ -2428,7 +2428,8 @@ function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters
     const next = chips.slice(prior.index).find((chip) => !chip.disabled) || chips.slice(0, prior.index).reverse().find((chip) => !chip.disabled);
     const target = !blocked && next?.querySelector("[data-dropdown-trigger]");
     focused.current = null;
-    (target || bar.current)?.focus();
+    if (target) target.focus();
+    else focusNextStop(bar.current);
   });
   return /* @__PURE__ */ jsx24("div", { children: /* @__PURE__ */ jsxs19(
     "fieldset",
@@ -2486,9 +2487,9 @@ function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters
           },
           filter.id
         )),
-        /* @__PURE__ */ jsx24("span", { "data-filter-clear": "", onFocus: () => {
+        filters.length > 0 && /* @__PURE__ */ jsx24("span", { "data-filter-clear": "", onFocus: () => {
           focused.current = { id: null, index: 0 };
-        }, children: /* @__PURE__ */ jsx24(Button, { size: "sm", variant: "ghost", disabled: !filters.length, onClick: () => {
+        }, children: /* @__PURE__ */ jsx24(Button, { size: "sm", onClick: () => {
           if (!blocked) onClear();
         }, children: clearLabel }) })
       ]
@@ -3646,10 +3647,52 @@ var Success = forwardRef9(function Success2({
   );
 });
 
+// src/AccentPicker.tsx
+import { forwardRef as forwardRef10 } from "react";
+import { ACCENTS, accentSwatchStyle } from "@apliteni/apliteni-ui";
+import { jsx as jsx38 } from "react/jsx-runtime";
+var AccentPicker = forwardRef10(function AccentPicker2({
+  value,
+  onChange,
+  options = ACCENTS,
+  className,
+  "aria-label": label = "Accent",
+  ...rest
+}, ref) {
+  return /* @__PURE__ */ jsx38(
+    "div",
+    {
+      ...rest,
+      ref,
+      className: ["ui-accent-picker", className].filter(Boolean).join(" "),
+      "data-accent-group": "",
+      role: "group",
+      "aria-label": label,
+      children: options.map((accent) => {
+        const title = accent.charAt(0).toUpperCase() + accent.slice(1);
+        return /* @__PURE__ */ jsx38(
+          "button",
+          {
+            type: "button",
+            className: accent === value ? "is-active" : void 0,
+            style: accentSwatchStyle(accent),
+            "aria-pressed": accent === value,
+            "aria-label": `${title} accent`,
+            title,
+            onClick: () => onChange(accent)
+          },
+          accent
+        );
+      })
+    }
+  );
+});
+
 // src/index.ts
 var PAGE_SIZES = KIT_PAGE_SIZES;
 var DEFAULT_PAGE_SIZE3 = KIT_DEFAULT_PAGE_SIZE;
 export {
+  AccentPicker,
   AppShell,
   BackLink,
   Badge,

package/src/components/filter-bar.js

@@ -1,6 +1,6 @@
 import { button, esc } from './index.js';
 import { dropdown, wireDropdown } from './dropdown.js';
-import { filterChipText, filterChipName, filterChipUnset } from '../logic/filter-bar.js';
+import { filterChipText, filterChipName, filterChipUnset, focusNextStop } from '../logic/filter-bar.js';
 
 export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear all filters', disabled = false, busy = false } = {}) {
   return `<fieldset class="ui-filter-bar" data-filter-bar${disabled || busy ? ' disabled' : ''}${busy ? ' aria-busy="true"' : ''}>`
@@ -13,7 +13,17 @@ export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear
         triggerContent: `<span class="${filterChipUnset(filter) ? 'ui-dropdown__value is-placeholder' : 'ui-dropdown__value'}">${esc(filterChipText(filter))}</span>`,
         ariaLabel: filterChipName(filter), open: !!filter.open && !disabled && !busy && !filter.disabled })
       + `<button type="button" class="ui-filter-bar__remove" data-filter-remove aria-label="${esc(`Remove ${filter.label} filter`)}">×</button></fieldset>`).join('')
-    + `<span data-filter-clear>${button({ label: clearLabel, size: 'sm', variant: 'ghost', disabled: !filters.length })}</span></fieldset>`;
+    // Nothing to clear, no control: an unavailable action standing in an empty
+    // row is the only thing in it, and it reads as a bar that has been turned
+    // off rather than one with no filters on it. It is the kit's own `one-page`
+    // rule — a control with no action to offer is not shown. It returns with
+    // the first chip, in the bordered skin rather than the ghost one, because a
+    // live action beside two chips has to read as live.
+    // why: docs/specification.md#a-filter-row-holds-its-panels
+    + (filters.length
+      ? `<span data-filter-clear>${button({ label: clearLabel, size: 'sm' })}</span>`
+      : '')
+    + '</fieldset>';
 }
 
 // The host stays mounted; update() restores the action's focus after controlled removal.
@@ -38,7 +48,9 @@ export function initFilterBar(host, options = {}) {
     const control = target?.querySelector(same && focus.remove ? '[data-filter-remove]' : '[data-dropdown-trigger]')
       || host.querySelector('[data-filter-clear] button');
     if (control && !control.disabled && !control.closest('fieldset:disabled')) control.focus();
-    else { const bar = host.querySelector('[data-filter-bar]'); bar.tabIndex = -1; bar.focus(); }
+    // No control of its own left to hold it: the shared pair decides where the
+    // focus goes and checks that it arrived. why: src/logic/filter-bar.js
+    else focusNextStop(host);
   };
   const emit = (type, detail) => host.dispatchEvent(new host.ownerDocument.defaultView.CustomEvent(type, { bubbles: true, detail }));
   const click = e => {

package/src/components/index.js

@@ -1,4 +1,5 @@
 import { calloutIcons } from '../logic/callout.js';
+import { ACCENTS, accentSwatchStyle } from '../logic/accents.js';
 export { calloutIcons } from '../logic/callout.js';
 // apliteni-ui component factories — each returns an HTML string, matching the
 // viz/ server-render idiom so the portal can adopt them with no framework.
@@ -99,25 +100,16 @@ export function segmented({ options = [], active = 0, size, block, name = 'seg',
 }
 
 // ---- Accent picker -------------------------------------------------------
-// Each swatch is made of the tokens its accent selects: it fades from the next
-// distinct step up that accent's dark ramp down to dark --accent. Most accents
-// land on --purple-light; Nebula's is its own --accent since #157, so it walks
-// on to --purple-mid. site/chrome.mjs and site/index.html hand-keep the same
-// four strings and must change with these. Held by stories/accent-swatch.test.js,
-// which derives both sides rather than restating them. See issue #190.
-const ACCENT_SWATCH = {
-  default: 'linear-gradient(135deg,#bd8cff,#b479ff)',
-  phoenix: 'linear-gradient(135deg,#ff8a5c,#ff6a3d)',
-  ocean: 'linear-gradient(135deg,#5ab0ff,#3b9dff)',
-  emerald: 'linear-gradient(135deg,#3ad9a0,#16c98a)',
-};
+// The accent list and every swatch's paints live in ../logic/accents.js, which
+// the React picker reads too, so neither copy can drift from the other.
 // Swatches have no text and no glyph at all — the aria-label is the whole
 // accessible name, and aria-pressed carries which one is on.
-export function accentPicker({ active = 'default', options = ['default', 'phoenix', 'ocean', 'emerald'] } = {}) {
+export function accentPicker({ active = 'default', options = ACCENTS } = {}) {
   const title = (o) => o.charAt(0).toUpperCase() + o.slice(1);
+  const style = (o) => Object.entries(accentSwatchStyle(o)).map(([k, v]) => `${k}:${v}`).join(';');
   return `<div class="ui-accent-picker" data-accent-group role="group" aria-label="Accent">${options.map((o) =>
     `<button type="button" data-accent-pick="${esc(o)}"${o === active ? ' class="is-active"' : ''}`
-    + ` style="--swatch:${ACCENT_SWATCH[o] || 'transparent'}" aria-pressed="${o === active ? 'true' : 'false'}"`
+    + ` style="${style(o)}" aria-pressed="${o === active ? 'true' : 'false'}"`
     + ` aria-label="${esc(title(o))} accent" title="${esc(title(o))}"></button>`).join('')}</div>`;
 }
 

package/src/components/topbar.js

@@ -119,7 +119,8 @@ export function applyTheme(t, root = document.documentElement) {
 }
 
 const ACCENT_KEY = 'apliteni-strategy-accent';
-export const ACCENTS = ['default', 'phoenix', 'ocean', 'emerald'];
+// One list for the pickers, this wiring and the React component.
+export { ACCENTS } from '../logic/accents.js';
 
 export function applyAccent(name, root = document.documentElement) {
   if (!name || name === 'default') root.removeAttribute('data-accent');

package/src/index.d.ts

@@ -10,6 +10,8 @@ export declare function initFilterBar(host: Element, opts?: Record<string, unkno
 export declare function filterChipText(filter?: { label?: string; value?: string }): string;
 export declare function filterChipName(filter?: { label?: string; value?: string }): string;
 export declare function filterChipUnset(filter?: { value?: string }): boolean;
+export declare function nextFocusStop(host: Element | null | undefined): HTMLElement | null;
+export declare function focusNextStop(host: Element | null | undefined): HTMLElement | null;
 export declare function segmentedNextIndex(key: string, index: number, length: number): number | null;
 export declare function icon(name: string, className?: string): string;
 export declare function snippet(opts?: Record<string, unknown>): string;
@@ -53,6 +55,10 @@ export declare function illo(name: string): string;
 export * from './motion.js';
 export declare const illoNames: string[];
 
+// The custom properties one accent swatch button carries. ACCENTS is declared
+// with the topbar wiring that re-exports it.
+export declare function accentSwatchStyle(accent: string): Record<string, string>;
+
 // Vanilla factories accept their existing option bags and return HTML.
 export declare function accentPicker(opts?: Record<string, unknown>): string;
 export declare function accountMenu(opts?: Record<string, unknown>): string;
@@ -96,7 +102,8 @@ export declare function themeName(theme: string): string;
 export declare function themeToggle(theme?: string): string;
 export declare function versionSwitcher(versions?: { label: string; meta?: string; badge?: string }[], activeIdx?: number): string;
 
-export declare const ACCENTS: string[];
+// A tuple, so React can derive its Accent union from it.
+export declare const ACCENTS: readonly ['default', 'phoenix', 'ocean', 'emerald'];
 export declare const ACCOUNT_NAV: { id: string; icon: string; label: string }[];
 export declare const RAIL_COOKIE: 'apliteni-ui-rail';
 export declare const STAT_TONES: string[];

package/src/index.js

@@ -30,7 +30,8 @@ export * from './components/filter-bar.js';
 export { dropdownMatch, dropdownFiltering } from './logic/dropdown.js';
 export { SCORE, rankGroups, rankCommands, scoreCommand, paletteHotkey } from './logic/command-palette.js';
 export { segmentedNextIndex } from './logic/segmented.js';
-export { filterChipText, filterChipName, filterChipUnset } from './logic/filter-bar.js';
+export { filterChipText, filterChipName, filterChipUnset, nextFocusStop, focusNextStop } from './logic/filter-bar.js';
 export { PAGE_SIZES, DEFAULT_PAGE_SIZE } from './logic/pagination.js';
 export { calloutIcons } from './logic/callout.js';
 export { formatNumericValue, formatDeltaValue } from './logic/table-values.js';
+export { accentSwatchStyle } from './logic/accents.js';

package/src/logic/accents.js

@@ -0,0 +1,35 @@
+// The accents the kit ships, and the paints one accent swatch needs.
+//
+// Every copy of the picker reads this module, so there is one list and one set of
+// paints rather than a copy per renderer. src/components/index.js and
+// react/src/AccentPicker.tsx call accentSwatchStyle(); site/chrome.mjs and
+// site/index.html still hand-keep the same four gradients. Held by
+// stories/accent-swatch.test.js, which derives both sides out of src/tokens/.
+// why: docs/specification.md#react-accent-picker. See issues #190 and #429.
+export const ACCENTS = ['default', 'phoenix', 'ocean', 'emerald'];
+
+// Per accent, the gradient's two stops — each the value src/tokens/ declares for
+// that accent. The swatch gate reads the tokens and this table apart and
+// compares them.
+const PAINTS = {
+  default: { from: '#bd8cff', to: '#b479ff' },
+  phoenix: { from: '#ff8a5c', to: '#ff6a3d' },
+  ocean: { from: '#5ab0ff', to: '#3b9dff' },
+  emerald: { from: '#3ad9a0', to: '#16c98a' },
+};
+
+/**
+ * The custom properties one swatch button carries, as property → value.
+ *
+ * An accent with no entry here gets `--swatch: transparent`, which is what it
+ * had before this module existed: the strip shows an empty circle you can still
+ * press, and the swatch gate reports it by name. Selected, that circle wears the
+ * same near-black tick, which is ink for a fill rather than for the surface
+ * showing through it — a cost that belongs to the missing paints, not the mark.
+ * Painting the circle as some other accent would be worse.
+ */
+export function accentSwatchStyle(accent) {
+  const paint = PAINTS[accent];
+  if (!paint) return { '--swatch': 'transparent' };
+  return { '--swatch': `linear-gradient(135deg,${paint.from},${paint.to})` };
+}

package/src/logic/filter-bar.js

@@ -1,4 +1,5 @@
-/* What a filter chip shows, what it is called, and when it counts as unset.
+/* What a filter chip shows, what it is called, when it counts as unset, and
+ * where the focus goes when the bar runs out of controls.
  * The chip prints the chosen value by itself — never the field's name beside it
  * — and the field's name stands in while nothing is chosen. Both faces ask
  * these, so a chip reads the same in vanilla and in React.
@@ -27,3 +28,78 @@ export function filterChipName(filter = {}) {
   if (!field) return text(filter.value);
   return filterChipUnset(filter) ? `${field}: any` : `${field}: ${text(filter.value)}`;
 }
+
+/* compareDocumentPosition's own flags, without reaching for a `Node` global
+   that a test environment need not define. */
+const FOLLOWING = 4;
+const PRECEDING = 2;
+
+/** A tab stop the focus cannot actually land on. `hidden`, a disabled fieldset and
+ *  `inert` are read off the document; `visibility` and `display` are read off the
+ *  cascade, because a `visibility: hidden` control keeps its box and so passes any
+ *  test made of rectangles. Each of them refuses `focus()` in a browser, and a
+ *  refusal is silent: the focus lands on the body, with no ring on anything and
+ *  the next Tab starting over from the top of the page. */
+function unreachable(el) {
+  if (el.tabIndex < 0 || el.disabled || el.inert) return true;
+  if (el.closest('[hidden],[inert],fieldset:disabled')) return true;
+  const view = el.ownerDocument.defaultView;
+  const style = view && view.getComputedStyle(el);
+  return !!style && (style.visibility === 'hidden' || style.visibility === 'collapse'
+    || style.display === 'none');
+}
+
+/** The controls a reader's Tab reaches from `host`, in the order the focus should
+ *  try them: forward in document order, then back from `host`.
+ *
+ *  It reads the document, not the layout. Where boxes are measurable, a control
+ *  that draws nothing is skipped; where nothing has a box — JSDOM has no layout
+ *  — every tab stop counts, so the answer stays the document's order rather than
+ *  becoming empty. */
+function stopsAround(host) {
+  const doc = host && host.ownerDocument;
+  if (!doc) return [];
+  const stops = [...doc.querySelectorAll('a[href],button,input,select,textarea,[tabindex]')]
+    .filter(el => !host.contains(el) && !unreachable(el));
+  const drawn = stops.filter(el => el.getClientRects().length);
+  const order = drawn.length ? drawn : stops;
+  return [...order.filter(el => host.compareDocumentPosition(el) & FOLLOWING),
+    ...order.filter(el => host.compareDocumentPosition(el) & PRECEDING).reverse()];
+}
+
+/** The control a reader's next Tab would reach from `host`: forward in document
+ *  order, else the nearest one behind it. A filter bar that has just dropped its
+ *  last control keeps no box the focus ring can sit on, so the focus has to
+ *  leave the bar rather than land on a line with no height.
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+export function nextFocusStop(host) {
+  return stopsAround(host)[0] || null;
+}
+
+/** Puts the focus where an emptied bar hands it on, and answers with the element
+ *  it ended on, or null if nothing took it.
+ *
+ *  A bar that still holds chips draws a box around them, so it takes the focus
+ *  itself, made focusable for that moment. Emptied, it has only an out-of-flow
+ *  legend left and measures 0 high, so the focus goes to the first control
+ *  outside it that will have it — on the Stock screener the caller's own
+ *  `Add filter`, in the React Finance composition the view strip's chosen tab.
+ *
+ *  Being reachable is not the same as taking the focus: a control can be visible
+ *  and enabled and still refuse, so each candidate is asked and then checked, and
+ *  the next one tried.
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+export function focusNextStop(host) {
+  const doc = host && host.ownerDocument;
+  if (!doc) return null;
+  const bar = host.matches('[data-filter-bar]') ? host : host.querySelector('[data-filter-bar]');
+  if (bar && bar.querySelector('[data-filter-id]')) {
+    bar.tabIndex = -1; bar.focus();
+    return doc.activeElement === bar ? bar : null;
+  }
+  for (const stop of stopsAround(host)) {
+    stop.focus();
+    if (doc.activeElement === stop) return stop;
+  }
+  return null;
+}

package/src/styles/filter-bar.css

@@ -23,3 +23,19 @@
    and off the page. It inherits, reaching an option's label and description.
    why: docs/specification.md#a-filter-row-holds-its-panels */
 .ui-filter-bar .ui-dropdown__panel { min-width: 100%; max-width: 100%; overflow-wrap: anywhere; }
+/* The clear action takes the kit's bordered skin minus its fill: words belong on
+   the page, not on a grey block, in any state — Artur, round r28. Rest stays at
+   (0,1,1) so `.ui-btn:hover`'s accent wash still outranks it; the rules under it
+   answer each state that paints a NEUTRAL fill, one step above the kit rule
+   writing it. Held by filter-bar.test.js. why: docs/specification.md#a-filter-row-holds-its-panels */
+[data-filter-clear] button { background: transparent; }
+.ui-filter-bar [data-filter-clear] button:disabled,
+.ui-filter-bar [data-filter-clear] button[aria-disabled="true"],
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"],
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"]:hover,
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"]:active,
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"][data-btn-disabled] { background: transparent; }
+/* No fill, so the label is read on the page: the ink button-disabled.test.js
+   measures on every ground. The edge stays the kit's --disabled-border. */
+.ui-filter-bar [data-filter-clear] button:disabled,
+.ui-filter-bar [data-filter-clear] button[aria-disabled="true"] { /* muted-ink: state — the clear action is off and its words sit on the page */ color: var(--disabled-ink-bare); }

package/src/styles/segmented.css

@@ -54,7 +54,7 @@
 .ui-seg--block { display: flex; align-self: stretch; justify-self: stretch; }
 .ui-seg--block button { flex: 1; }
 
-/* Accent picker — round colour swatches, active gets a ring */
+/* Accent picker — round colour swatches, the selected one ticked */
 .ui-accent-picker { display: inline-flex; gap: 10px; align-items: center; }
 .ui-accent-picker button {
   width: 26px;
@@ -63,19 +63,85 @@
   border: 0;
   padding: 0;
   cursor: pointer;
+  position: relative;
   background: var(--swatch, var(--accent));
   box-shadow: 0 0 0 2px var(--surface), 0 0 0 2px var(--surface);
   transition: transform var(--dur-fast) var(--ease), box-shadow var(--dur-fast) var(--ease);
 }
 .ui-accent-picker button:hover { transform: scale(1.08); }
-.ui-accent-picker button.is-active {
-  box-shadow: 0 0 0 2px var(--surface), 0 0 0 4px var(--swatch, var(--accent));
+/* Selected is a tick inside the circle, not a second ring around it: one element
+ * carries one accent signal, and on a focusable control that signal is the kit's
+ * focus ring. The mark is the one .ui-check draws for a checked box, at the same
+ * 2px stroke, in --signal-contrast — the circle wears the accent's dark ramp in
+ * both themes, so its ink is the one for a fill, not the --accent-contrast that
+ * pairs with --accent-strong. Held by stories/accent-mark.test.js.
+ * why: docs/specification.md#react-accent-picker */
+.ui-accent-picker button.is-active::after {
+  content: "";
+  position: absolute;
+  left: 50%;
+  /* Lifted 2px: turning the box leaves the drawn corner below its middle. */
+  top: calc(50% - 2px);
+  width: 6px;
+  height: 11px;
+  border: solid var(--signal-contrast);
+  border-width: 0 2px 2px 0;
+  transform: translate(-50%, -50%) rotate(45deg); /* motion: still — the turn is the tick's shape, not travel, and the mark lands with the press that asked for it. Nothing else on the swatch changes with selection, so there is no paint for it to arrive with. */
 }
 .ui-accent-picker button:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
-.ui-seg--underline { flex-wrap: nowrap; align-self: stretch; justify-self: stretch; background: transparent; --ring-gap: inherit; border-radius: 0; border-bottom: 1px solid var(--border); padding: var(--space-1); overflow: auto; max-width: 100%; }
-.ui-seg--underline button { border-radius: var(--radius-xs); border-bottom: 2px solid transparent; padding: var(--space-3); white-space: nowrap; }
+/* Underline tabs wrap for the reason the pills above do — #435 — and draw no
+   rule of their own: the chosen tab carries the selection. #527, #545
+   why: docs/specification.md#the-chosen-tab-in-an-underline-strip */
+.ui-seg--underline { flex-wrap: wrap; overflow: visible; row-gap: var(--space-1); align-self: stretch; justify-self: stretch; background: transparent; --ring-gap: inherit; border-radius: 0; padding: var(--space-1); max-width: 100%; }
+/* `anywhere` is the half `break-word` cannot do: it lowers the tab's min-content
+   width, so one unbreakable word narrows rather than widening the page. The
+   padding is the scale's own step and the height is the tap floor, so the tab
+   draws 44 whatever line box its font hands it: the off-scale `--space-3 + 1px`
+   this replaces drew 44 with the webfont loaded and 41 without, which is under
+   the floor it claimed. The radius is left for the focus ring; the tab paints no
+   box. #527
+   why: guidelines/layout-and-density.md, the spacing scale */
+.ui-seg--underline button { position: relative; border-radius: var(--radius-sm); padding: var(--space-3); min-height: var(--tap-min, 44px); white-space: normal; overflow-wrap: anywhere; font-weight: var(--weight-medium); }
+/* The chosen tab is its label and one bar under it: no plate, no hairline, no
+   upright rail — those read as a list-row grip. `outline: 0` cancels the accent
+   outline the pill rule gives every chosen button, which is #544's second mark.
+   #527 r31. why: docs/specification.md#the-chosen-tab-in-an-underline-strip */
 .ui-seg--underline button.is-active,
-.ui-seg--underline button[aria-pressed="true"] { background: transparent; border-bottom-color: var(--accent); }
+.ui-seg--underline button[aria-pressed="true"] {
+  background: none;
+  color: var(--strong);
+  font-weight: var(--weight-semibold);
+  outline: 0;
+}
+/* Every tab reserves the bar and hides it, so the mark grows in place when the
+   choice moves rather than appearing — the structure and the timing
+   .ui-nav--tabs.is-underline already uses for the same 2px bar. ::before, not
+   ::after: below the phone step tap-zone.css sizes ::after to the 44px floor,
+   and a bar drawn there collapses that layer to 2px. Inset from the tab's
+   bottom edge, which is the line two wrapped rows share. */
+.ui-seg--underline button::before {
+  content: "";
+  position: absolute;
+  left: var(--space-3); right: var(--space-3); bottom: 3px;
+  height: 2px;
+  border-radius: 2px;
+  background: var(--accent);
+  opacity: 0;
+  transform: scaleX(0.4);
+  transition: opacity var(--dur-fast) var(--ease), transform var(--dur-fast) var(--ease);
+}
+.ui-seg--underline button.is-active::before,
+.ui-seg--underline button[aria-pressed="true"]::before { opacity: 1; transform: scaleX(1); }
+/* `outline: 0` above outranks the kit's :focus-visible rule — (0,3,0) against
+   (0,2,1) — so the chosen tab would focus with no indicator. Restated here. */
+.ui-seg--underline button.is-active:focus-visible,
+.ui-seg--underline button[aria-pressed="true"]:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
+/* The mode repaints an author colour, so the bar comes back as the labels' own
+   ink. `Highlight` is kept where it is named: one mark the mode cannot flatten. */
+@media (forced-colors: active) {
+  .ui-seg--underline button.is-active::before,
+  .ui-seg--underline button[aria-pressed="true"]::before { background: Highlight; }
+}
 .ui-seg button:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-seg button:disabled { /* muted-ink: state — unavailable choice */ color: var(--disabled-ink); cursor: not-allowed; }

package/src/styles/tap-zone.css

@@ -110,6 +110,17 @@
     --tap-clear-y: var(--tap-gap);
   }
 
+  /* The underline appearance keeps the gap it draws, at every width and under
+     both pointers, so a wrapped strip reads as one block. It can because the tab
+     draws the floor itself — segmented.css gives it `min-height: var(--tap-min)`
+     — leaving its layer inside the drawn box. The clearance is still declared,
+     and declared SMALL on purpose: the pill rule above hands every strip
+     --tap-gap, and this one has 4px of row to give, not 20. So a layer here can
+     never reach past the gap it was promised, whatever a tab draws. A pill draws
+     31 tall and does want the full 20. #527, measured in
+     stories/segmented-wrap.test.js. */
+  .ui-seg--underline { row-gap: var(--space-1, 4px) !important; --tap-clear-y: var(--space-1, 4px); }
+
   /* Tabs are wide enough across; down, the panel under them has the room. */
   .ui-tabs__list { --tap-clear-x: 2px; --tap-clear-y: var(--tap-gap); }