@jcsoftdev/ui 0.6.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +12 -2
  3. package/dist/atoms/avatar/avatar.d.ts +6 -1
  4. package/dist/atoms/avatar/avatar.js +3 -2
  5. package/dist/containers/kanban/kanban.js +2 -0
  6. package/dist/containers/list-detail/list-detail.js +2 -0
  7. package/dist/containers/responsive-list/responsive-list.d.ts +1 -1
  8. package/dist/containers/responsive-list/responsive-list.js +127 -116
  9. package/dist/forms/number-stepper/index.d.ts +1 -1
  10. package/dist/forms/number-stepper/number-stepper.d.ts +7 -0
  11. package/dist/forms/number-stepper/number-stepper.js +37 -6
  12. package/dist/i18n/strings.d.ts +12 -0
  13. package/dist/i18n/strings.js +6 -0
  14. package/dist/overlays/dialog/dialog.d.ts +1 -0
  15. package/dist/overlays/dialog/dialog.js +1 -1
  16. package/dist/overlays/toaster/toast-store.d.ts +2 -0
  17. package/dist/overlays/toaster/toast-store.js +6 -1
  18. package/dist/overlays/toaster/toaster.js +13 -0
  19. package/dist/shell/bottom-nav/bottom-nav.d.ts +5 -1
  20. package/dist/shell/bottom-nav/bottom-nav.js +52 -9
  21. package/dist/states/skeleton/skeleton.d.ts +16 -1
  22. package/dist/states/skeleton/skeleton.js +12 -4
  23. package/dist/utils/focus-chain.d.ts +11 -0
  24. package/dist/utils/focus-chain.js +39 -0
  25. package/dist/utils/focus-rescue.d.ts +13 -0
  26. package/dist/utils/focus-rescue.js +48 -0
  27. package/package.json +2 -2
  28. package/src/atoms/avatar/avatar.tsx +8 -2
  29. package/src/containers/kanban/kanban.tsx +2 -0
  30. package/src/containers/list-detail/list-detail.tsx +2 -0
  31. package/src/containers/responsive-list/responsive-list.tsx +8 -2
  32. package/src/forms/number-stepper/index.ts +1 -0
  33. package/src/forms/number-stepper/number-stepper.tsx +51 -6
  34. package/src/i18n/strings.ts +12 -0
  35. package/src/overlays/dialog/dialog.tsx +2 -1
  36. package/src/overlays/toaster/toast-store.ts +8 -0
  37. package/src/overlays/toaster/toaster.tsx +14 -0
  38. package/src/shell/bottom-nav/bottom-nav.tsx +78 -8
  39. package/src/states/skeleton/skeleton.tsx +32 -4
  40. package/src/utils/focus-chain.ts +53 -0
  41. package/src/utils/focus-rescue.ts +68 -0
@@ -97,7 +97,7 @@ function DialogHeader({ className, ...props }) {
97
97
  return /* @__PURE__ */ jsx(
98
98
  "div",
99
99
  {
100
- className: cn("flex items-center gap-2.5 border-b-divider py-3.5 pr-10 pl-4.5", className),
100
+ className: cn("flex flex-col gap-1 border-b-divider py-3.5 pr-10 pl-4.5", className),
101
101
  ...props
102
102
  }
103
103
  );
@@ -24,6 +24,8 @@ export interface ToastRecord extends Omit<ToastOptions, "id"> {
24
24
  state: "open" | "closed";
25
25
  /** Bumped on every update so timers restart. */
26
26
  revision: number;
27
+ /** Where focus was, nearest first, when the toast was published; focus returns there once the toast leaves. */
28
+ origin: readonly HTMLElement[];
27
29
  }
28
30
  export declare function subscribe(listener: () => void): () => void;
29
31
  export declare function getSnapshot(): readonly ToastRecord[];
@@ -1,3 +1,4 @@
1
+ import { focusChain } from "../../utils/focus-chain.js";
1
2
  const EMPTY = [];
2
3
  let toasts = EMPTY;
3
4
  let counter = 0;
@@ -18,6 +19,9 @@ function getSnapshot() {
18
19
  function getServerSnapshot() {
19
20
  return EMPTY;
20
21
  }
22
+ function currentFocusChain() {
23
+ return typeof document === "undefined" ? [] : focusChain(document.activeElement);
24
+ }
21
25
  function publish(message, tone, options = {}) {
22
26
  const id = options.id ?? `toast-${++counter}`;
23
27
  const existing = toasts.find((t) => t.id === id);
@@ -27,7 +31,8 @@ function publish(message, tone, options = {}) {
27
31
  message,
28
32
  tone,
29
33
  state: "open",
30
- revision: (existing?.revision ?? 0) + 1
34
+ revision: (existing?.revision ?? 0) + 1,
35
+ origin: existing?.origin ?? currentFocusChain()
31
36
  };
32
37
  commit(existing ? toasts.map((t) => t.id === id ? record : t) : [...toasts, record]);
33
38
  return id;
@@ -2,6 +2,7 @@
2
2
  import { jsx, jsxs } from "react/jsx-runtime";
3
3
  import {
4
4
  useEffect,
5
+ useLayoutEffect,
5
6
  useRef,
6
7
  useState,
7
8
  useSyncExternalStore
@@ -10,6 +11,7 @@ import { statusIcon } from "../../atoms/internal/status-icons.js";
10
11
  import { useUiStrings } from "../../i18n/ui-strings-provider.js";
11
12
  import { Portal } from "../../primitives/portal.js";
12
13
  import { cn } from "../../utils/cn.js";
14
+ import { restoreFocusFromChain } from "../../utils/focus-chain.js";
13
15
  import { usePrefersReducedMotion } from "../../utils/reduced-motion.js";
14
16
  import {
15
17
  dismiss,
@@ -148,9 +150,19 @@ function ToastItem({ record, duration, reducedMotion, classNames }) {
148
150
  const [entered, setEntered] = useState(false);
149
151
  const [dragX, setDragX] = useState(0);
150
152
  const drag = useRef(null);
153
+ const rootRef = useRef(null);
151
154
  const hidden = useDocumentHidden();
152
155
  const effectiveDuration = record.duration ?? duration;
153
156
  useDismissTimer(record, effectiveDuration, hovered || focused || hidden);
157
+ const originRef = useRef(record.origin);
158
+ originRef.current = record.origin;
159
+ useLayoutEffect(
160
+ () => () => {
161
+ const current = document.activeElement;
162
+ if (current && rootRef.current?.contains(current)) restoreFocusFromChain(originRef.current);
163
+ },
164
+ []
165
+ );
154
166
  useEffect(() => {
155
167
  const frame = requestAnimationFrame(() => setEntered(true));
156
168
  return () => cancelAnimationFrame(frame);
@@ -194,6 +206,7 @@ function ToastItem({ record, duration, reducedMotion, classNames }) {
194
206
  /* @__PURE__ */ jsxs(
195
207
  "div",
196
208
  {
209
+ ref: rootRef,
197
210
  role: isError ? "alert" : "status",
198
211
  "aria-live": isError ? "assertive" : "polite",
199
212
  "aria-atomic": "true",
@@ -17,6 +17,10 @@ export interface BottomNavProps {
17
17
  maxSlots?: number;
18
18
  /** Text of the "More" button and the drawer title. Defaults to the localized "More". */
19
19
  moreLabel?: string;
20
+ /** Accessible text of the total on "More"; defaults to the localized "{count} pending". */
21
+ moreBadgeLabel?: (count: number) => string;
22
+ /** `count` (default) shows numeric badges as a count chip on the phone bar; `dot` keeps the small dot. */
23
+ badgeStyle?: "count" | "dot";
20
24
  /** Pinned at the bottom of the "More" drawer, e.g. the account or a sign-out button. */
21
25
  moreFooter?: ReactNode;
22
26
  /** Link renderer; defaults to a plain anchor. */
@@ -31,4 +35,4 @@ export interface BottomNavProps {
31
35
  * inside `AppShell`: it sticks to the bottom of the viewport and hides itself once the shell is
32
36
  * 900 px or wider, where the sidebar takes over. Without an `AppShell` it is always visible.
33
37
  */
34
- export declare function BottomNav({ items, ariaLabel, maxSlots, moreLabel, moreFooter, renderLink, className, classNames, }: BottomNavProps): import("react").JSX.Element;
38
+ export declare function BottomNav({ items, ariaLabel, maxSlots, moreLabel, moreBadgeLabel, badgeStyle, moreFooter, renderLink, className, classNames, }: BottomNavProps): import("react").JSX.Element;
@@ -6,6 +6,29 @@ import { Menu } from "../../icons/index.js";
6
6
  import { Drawer, DrawerContent, DrawerTitle } from "../../overlays/drawer/index.js";
7
7
  import { cn } from "../../utils/cn.js";
8
8
  import { BOTTOM_NAV_MAX_SLOTS, splitBottomNavItems } from "./split.js";
9
+ const BADGE_CAP = 99;
10
+ function numericBadge(badge) {
11
+ if (typeof badge === "number") return Number.isFinite(badge) ? badge : void 0;
12
+ if (typeof badge === "string" && /^\s*\d+\s*$/.test(badge)) return Number(badge);
13
+ return void 0;
14
+ }
15
+ function formatCount(count) {
16
+ return count > BADGE_CAP ? `${BADGE_CAP}+` : String(count);
17
+ }
18
+ const dotClasses = "absolute -top-0.5 -right-1 size-2 rounded-pill";
19
+ const chipClasses = "absolute -top-1.5 -right-2.5 inline-flex h-4 min-w-4 items-center justify-center rounded-pill px-1 font-bold text-count text-surface leading-none";
20
+ function BadgeMark({
21
+ count,
22
+ danger,
23
+ asDot,
24
+ className
25
+ }) {
26
+ const tone = danger ? "bg-danger" : "bg-warning";
27
+ if (count === void 0 || asDot) {
28
+ return /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: cn(dotClasses, tone, className) });
29
+ }
30
+ return /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: cn(chipClasses, tone, className), children: formatCount(count) });
31
+ }
9
32
  const defaultRenderLink = ({ children, ...props }) => /* @__PURE__ */ jsx("a", { ...props, children });
10
33
  const slotClasses = "relative flex min-h-14 w-full flex-col items-center justify-center gap-0.5 px-1 text-ink-2 text-meta focus-visible:focus-ring aria-[current=page]:font-bold aria-[current=page]:text-accent-ink data-[active=true]:font-bold data-[active=true]:text-accent-ink [&_svg]:size-5 [&_svg]:shrink-0";
11
34
  function BottomNav({
@@ -13,6 +36,8 @@ function BottomNav({
13
36
  ariaLabel,
14
37
  maxSlots = BOTTOM_NAV_MAX_SLOTS,
15
38
  moreLabel,
39
+ moreBadgeLabel,
40
+ badgeStyle = "count",
16
41
  moreFooter,
17
42
  renderLink = defaultRenderLink,
18
43
  className,
@@ -23,6 +48,14 @@ function BottomNav({
23
48
  const { visible, overflow } = splitBottomNavItems(items, maxSlots);
24
49
  const more = moreLabel ?? strings.more;
25
50
  const moreActive = overflow.some((item) => item.active);
51
+ const badged = overflow.filter((item) => item.badge !== void 0);
52
+ const overflowCounts = badged.map((item) => numericBadge(item.badge));
53
+ const overflowTotal = overflowCounts.reduce(
54
+ (sum, count) => count === void 0 ? sum : (sum ?? 0) + count,
55
+ void 0
56
+ );
57
+ const overflowDanger = badged.some((item) => item.badgeTone === "danger");
58
+ const overflowBadgeText = overflowTotal === void 0 ? void 0 : (moreBadgeLabel ?? ((count) => strings.morePending.replace("{count}", String(count))))(overflowTotal);
26
59
  return /* @__PURE__ */ jsxs(Fragment, { children: [
27
60
  /* @__PURE__ */ jsx(
28
61
  "nav",
@@ -50,14 +83,12 @@ function BottomNav({
50
83
  item.icon,
51
84
  item.badge !== void 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
52
85
  /* @__PURE__ */ jsx(
53
- "span",
86
+ BadgeMark,
54
87
  {
55
- "aria-hidden": "true",
56
- className: cn(
57
- "absolute -top-0.5 -right-1 size-2 rounded-pill",
58
- item.badgeTone === "danger" ? "bg-danger" : "bg-warning",
59
- classNames?.badge
60
- )
88
+ count: numericBadge(item.badge),
89
+ danger: item.badgeTone === "danger",
90
+ asDot: badgeStyle === "dot",
91
+ className: classNames?.badge
61
92
  }
62
93
  ),
63
94
  /* @__PURE__ */ jsx("span", { className: "sr-only", children: item.badgeLabel ?? item.badge })
@@ -76,8 +107,20 @@ function BottomNav({
76
107
  onClick: () => setMoreOpen(true),
77
108
  className: cn(slotClasses, classNames?.moreButton),
78
109
  children: [
79
- /* @__PURE__ */ jsx(Menu, { "aria-hidden": "true" }),
80
- /* @__PURE__ */ jsx("span", { children: more })
110
+ /* @__PURE__ */ jsxs("span", { className: "relative", children: [
111
+ /* @__PURE__ */ jsx(Menu, { "aria-hidden": "true" }),
112
+ badged.length > 0 ? /* @__PURE__ */ jsx(
113
+ BadgeMark,
114
+ {
115
+ count: overflowTotal,
116
+ danger: overflowDanger,
117
+ asDot: badgeStyle === "dot",
118
+ className: classNames?.badge
119
+ }
120
+ ) : null
121
+ ] }),
122
+ /* @__PURE__ */ jsx("span", { children: more }),
123
+ badged.length > 0 && overflowBadgeText ? /* @__PURE__ */ jsx("span", { className: "sr-only", children: overflowBadgeText }) : null
81
124
  ]
82
125
  }
83
126
  ) }) : null
@@ -1,4 +1,13 @@
1
+ import { type ReactNode } from "react";
1
2
  export type SkeletonVariant = "lines" | "table" | "card" | "list" | "kpis" | "key-value" | "bar";
3
+ export interface SkeletonGroupProps {
4
+ /** Text announced once for the whole region. Defaults to the localized "Loading". */
5
+ label?: string;
6
+ className?: string;
7
+ children: ReactNode;
8
+ }
9
+ /** One status announcement for every `Skeleton` inside; they render silent. */
10
+ export declare function SkeletonGroup({ label, className, children }: SkeletonGroupProps): import("react").JSX.Element;
2
11
  export interface SkeletonProps {
3
12
  variant?: SkeletonVariant;
4
13
  /** Number of lines for the `lines` variant. */
@@ -9,10 +18,16 @@ export interface SkeletonProps {
9
18
  count?: number;
10
19
  /** Text announced to screen readers while loading. */
11
20
  label?: string;
21
+ /**
22
+ * Whether this skeleton is its own status region. Defaults to `true`, except inside a
23
+ * `SkeletonGroup`, which announces once. Set `false` on repeated skeletons so a screen reader
24
+ * does not say "Loading" for each; wrap them in a `SkeletonGroup` or a status of your own.
25
+ */
26
+ announce?: boolean;
12
27
  /**
13
28
  * Classes on the root. The `bar` variant is one block sized by them (`h-8 w-32`), 12px tall and
14
29
  * full width otherwise.
15
30
  */
16
31
  className?: string;
17
32
  }
18
- export declare function Skeleton({ variant, lines, rows, count, label, className, }: SkeletonProps): import("react").JSX.Element;
33
+ export declare function Skeleton({ variant, lines, rows, count, label, announce, className, }: SkeletonProps): import("react").JSX.Element;
@@ -1,8 +1,14 @@
1
1
  "use client";
2
2
  import { jsx, jsxs } from "react/jsx-runtime";
3
+ import { createContext, useContext } from "react";
3
4
  import { useUiStrings } from "../../i18n/index.js";
4
5
  import { cn } from "../../utils/cn.js";
5
6
  const PLACEHOLDER_IDS = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l"];
7
+ const SkeletonGroupContext = createContext(false);
8
+ function SkeletonGroup({ label, className, children }) {
9
+ const strings = useUiStrings();
10
+ return /* @__PURE__ */ jsx("div", { role: "status", "aria-busy": "true", "aria-label": label ?? strings.loading, className, children: /* @__PURE__ */ jsx(SkeletonGroupContext.Provider, { value: true, children }) });
11
+ }
6
12
  function Bar({ className }) {
7
13
  return /* @__PURE__ */ jsx("span", { "aria-hidden": "true", className: cn("block h-3 rounded-xs bg-surface-2", className) });
8
14
  }
@@ -15,15 +21,16 @@ function Skeleton({
15
21
  rows = 4,
16
22
  count = 4,
17
23
  label,
24
+ announce,
18
25
  className
19
26
  }) {
20
27
  const strings = useUiStrings();
28
+ const grouped = useContext(SkeletonGroupContext);
29
+ const silent = !(announce ?? !grouped);
21
30
  return /* @__PURE__ */ jsxs(
22
31
  "div",
23
32
  {
24
- role: "status",
25
- "aria-busy": "true",
26
- "aria-label": label ?? strings.loading,
33
+ ...silent ? { "aria-hidden": true } : { role: "status", "aria-busy": true, "aria-label": label ?? strings.loading },
27
34
  className: cn(
28
35
  "animate-pulse",
29
36
  variant === "bar" && "block h-3 w-full rounded-xs bg-surface-2",
@@ -76,5 +83,6 @@ function Skeleton({
76
83
  }
77
84
  const KEY_VALUE_WIDTHS = ["w-11/12", "w-3/4", "w-5/6", "w-2/3"];
78
85
  export {
79
- Skeleton
86
+ Skeleton,
87
+ SkeletonGroup
80
88
  };
@@ -0,0 +1,11 @@
1
+ export declare function isVisible(element: Element): boolean;
2
+ export declare function focusLosing(): boolean;
3
+ /** Focuses the element, or a control inside it; returns whether focus moved there. */
4
+ export declare function focusWithin(element: HTMLElement): boolean;
5
+ /** The element and its ancestors up to the body, nearest first. */
6
+ export declare function focusChain(element: Element | null): HTMLElement[];
7
+ /**
8
+ * Focuses the first element of a chain captured with `focusChain` that still lives in the
9
+ * document: the element itself, otherwise the nearest surviving interactive or list-like ancestor.
10
+ */
11
+ export declare function restoreFocusFromChain(chain: readonly HTMLElement[]): boolean;
@@ -0,0 +1,39 @@
1
+ const FOCUSABLE = 'button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
2
+ const CONTAINER_TAGS = /* @__PURE__ */ new Set(["UL", "OL", "TBODY", "TABLE", "MAIN", "SECTION", "ARTICLE"]);
3
+ function isVisible(element) {
4
+ return element.getClientRects().length > 0;
5
+ }
6
+ function focusLosing() {
7
+ const active = document.activeElement;
8
+ return active === null || active === document.body || active === document.documentElement;
9
+ }
10
+ function focusWithin(element) {
11
+ const target = element.hasAttribute("tabindex") ? element : element.querySelector(FOCUSABLE) ?? element;
12
+ if (!target.hasAttribute("tabindex") && !target.matches(FOCUSABLE)) {
13
+ target.setAttribute("tabindex", "-1");
14
+ }
15
+ target.focus({ preventScroll: false });
16
+ return document.activeElement === target;
17
+ }
18
+ function focusChain(element) {
19
+ const chain = [];
20
+ for (let node = element; node && node !== document.body; node = node.parentElement) {
21
+ if (node instanceof HTMLElement) chain.push(node);
22
+ }
23
+ return chain;
24
+ }
25
+ function restoreFocusFromChain(chain) {
26
+ for (const [index, element] of chain.entries()) {
27
+ if (!element.isConnected || !isVisible(element)) continue;
28
+ const usable = index === 0 || element.hasAttribute("tabindex") || element.matches(FOCUSABLE) || CONTAINER_TAGS.has(element.tagName) || element.getAttribute("role") === "listbox" || element.getAttribute("role") === "list";
29
+ if (usable && focusWithin(element)) return true;
30
+ }
31
+ return false;
32
+ }
33
+ export {
34
+ focusChain,
35
+ focusLosing,
36
+ focusWithin,
37
+ isVisible,
38
+ restoreFocusFromChain
39
+ };
@@ -0,0 +1,13 @@
1
+ import { type RefObject } from "react";
2
+ export interface FocusRescueOptions {
3
+ /** Selector of the items inside the root. */
4
+ item: string;
5
+ /** Selector of the nearest ancestor that groups sibling items; the next item is looked up inside it. */
6
+ group: string;
7
+ }
8
+ /**
9
+ * When the focused item leaves the DOM (approved, started, moved away) the browser drops focus on
10
+ * the body. This hands it to the item that took its place, the last one when it was the tail, or
11
+ * the group when nothing is left. Focus that moved on purpose is never touched.
12
+ */
13
+ export declare function useFocusRescue(rootRef: RefObject<HTMLElement | null>, { item, group }: FocusRescueOptions): void;
@@ -0,0 +1,48 @@
1
+ import { useEffect } from "react";
2
+ import { focusLosing, focusWithin, isVisible } from "./focus-chain.js";
3
+ function useFocusRescue(rootRef, { item, group }) {
4
+ useEffect(() => {
5
+ const root = rootRef.current;
6
+ if (!root) return;
7
+ let tracked = null;
8
+ const itemsOf = (scope) => Array.from(scope.querySelectorAll(item)).filter(
9
+ (candidate) => candidate.closest(group) === scope && isVisible(candidate)
10
+ );
11
+ const track = (element) => {
12
+ const found = element?.closest(item);
13
+ const scope = found?.closest(group);
14
+ if (!found || !scope) return;
15
+ tracked = { element: found, group: scope, index: itemsOf(scope).indexOf(found) };
16
+ };
17
+ const onFocusIn = (event) => track(event.target instanceof HTMLElement ? event.target : null);
18
+ const rescue = () => {
19
+ if (!tracked) return;
20
+ if (tracked.element.isConnected) {
21
+ track(tracked.element);
22
+ return;
23
+ }
24
+ const lost = tracked;
25
+ if (!focusLosing()) {
26
+ tracked = null;
27
+ return;
28
+ }
29
+ tracked = null;
30
+ const scope = lost.group.isConnected ? lost.group : null;
31
+ if (!scope) return;
32
+ const siblings = itemsOf(scope);
33
+ const next = siblings[Math.min(Math.max(lost.index, 0), siblings.length - 1)];
34
+ if (next) focusWithin(next);
35
+ else focusWithin(scope);
36
+ };
37
+ root.addEventListener("focusin", onFocusIn);
38
+ const observer = new MutationObserver(rescue);
39
+ observer.observe(root, { childList: true, subtree: true });
40
+ return () => {
41
+ root.removeEventListener("focusin", onFocusIn);
42
+ observer.disconnect();
43
+ };
44
+ }, [rootRef, item, group]);
45
+ }
46
+ export {
47
+ useFocusRescue
48
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jcsoftdev/ui",
3
- "version": "0.6.0",
3
+ "version": "0.7.1",
4
4
  "description": "Token-driven React component library: React 19, Tailwind v4.",
5
5
  "author": "jcsoftdev",
6
6
  "license": "MIT",
@@ -102,7 +102,7 @@
102
102
  "typescript": "^5.5.4",
103
103
  "vite": "7.3.6",
104
104
  "vitest": "4.1.11",
105
- "@jcsoftdev/ui-tokens": "^0.6.0"
105
+ "@jcsoftdev/ui-tokens": "^0.7.1"
106
106
  },
107
107
  "publishConfig": {
108
108
  "access": "public"
@@ -98,6 +98,11 @@ export interface AvatarProps extends Omit<ComponentPropsWithRef<"span">, "childr
98
98
  tone?: AvatarTone;
99
99
  /** Small status dot at the bottom-right corner. */
100
100
  status?: StatusDotTone;
101
+ /**
102
+ * Hides the avatar from assistive technology, for one beside a visible name that already says
103
+ * who it is. `aria-hidden` passed directly does the same.
104
+ */
105
+ decorative?: boolean;
101
106
  /** Accessible text for the status dot; defaults to the status name. */
102
107
  statusLabel?: string;
103
108
  /** Per-part classes merged with `cn`; consumer classes win. `className` still targets the root and is merged last. */
@@ -112,6 +117,7 @@ export function Avatar({
112
117
  tone = "neutral",
113
118
  status: statusTone,
114
119
  statusLabel,
120
+ decorative,
115
121
  className,
116
122
  classNames,
117
123
  style,
@@ -126,8 +132,8 @@ export function Avatar({
126
132
 
127
133
  const avatar = (
128
134
  <span
129
- role="img"
130
- aria-label={name}
135
+ {...(decorative || props["aria-hidden"] ? {} : { role: "img", "aria-label": name })}
136
+ {...(decorative ? { "aria-hidden": true } : {})}
131
137
  {...props}
132
138
  style={customToneStyle(tone, builtinTones, style)}
133
139
  className={cn(
@@ -16,6 +16,7 @@ import { Chip } from "../../atoms/chip/chip.js";
16
16
  import { GripVertical } from "../../icons/index.js";
17
17
  import type { ClassNames } from "../../utils/class-names.js";
18
18
  import { cn } from "../../utils/cn.js";
19
+ import { useFocusRescue } from "../../utils/focus-rescue.js";
19
20
  import {
20
21
  dropIndex,
21
22
  dropIndexGrid,
@@ -148,6 +149,7 @@ export function Kanban({
148
149
  const [status, setStatus] = useState("");
149
150
 
150
151
  const rootRef = useRef<HTMLDivElement>(null);
152
+ useFocusRescue(rootRef, { item: "[data-card-id]", group: "ul" });
151
153
  const focusId = useRef<string | null>(null);
152
154
  const columnsRef = useRef(columns);
153
155
  columnsRef.current = columns;
@@ -18,6 +18,7 @@ import { useUiStrings } from "../../i18n/index.js";
18
18
  import { ChevronLeft } from "../../icons/index.js";
19
19
  import { cn } from "../../utils/cn.js";
20
20
  import { composeHandlers } from "../../utils/compose.js";
21
+ import { useFocusRescue } from "../../utils/focus-rescue.js";
21
22
  import { useControllableState } from "../../utils/use-controllable-state.js";
22
23
 
23
24
  interface ListDetailContextValue {
@@ -135,6 +136,7 @@ export function ListDetail({
135
136
  );
136
137
  const rootRef = useRef<HTMLDivElement>(null);
137
138
  const previous = useRef<string | null>(value);
139
+ useFocusRescue(rootRef, { item: "[data-list-detail-item]", group: "ul" });
138
140
 
139
141
  useEffect(() => {
140
142
  const before = previous.current;
@@ -1,9 +1,10 @@
1
1
  "use client";
2
2
 
3
- import type { KeyboardEvent, MouseEvent, ReactNode } from "react";
3
+ import { type KeyboardEvent, type MouseEvent, type ReactNode, useRef } from "react";
4
4
  import { useUiStrings } from "../../i18n/index.js";
5
5
  import type { ClassNames } from "../../utils/class-names.js";
6
6
  import { cn } from "../../utils/cn.js";
7
+ import { useFocusRescue } from "../../utils/focus-rescue.js";
7
8
  import { focusRowByKey } from "../../utils/list-navigation.js";
8
9
  import {
9
10
  Table,
@@ -124,6 +125,8 @@ export function ResponsiveList<T>({
124
125
  classNames,
125
126
  }: ResponsiveListProps<T>) {
126
127
  const strings = useUiStrings();
128
+ const rootRef = useRef<HTMLDivElement>(null);
129
+ useFocusRescue(rootRef, { item: "[data-row-key]", group: "tbody, ul" });
127
130
  const primary = columns.find((column) => column.primary) ?? columns[0];
128
131
  const details = columns.filter((column) => column !== primary);
129
132
  const selectable = onSelect !== undefined;
@@ -177,7 +180,10 @@ export function ResponsiveList<T>({
177
180
  };
178
181
 
179
182
  return (
180
- <div className={cn("@container/responsive-list min-w-0", classNames?.root, className)}>
183
+ <div
184
+ ref={rootRef}
185
+ className={cn("@container/responsive-list min-w-0", classNames?.root, className)}
186
+ >
181
187
  {layout === "auto" ? (
182
188
  <div
183
189
  className={cn(
@@ -2,4 +2,5 @@ export {
2
2
  NumberStepper,
3
3
  type NumberStepperPart,
4
4
  type NumberStepperProps,
5
+ type NumberStepperSize,
5
6
  } from "./number-stepper.js";
@@ -4,10 +4,12 @@ import {
4
4
  type ChangeEvent,
5
5
  type ChangeEventHandler,
6
6
  type KeyboardEvent,
7
+ useEffect,
7
8
  useId,
8
9
  useRef,
9
10
  useState,
10
11
  } from "react";
12
+ import { useUiStrings } from "../../i18n/index.js";
11
13
  import { Minus, Plus } from "../../icons/index.js";
12
14
  import type { ClassNames } from "../../utils/class-names.js";
13
15
  import { cn } from "../../utils/cn.js";
@@ -16,7 +18,20 @@ import { canStep, parseNumber, stepText } from "./model.js";
16
18
 
17
19
  export type NumberStepperPart = "root" | "decrement" | "increment" | "input" | "unit";
18
20
 
21
+ export type NumberStepperSize = "sm" | "md";
22
+
23
+ const sizeClasses: Readonly<Record<NumberStepperSize, { root: string; button: string }>> = {
24
+ sm: { root: "h-control-sm", button: "w-7" },
25
+ md: { root: "h-input", button: "w-9" },
26
+ };
27
+
19
28
  interface NumberStepperBaseProps {
29
+ /** `sm` (30px) matches a small `Button` or `Input` for dense rows; `md` (default) is the regular field height. */
30
+ size?: NumberStepperSize;
31
+ /** Accessible name of the plus button. Defaults to the localized verb followed by the field label. */
32
+ incrementLabel?: string;
33
+ /** Accessible name of the minus button. Defaults to the localized verb followed by the field label. */
34
+ decrementLabel?: string;
20
35
  min?: number;
21
36
  max?: number;
22
37
  step?: number;
@@ -68,6 +83,9 @@ export type NumberStepperProps = NumberStepperNumberProps | NumberStepperStringP
68
83
  */
69
84
  export function NumberStepper(props: NumberStepperProps) {
70
85
  const {
86
+ size = "md",
87
+ incrementLabel,
88
+ decrementLabel,
71
89
  min = Number.NEGATIVE_INFINITY,
72
90
  max = Number.POSITIVE_INFINITY,
73
91
  step = 1,
@@ -85,9 +103,33 @@ export function NumberStepper(props: NumberStepperProps) {
85
103
  "aria-describedby": ariaDescribedBy,
86
104
  "aria-invalid": ariaInvalid,
87
105
  } = props;
106
+ const strings = useUiStrings();
88
107
  const autoId = useId();
89
108
  const id = idProp ?? autoId;
109
+ const decrementId = `${autoId}-decrement`;
110
+ const incrementId = `${autoId}-increment`;
111
+ const [fieldLabel, setFieldLabel] = useState("");
90
112
  const inputRef = useRef<HTMLInputElement | null>(null);
113
+
114
+ useEffect(() => {
115
+ if (ariaLabel || ariaLabelledBy) return;
116
+ const labels = Array.from(inputRef.current?.labels ?? []);
117
+ setFieldLabel(
118
+ labels
119
+ .map((label) => label.textContent?.trim() ?? "")
120
+ .filter(Boolean)
121
+ .join(" "),
122
+ );
123
+ });
124
+
125
+ const stepButtonName = (verb: string, custom: string | undefined, buttonId: string) => {
126
+ if (custom) return { "aria-label": custom };
127
+ if (ariaLabelledBy) {
128
+ return { "aria-label": verb, "aria-labelledby": `${buttonId} ${ariaLabelledBy}` };
129
+ }
130
+ const subject = ariaLabel ?? fieldLabel;
131
+ return { "aria-label": subject ? `${verb} ${subject}` : verb };
132
+ };
91
133
  const isString = props.mode === "string";
92
134
  const [innerNumber, setInnerNumber] = useState(isString ? 0 : (props.defaultValue ?? 0));
93
135
  const [innerText, setInnerText] = useState(isString ? (props.defaultValue ?? "") : "");
@@ -148,13 +190,14 @@ export function NumberStepper(props: NumberStepperProps) {
148
190
  };
149
191
 
150
192
  const button =
151
- "grid h-full w-9 shrink-0 place-items-center text-ink-2 outline-none hover:bg-surface-sunken hover:text-ink focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-40";
193
+ "grid h-full shrink-0 place-items-center text-ink-2 outline-none hover:bg-surface-sunken hover:text-ink focus-visible:focus-ring disabled:cursor-not-allowed disabled:opacity-40";
152
194
  const valid = !Number.isNaN(number);
153
195
 
154
196
  return (
155
197
  <div
156
198
  className={cn(
157
- "inline-flex h-input min-w-32 max-w-full items-stretch overflow-hidden rounded-input border-control bg-surface-control",
199
+ "inline-flex min-w-32 max-w-full items-stretch overflow-hidden rounded-input border-control bg-surface-control",
200
+ sizeClasses[size].root,
158
201
  disabled && "opacity-60",
159
202
  (invalid || ariaInvalid) && "border-danger",
160
203
  classNames?.root,
@@ -164,11 +207,12 @@ export function NumberStepper(props: NumberStepperProps) {
164
207
  <button
165
208
  type="button"
166
209
  tabIndex={-1}
167
- aria-label="Disminuir"
210
+ id={decrementId}
211
+ {...stepButtonName(strings.decrease, decrementLabel, decrementId)}
168
212
  aria-controls={id}
169
213
  disabled={disabled || !canStep(text, -1, { min, max })}
170
214
  onClick={() => move(-1)}
171
- className={cn(button, "pressable", classNames?.decrement)}
215
+ className={cn(button, sizeClasses[size].button, "pressable", classNames?.decrement)}
172
216
  >
173
217
  <Minus aria-hidden="true" className="size-3.5" />
174
218
  </button>
@@ -210,11 +254,12 @@ export function NumberStepper(props: NumberStepperProps) {
210
254
  <button
211
255
  type="button"
212
256
  tabIndex={-1}
213
- aria-label="Aumentar"
257
+ id={incrementId}
258
+ {...stepButtonName(strings.increase, incrementLabel, incrementId)}
214
259
  aria-controls={id}
215
260
  disabled={disabled || !canStep(text, 1, { min, max })}
216
261
  onClick={() => move(1)}
217
- className={cn(button, "pressable", classNames?.increment)}
262
+ className={cn(button, sizeClasses[size].button, "pressable", classNames?.increment)}
218
263
  >
219
264
  <Plus aria-hidden="true" className="size-3.5" />
220
265
  </button>