@astryxdesign/core 0.7.6-canary.32f9dc8 → 0.7.6-canary.340cc7c

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.
@@ -1 +1 @@
1
- {"version":3,"file":"Wheel.d.ts","sourceRoot":"","sources":["../../src/DateInput/Wheel.tsx"],"names":[],"mappings":"AA8MA,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACpC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAe,GAChB,EAAE,UAAU,+BAmOZ;yBAzOe,KAAK"}
1
+ {"version":3,"file":"Wheel.d.ts","sourceRoot":"","sources":["../../src/DateInput/Wheel.tsx"],"names":[],"mappings":"AA8MA,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACpC,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAe,GAChB,EAAE,UAAU,+BAgOZ;yBAtOe,KAAK"}
@@ -12,7 +12,7 @@
12
12
  * rubber-banding, and the settle animation are the platform's; all this adds
13
13
  * is `scroll-snap-align: center` on each option, half a viewport of padding at
14
14
  * each end so the first and last option can reach the middle, and a commit
15
- * when the scrolling stops and no finger or mouse drag still holds it.
15
+ * when the scrolling stops.
16
16
  *
17
17
  * The falloff (rows fading and tipping away from the centre) is a CSS
18
18
  * scroll-driven animation on a `view()` timeline — the browser interpolates it
@@ -99,15 +99,6 @@ export function Wheel({
99
99
  // `selectedIndex` only catches up when the wheel settles.
100
100
  const [activeIndex, setActiveIndex] = useState(selectedIndex);
101
101
 
102
- // A mouse cannot drag a scroll container, so without this the wheel ignores
103
- // the one gesture its shape invites. Touch is untouched — it pans natively,
104
- // with momentum this could not match. See usePointerDragScroll. The drag it
105
- // holds is not rest either: the settle below waits for its release, as it
106
- // waits for a finger's (useScrollSettle).
107
- const {
108
- isDraggingRef
109
- } = usePointerDragScroll(scrollerRef, isActive);
110
-
111
102
  // Row height in px, read from layout rather than assumed, so a theme that
112
103
  // retunes --date-input-touch-wheel-item-size still lands on the right row.
113
104
  const itemBlockSize = useCallback(() => {
@@ -147,7 +138,7 @@ export function Wheel({
147
138
  if (option.value !== value) {
148
139
  onChange(option.value);
149
140
  }
150
- }, isActive, isDraggingRef);
141
+ }, isActive);
151
142
 
152
143
  // Park the committed row under the band whenever the wheel is shown, or the
153
144
  // value is changed from outside (the calendar scrolled to another month).
@@ -219,6 +210,11 @@ export function Wheel({
219
210
  useOwnScrollGesture(scrollerRef, 'all', {
220
211
  isEnabled: isActive
221
212
  });
213
+
214
+ // A mouse cannot drag a scroll container, so without this the wheel ignores
215
+ // the one gesture its shape invites. Touch is untouched — it pans natively,
216
+ // with momentum this could not match. See usePointerDragScroll.
217
+ usePointerDragScroll(scrollerRef, isActive);
222
218
  const moveBy = useCallback(delta => {
223
219
  const next = Math.min(options.length - 1, Math.max(0, activeIndex + delta));
224
220
  const option = options[next];
@@ -3,15 +3,6 @@
3
3
  * press of the button itself, and a wheel row is a click target.
4
4
  */
5
5
  export declare const DRAG_SLOP = 4;
6
- /** What {@link usePointerDragScroll} reports back about the drag. */
7
- export type PointerDragScrollState = {
8
- /**
9
- * True while a mouse drag holds the container: from the press that moved
10
- * past {@link DRAG_SLOP} until its release. Pass it to `useScrollSettle`,
11
- * which treats a held drag as it treats a finger still down.
12
- */
13
- isDraggingRef: React.RefObject<boolean>;
14
- };
15
6
  /**
16
7
  * Let a mouse drag `ref`'s contents, on a container that already scrolls and
17
8
  * snaps for touch.
@@ -20,5 +11,5 @@ export type PointerDragScrollState = {
20
11
  * @param isEnabled - skip while the wheel is hidden; a hidden panel keeps its
21
12
  * layout box, so its listeners would otherwise still be live
22
13
  */
23
- export declare function usePointerDragScroll(ref: React.RefObject<HTMLElement | null>, isEnabled?: boolean): PointerDragScrollState;
14
+ export declare function usePointerDragScroll(ref: React.RefObject<HTMLElement | null>, isEnabled?: boolean): void;
24
15
  //# sourceMappingURL=usePointerDragScroll.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"usePointerDragScroll.d.ts","sourceRoot":"","sources":["../../src/DateInput/usePointerDragScroll.ts"],"names":[],"mappings":"AAwDA;;;GAGG;AACH,eAAO,MAAM,SAAS,IAAI,CAAC;AAK3B,qEAAqE;AACrE,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;OAIG;IACH,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;CACzC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,SAAS,GAAE,OAAc,GACxB,sBAAsB,CAmJxB"}
1
+ {"version":3,"file":"usePointerDragScroll.d.ts","sourceRoot":"","sources":["../../src/DateInput/usePointerDragScroll.ts"],"names":[],"mappings":"AA+CA;;;GAGG;AACH,eAAO,MAAM,SAAS,IAAI,CAAC;AAK3B;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,SAAS,GAAE,OAAc,GACxB,IAAI,CA8IN"}
@@ -5,8 +5,7 @@
5
5
  /**
6
6
  * @file usePointerDragScroll.ts
7
7
  * @input A scroll container ref
8
- * @output Lets a mouse drag the container's contents the way a finger does,
9
- * and reports while a drag holds it (`isDraggingRef`)
8
+ * @output Lets a mouse drag the container's contents the way a finger does
10
9
  * @position Internal behavior hook; consumed by Wheel.tsx
11
10
  *
12
11
  * ## Why this exists
@@ -39,19 +38,11 @@
39
38
  * then jumps a whole one. The drag therefore suspends snapping, and restores
40
39
  * it once the release has settled somewhere legal.
41
40
  *
42
- * ## A held drag is not rest
43
- *
44
- * Every `scrollTop` the drag assigns is a programmatic scroll, and Chromium
45
- * ends each one with a `scrollend` — 14 moves, 14 of them. A settle listening
46
- * for `scrollend` alone would commit the row under the band at every step,
47
- * with the button still down. `isDraggingRef` tells `useScrollSettle` the
48
- * drag is still held, the way a touch that has not ended does.
49
- *
50
41
  * SYNC: When modified, update:
51
42
  * - /packages/core/src/DateInput/Wheel.tsx
52
43
  * - /packages/core/src/DateInput/DateInputTouch.test.tsx
53
44
  */
54
- import { useEffect, useRef } from 'react';
45
+ import { useEffect } from 'react';
55
46
 
56
47
  /**
57
48
  * Movement below this stays a click. A mouse shifts a pixel or two under the
@@ -62,8 +53,6 @@ export const DRAG_SLOP = 4;
62
53
  /** How long to wait for a release's settle before restoring snapping. */
63
54
  const SETTLE_FALLBACK_MS = 260;
64
55
 
65
- /** What {@link usePointerDragScroll} reports back about the drag. */
66
-
67
56
  /**
68
57
  * Let a mouse drag `ref`'s contents, on a container that already scrolls and
69
58
  * snaps for touch.
@@ -73,7 +62,6 @@ const SETTLE_FALLBACK_MS = 260;
73
62
  * layout box, so its listeners would otherwise still be live
74
63
  */
75
64
  export function usePointerDragScroll(ref, isEnabled = true) {
76
- const isDraggingRef = useRef(false);
77
65
  useEffect(() => {
78
66
  const element = ref.current;
79
67
  if (element == null || !isEnabled) {
@@ -82,9 +70,9 @@ export function usePointerDragScroll(ref, isEnabled = true) {
82
70
  let pointerId = null;
83
71
  let originY = 0;
84
72
  let originScrollTop = 0;
85
- isDraggingRef.current = false;
73
+ let isDragging = false;
86
74
  // Survives from the drag's end to the click it produces, which is the
87
- // whole reason it is not just `isDraggingRef`.
75
+ // whole reason it is not just `isDragging`.
88
76
  let wasDragged = false;
89
77
  let restoreTimer;
90
78
  const restoreSnap = () => {
@@ -124,7 +112,7 @@ export function usePointerDragScroll(ref, isEnabled = true) {
124
112
  pointerId = event.pointerId;
125
113
  originY = event.clientY;
126
114
  originScrollTop = element.scrollTop;
127
- isDraggingRef.current = false;
115
+ isDragging = false;
128
116
  // Not captured yet: a press that never moves has to stay a click on the
129
117
  // row under it, and capturing here would retarget that click.
130
118
  };
@@ -133,11 +121,11 @@ export function usePointerDragScroll(ref, isEnabled = true) {
133
121
  return;
134
122
  }
135
123
  const delta = event.clientY - originY;
136
- if (!isDraggingRef.current) {
124
+ if (!isDragging) {
137
125
  if (Math.abs(delta) < DRAG_SLOP) {
138
126
  return;
139
127
  }
140
- isDraggingRef.current = true;
128
+ isDragging = true;
141
129
  element.setPointerCapture(event.pointerId);
142
130
  suspendSnap();
143
131
  // Dragging across rows would otherwise select their text, leaving the
@@ -153,10 +141,10 @@ export function usePointerDragScroll(ref, isEnabled = true) {
153
141
  return;
154
142
  }
155
143
  pointerId = null;
156
- if (!isDraggingRef.current) {
144
+ if (!isDragging) {
157
145
  return;
158
146
  }
159
- isDraggingRef.current = false;
147
+ isDragging = false;
160
148
  wasDragged = true;
161
149
  element.style.removeProperty('user-select');
162
150
  if (element.hasPointerCapture(event.pointerId)) {
@@ -212,13 +200,9 @@ export function usePointerDragScroll(ref, isEnabled = true) {
212
200
  element.removeEventListener('click', onClickCapture, {
213
201
  capture: true
214
202
  });
215
- isDraggingRef.current = false;
216
203
  restoreSnap();
217
204
  };
218
205
  }, [ref, isEnabled]);
219
- return {
220
- isDraggingRef
221
- };
222
206
  }
223
207
 
224
208
  /**
@@ -21,8 +21,6 @@ export type ScrollSettleState = {
21
21
  * @param ref - the scroll container
22
22
  * @param onSettle - called with the settled element; may change every render
23
23
  * @param isEnabled - skip attaching while false (e.g. a hidden panel)
24
- * @param isHeldRef - true while a mouse drag holds the scroller
25
- * (usePointerDragScroll's `isDraggingRef`): not rest, however quiet
26
24
  */
27
- export declare function useScrollSettle(ref: React.RefObject<HTMLElement | null>, onSettle: (element: HTMLElement) => void, isEnabled?: boolean, isHeldRef?: React.RefObject<boolean>): ScrollSettleState;
25
+ export declare function useScrollSettle(ref: React.RefObject<HTMLElement | null>, onSettle: (element: HTMLElement) => void, isEnabled?: boolean): ScrollSettleState;
28
26
  //# sourceMappingURL=useScrollSettle.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useScrollSettle.d.ts","sourceRoot":"","sources":["../../src/DateInput/useScrollSettle.ts"],"names":[],"mappings":"AA0DA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;OAKG;IACH,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,EACxC,SAAS,GAAE,OAAc,EACzB,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,GACnC,iBAAiB,CAuGnB"}
1
+ {"version":3,"file":"useScrollSettle.d.ts","sourceRoot":"","sources":["../../src/DateInput/useScrollSettle.ts"],"names":[],"mappings":"AAsDA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;;OAKG;IACH,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,EACxC,SAAS,GAAE,OAAc,GACxB,iBAAiB,CA+EnB"}
@@ -4,8 +4,7 @@
4
4
 
5
5
  /**
6
6
  * @file useScrollSettle.ts
7
- * @input A scroll container ref, a settle callback, and optionally whether a
8
- * mouse drag holds it (usePointerDragScroll's `isDraggingRef`)
7
+ * @input A scroll container ref and a settle callback
9
8
  * @output Calls back once, after scrolling (including momentum) stops
10
9
  * @position Internal behavior hook; consumed by Wheel.tsx and MonthScroller.tsx
11
10
  *
@@ -28,10 +27,7 @@
28
27
  * moment without lifting and the scroll events stop, so the timer fires
29
28
  * and the value commits to whatever is under the band. Chrome hides this
30
29
  * because it has `scrollend`, which does not fire until the touch is
31
- * released. A mouse drag (usePointerDragScroll) is held the same way, and
32
- * there Chrome gives no cover at all: each `scrollTop` the drag assigns
33
- * ends in its own `scrollend`, so the settle waits for the drag's
34
- * `pointerup` as it waits for `touchend`.
30
+ * released.
35
31
  *
36
32
  * 2. **Momentum is not rest either.** iOS momentum runs on the UI thread and
37
33
  * keeps going for a second or more after the finger is gone, and its scroll
@@ -45,7 +41,7 @@
45
41
  * underneath, and the fresh scroll events start the next premature settle —
46
42
  * each one landing a row further along, which is why the month climbed.
47
43
  *
48
- * So: the settle waits for the touch or the mouse drag to end, and then for a quiet period
44
+ * So: the settle waits for the touch to end, and then for a quiet period
49
45
  * measured from the LAST scroll event, which is what makes it outlast
50
46
  * momentum however long it runs. {@link useScrollSettle} also reports whether
51
47
  * the scroller is at rest, so a caller can refuse to reposition one that is
@@ -71,10 +67,8 @@ export const SCROLL_QUIET_MS = 220;
71
67
  * @param ref - the scroll container
72
68
  * @param onSettle - called with the settled element; may change every render
73
69
  * @param isEnabled - skip attaching while false (e.g. a hidden panel)
74
- * @param isHeldRef - true while a mouse drag holds the scroller
75
- * (usePointerDragScroll's `isDraggingRef`): not rest, however quiet
76
70
  */
77
- export function useScrollSettle(ref, onSettle, isEnabled = true, isHeldRef) {
71
+ export function useScrollSettle(ref, onSettle, isEnabled = true) {
78
72
  // The callback closes over render-fresh values (the option list, the current
79
73
  // value); keeping it in a ref means the listeners attach once instead of
80
74
  // re-attaching mid-scroll, which would drop an in-flight settle.
@@ -90,17 +84,10 @@ export function useScrollSettle(ref, onSettle, isEnabled = true, isHeldRef) {
90
84
  let timer;
91
85
  let hasSettled = false;
92
86
  let isTouching = false;
93
- // Whether a mouse drag held this gesture, so its release re-arms the
94
- // settle; a plain click does not.
95
- let wasHeld = false;
96
87
  const settle = () => {
97
- // A finger still on the glass, or a mouse button still holding a drag,
98
- // is not rest, however quiet the scroller has gone. The release re-arms
99
- // this.
100
- if (isHeldRef?.current) {
101
- wasHeld = true;
102
- }
103
- if (hasSettled || isTouching || isHeldRef?.current) {
88
+ // A finger still on the glass is not rest, however quiet the scroller
89
+ // has gone. The release re-arms this.
90
+ if (hasSettled || isTouching) {
104
91
  return;
105
92
  }
106
93
  hasSettled = true;
@@ -119,9 +106,6 @@ export function useScrollSettle(ref, onSettle, isEnabled = true, isHeldRef) {
119
106
  // the last of it however long it runs.
120
107
  hasSettled = false;
121
108
  isAtRestRef.current = false;
122
- if (isHeldRef?.current) {
123
- wasHeld = true;
124
- }
125
109
  arm();
126
110
  };
127
111
  const onTouchStart = () => {
@@ -137,15 +121,6 @@ export function useScrollSettle(ref, onSettle, isEnabled = true, isHeldRef) {
137
121
  // produces no further scroll events at all.
138
122
  arm();
139
123
  };
140
- const onPointerEnd = () => {
141
- // The drag's release: its glide to the nearest row re-arms this on its
142
- // own, and the timer covers a release already on a row, which scrolls
143
- // no further.
144
- if (wasHeld) {
145
- wasHeld = false;
146
- arm();
147
- }
148
- };
149
124
  element.addEventListener('scroll', onScroll, {
150
125
  passive: true
151
126
  });
@@ -159,8 +134,6 @@ export function useScrollSettle(ref, onSettle, isEnabled = true, isHeldRef) {
159
134
  element.addEventListener('touchcancel', onTouchEnd, {
160
135
  passive: true
161
136
  });
162
- element.addEventListener('pointerup', onPointerEnd);
163
- element.addEventListener('pointercancel', onPointerEnd);
164
137
  return () => {
165
138
  clearTimeout(timer);
166
139
  element.removeEventListener('scroll', onScroll);
@@ -168,10 +141,8 @@ export function useScrollSettle(ref, onSettle, isEnabled = true, isHeldRef) {
168
141
  element.removeEventListener('touchstart', onTouchStart);
169
142
  element.removeEventListener('touchend', onTouchEnd);
170
143
  element.removeEventListener('touchcancel', onTouchEnd);
171
- element.removeEventListener('pointerup', onPointerEnd);
172
- element.removeEventListener('pointercancel', onPointerEnd);
173
144
  };
174
- }, [ref, isEnabled, isHeldRef]);
145
+ }, [ref, isEnabled]);
175
146
  return {
176
147
  isAtRestRef
177
148
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astryxdesign/core",
3
- "version": "0.7.6-canary.32f9dc8",
3
+ "version": "0.7.6-canary.340cc7c",
4
4
  "displayName": "Astryx Core",
5
5
  "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
6
6
  "author": "Meta Open Source",
@@ -847,9 +847,9 @@
847
847
  "react-dom": ">=19.0.0"
848
848
  },
849
849
  "devDependencies": {
850
- "@astryxdesign/a11y-spec": "0.7.6-canary.32f9dc8",
851
- "@astryxdesign/cli": "0.7.6-canary.32f9dc8",
852
- "@astryxdesign/interaction-harness": "0.7.6-canary.32f9dc8",
850
+ "@astryxdesign/a11y-spec": "0.7.6-canary.340cc7c",
851
+ "@astryxdesign/cli": "0.7.6-canary.340cc7c",
852
+ "@astryxdesign/interaction-harness": "0.7.6-canary.340cc7c",
853
853
  "@babel/cli": "^7.29.7",
854
854
  "@babel/core": "^7.29.7",
855
855
  "@babel/preset-react": "^7.29.7",
@@ -2325,50 +2325,6 @@ describe('DateInput — a mouse can drag a wheel', () => {
2325
2325
  });
2326
2326
  });
2327
2327
 
2328
- /**
2329
- * Every `scrollTop` the drag assigns ends in its own `scrollend` in
2330
- * Chromium, and the hand can rest with the button still down. Neither is
2331
- * rest: the month the wheel lands on commits at the release, as it does
2332
- * when a finger lifts.
2333
- */
2334
- it('commits nothing while a mouse drag holds the wheel, and commits at the release', () => {
2335
- vi.useFakeTimers();
2336
- try {
2337
- // A year of months, so May is reachable (the default range ends in April).
2338
- renderAndOpen(
2339
- <Controlled initial="2026-03-21" min="2026-01-01" max="2026-12-31" />,
2340
- );
2341
- fireEvent.click(title());
2342
- withWheelLayout(() => {
2343
- const el = wheel();
2344
- trackable(el);
2345
- // March, the committed month, sits under the band.
2346
- el.scrollTop = 2 * 28;
2347
- const selected = () =>
2348
- el.querySelector('[aria-selected="true"]')?.textContent;
2349
- el.dispatchEvent(pointer('pointerdown', {y: 200}));
2350
- // Two rows on: May is under the band.
2351
- el.dispatchEvent(pointer('pointermove', {y: 144}));
2352
- fireEvent.scroll(el);
2353
- el.dispatchEvent(new Event('scrollend'));
2354
- act(() => {
2355
- vi.advanceTimersByTime(SCROLL_QUIET_MS * 2);
2356
- });
2357
- expect(selected()).toBe('March');
2358
- expect(title()).toHaveTextContent('March 2026');
2359
-
2360
- el.dispatchEvent(pointer('pointerup', {y: 144}));
2361
- act(() => {
2362
- vi.advanceTimersByTime(SCROLL_QUIET_MS * 2);
2363
- });
2364
- expect(selected()).toBe('May');
2365
- expect(title()).toHaveTextContent('May 2026');
2366
- });
2367
- } finally {
2368
- vi.useRealTimers();
2369
- }
2370
- });
2371
-
2372
2328
  /**
2373
2329
  * BottomSheet starts its own drag-to-dismiss from a `pointerdown` on its
2374
2330
  * body and CAPTURES the pointer for it, which retargets every later pointer
@@ -12,7 +12,7 @@
12
12
  * rubber-banding, and the settle animation are the platform's; all this adds
13
13
  * is `scroll-snap-align: center` on each option, half a viewport of padding at
14
14
  * each end so the first and last option can reach the middle, and a commit
15
- * when the scrolling stops and no finger or mouse drag still holds it.
15
+ * when the scrolling stops.
16
16
  *
17
17
  * The falloff (rows fading and tipping away from the centre) is a CSS
18
18
  * scroll-driven animation on a `view()` timeline — the browser interpolates it
@@ -259,13 +259,6 @@ export function Wheel({
259
259
  // `selectedIndex` only catches up when the wheel settles.
260
260
  const [activeIndex, setActiveIndex] = useState(selectedIndex);
261
261
 
262
- // A mouse cannot drag a scroll container, so without this the wheel ignores
263
- // the one gesture its shape invites. Touch is untouched — it pans natively,
264
- // with momentum this could not match. See usePointerDragScroll. The drag it
265
- // holds is not rest either: the settle below waits for its release, as it
266
- // waits for a finger's (useScrollSettle).
267
- const {isDraggingRef} = usePointerDragScroll(scrollerRef, isActive);
268
-
269
262
  // Row height in px, read from layout rather than assumed, so a theme that
270
263
  // retunes --date-input-touch-wheel-item-size still lands on the right row.
271
264
  const itemBlockSize = useCallback((): number => {
@@ -313,7 +306,6 @@ export function Wheel({
313
306
  }
314
307
  },
315
308
  isActive,
316
- isDraggingRef,
317
309
  );
318
310
 
319
311
  // Park the committed row under the band whenever the wheel is shown, or the
@@ -383,6 +375,11 @@ export function Wheel({
383
375
  // there is no way to share — it takes every touch that lands on it.
384
376
  useOwnScrollGesture(scrollerRef, 'all', {isEnabled: isActive});
385
377
 
378
+ // A mouse cannot drag a scroll container, so without this the wheel ignores
379
+ // the one gesture its shape invites. Touch is untouched — it pans natively,
380
+ // with momentum this could not match. See usePointerDragScroll.
381
+ usePointerDragScroll(scrollerRef, isActive);
382
+
386
383
  const moveBy = useCallback(
387
384
  (delta: number) => {
388
385
  const next = Math.min(
@@ -5,8 +5,7 @@
5
5
  /**
6
6
  * @file usePointerDragScroll.ts
7
7
  * @input A scroll container ref
8
- * @output Lets a mouse drag the container's contents the way a finger does,
9
- * and reports while a drag holds it (`isDraggingRef`)
8
+ * @output Lets a mouse drag the container's contents the way a finger does
10
9
  * @position Internal behavior hook; consumed by Wheel.tsx
11
10
  *
12
11
  * ## Why this exists
@@ -39,20 +38,12 @@
39
38
  * then jumps a whole one. The drag therefore suspends snapping, and restores
40
39
  * it once the release has settled somewhere legal.
41
40
  *
42
- * ## A held drag is not rest
43
- *
44
- * Every `scrollTop` the drag assigns is a programmatic scroll, and Chromium
45
- * ends each one with a `scrollend` — 14 moves, 14 of them. A settle listening
46
- * for `scrollend` alone would commit the row under the band at every step,
47
- * with the button still down. `isDraggingRef` tells `useScrollSettle` the
48
- * drag is still held, the way a touch that has not ended does.
49
- *
50
41
  * SYNC: When modified, update:
51
42
  * - /packages/core/src/DateInput/Wheel.tsx
52
43
  * - /packages/core/src/DateInput/DateInputTouch.test.tsx
53
44
  */
54
45
 
55
- import {useEffect, useRef} from 'react';
46
+ import {useEffect} from 'react';
56
47
 
57
48
  /**
58
49
  * Movement below this stays a click. A mouse shifts a pixel or two under the
@@ -63,16 +54,6 @@ export const DRAG_SLOP = 4;
63
54
  /** How long to wait for a release's settle before restoring snapping. */
64
55
  const SETTLE_FALLBACK_MS = 260;
65
56
 
66
- /** What {@link usePointerDragScroll} reports back about the drag. */
67
- export type PointerDragScrollState = {
68
- /**
69
- * True while a mouse drag holds the container: from the press that moved
70
- * past {@link DRAG_SLOP} until its release. Pass it to `useScrollSettle`,
71
- * which treats a held drag as it treats a finger still down.
72
- */
73
- isDraggingRef: React.RefObject<boolean>;
74
- };
75
-
76
57
  /**
77
58
  * Let a mouse drag `ref`'s contents, on a container that already scrolls and
78
59
  * snaps for touch.
@@ -84,9 +65,7 @@ export type PointerDragScrollState = {
84
65
  export function usePointerDragScroll(
85
66
  ref: React.RefObject<HTMLElement | null>,
86
67
  isEnabled: boolean = true,
87
- ): PointerDragScrollState {
88
- const isDraggingRef = useRef(false);
89
-
68
+ ): void {
90
69
  useEffect(() => {
91
70
  const element = ref.current;
92
71
  if (element == null || !isEnabled) {
@@ -96,9 +75,9 @@ export function usePointerDragScroll(
96
75
  let pointerId: number | null = null;
97
76
  let originY = 0;
98
77
  let originScrollTop = 0;
99
- isDraggingRef.current = false;
78
+ let isDragging = false;
100
79
  // Survives from the drag's end to the click it produces, which is the
101
- // whole reason it is not just `isDraggingRef`.
80
+ // whole reason it is not just `isDragging`.
102
81
  let wasDragged = false;
103
82
  let restoreTimer: number | undefined;
104
83
 
@@ -141,7 +120,7 @@ export function usePointerDragScroll(
141
120
  pointerId = event.pointerId;
142
121
  originY = event.clientY;
143
122
  originScrollTop = element.scrollTop;
144
- isDraggingRef.current = false;
123
+ isDragging = false;
145
124
  // Not captured yet: a press that never moves has to stay a click on the
146
125
  // row under it, and capturing here would retarget that click.
147
126
  };
@@ -151,11 +130,11 @@ export function usePointerDragScroll(
151
130
  return;
152
131
  }
153
132
  const delta = event.clientY - originY;
154
- if (!isDraggingRef.current) {
133
+ if (!isDragging) {
155
134
  if (Math.abs(delta) < DRAG_SLOP) {
156
135
  return;
157
136
  }
158
- isDraggingRef.current = true;
137
+ isDragging = true;
159
138
  element.setPointerCapture(event.pointerId);
160
139
  suspendSnap();
161
140
  // Dragging across rows would otherwise select their text, leaving the
@@ -172,10 +151,10 @@ export function usePointerDragScroll(
172
151
  return;
173
152
  }
174
153
  pointerId = null;
175
- if (!isDraggingRef.current) {
154
+ if (!isDragging) {
176
155
  return;
177
156
  }
178
- isDraggingRef.current = false;
157
+ isDragging = false;
179
158
  wasDragged = true;
180
159
  element.style.removeProperty('user-select');
181
160
  if (element.hasPointerCapture(event.pointerId)) {
@@ -225,12 +204,9 @@ export function usePointerDragScroll(
225
204
  element.removeEventListener('pointerup', onPointerEnd);
226
205
  element.removeEventListener('pointercancel', onPointerEnd);
227
206
  element.removeEventListener('click', onClickCapture, {capture: true});
228
- isDraggingRef.current = false;
229
207
  restoreSnap();
230
208
  };
231
209
  }, [ref, isEnabled]);
232
-
233
- return {isDraggingRef};
234
210
  }
235
211
 
236
212
  /**
@@ -4,8 +4,7 @@
4
4
 
5
5
  /**
6
6
  * @file useScrollSettle.ts
7
- * @input A scroll container ref, a settle callback, and optionally whether a
8
- * mouse drag holds it (usePointerDragScroll's `isDraggingRef`)
7
+ * @input A scroll container ref and a settle callback
9
8
  * @output Calls back once, after scrolling (including momentum) stops
10
9
  * @position Internal behavior hook; consumed by Wheel.tsx and MonthScroller.tsx
11
10
  *
@@ -28,10 +27,7 @@
28
27
  * moment without lifting and the scroll events stop, so the timer fires
29
28
  * and the value commits to whatever is under the band. Chrome hides this
30
29
  * because it has `scrollend`, which does not fire until the touch is
31
- * released. A mouse drag (usePointerDragScroll) is held the same way, and
32
- * there Chrome gives no cover at all: each `scrollTop` the drag assigns
33
- * ends in its own `scrollend`, so the settle waits for the drag's
34
- * `pointerup` as it waits for `touchend`.
30
+ * released.
35
31
  *
36
32
  * 2. **Momentum is not rest either.** iOS momentum runs on the UI thread and
37
33
  * keeps going for a second or more after the finger is gone, and its scroll
@@ -45,7 +41,7 @@
45
41
  * underneath, and the fresh scroll events start the next premature settle —
46
42
  * each one landing a row further along, which is why the month climbed.
47
43
  *
48
- * So: the settle waits for the touch or the mouse drag to end, and then for a quiet period
44
+ * So: the settle waits for the touch to end, and then for a quiet period
49
45
  * measured from the LAST scroll event, which is what makes it outlast
50
46
  * momentum however long it runs. {@link useScrollSettle} also reports whether
51
47
  * the scroller is at rest, so a caller can refuse to reposition one that is
@@ -81,14 +77,11 @@ export type ScrollSettleState = {
81
77
  * @param ref - the scroll container
82
78
  * @param onSettle - called with the settled element; may change every render
83
79
  * @param isEnabled - skip attaching while false (e.g. a hidden panel)
84
- * @param isHeldRef - true while a mouse drag holds the scroller
85
- * (usePointerDragScroll's `isDraggingRef`): not rest, however quiet
86
80
  */
87
81
  export function useScrollSettle(
88
82
  ref: React.RefObject<HTMLElement | null>,
89
83
  onSettle: (element: HTMLElement) => void,
90
84
  isEnabled: boolean = true,
91
- isHeldRef?: React.RefObject<boolean>,
92
85
  ): ScrollSettleState {
93
86
  // The callback closes over render-fresh values (the option list, the current
94
87
  // value); keeping it in a ref means the listeners attach once instead of
@@ -108,18 +101,11 @@ export function useScrollSettle(
108
101
  let timer: ReturnType<typeof setTimeout> | undefined;
109
102
  let hasSettled = false;
110
103
  let isTouching = false;
111
- // Whether a mouse drag held this gesture, so its release re-arms the
112
- // settle; a plain click does not.
113
- let wasHeld = false;
114
104
 
115
105
  const settle = () => {
116
- // A finger still on the glass, or a mouse button still holding a drag,
117
- // is not rest, however quiet the scroller has gone. The release re-arms
118
- // this.
119
- if (isHeldRef?.current) {
120
- wasHeld = true;
121
- }
122
- if (hasSettled || isTouching || isHeldRef?.current) {
106
+ // A finger still on the glass is not rest, however quiet the scroller
107
+ // has gone. The release re-arms this.
108
+ if (hasSettled || isTouching) {
123
109
  return;
124
110
  }
125
111
  hasSettled = true;
@@ -140,9 +126,6 @@ export function useScrollSettle(
140
126
  // the last of it however long it runs.
141
127
  hasSettled = false;
142
128
  isAtRestRef.current = false;
143
- if (isHeldRef?.current) {
144
- wasHeld = true;
145
- }
146
129
  arm();
147
130
  };
148
131
 
@@ -161,23 +144,11 @@ export function useScrollSettle(
161
144
  arm();
162
145
  };
163
146
 
164
- const onPointerEnd = () => {
165
- // The drag's release: its glide to the nearest row re-arms this on its
166
- // own, and the timer covers a release already on a row, which scrolls
167
- // no further.
168
- if (wasHeld) {
169
- wasHeld = false;
170
- arm();
171
- }
172
- };
173
-
174
147
  element.addEventListener('scroll', onScroll, {passive: true});
175
148
  element.addEventListener('scrollend', settle);
176
149
  element.addEventListener('touchstart', onTouchStart, {passive: true});
177
150
  element.addEventListener('touchend', onTouchEnd, {passive: true});
178
151
  element.addEventListener('touchcancel', onTouchEnd, {passive: true});
179
- element.addEventListener('pointerup', onPointerEnd);
180
- element.addEventListener('pointercancel', onPointerEnd);
181
152
 
182
153
  return () => {
183
154
  clearTimeout(timer);
@@ -186,10 +157,8 @@ export function useScrollSettle(
186
157
  element.removeEventListener('touchstart', onTouchStart);
187
158
  element.removeEventListener('touchend', onTouchEnd);
188
159
  element.removeEventListener('touchcancel', onTouchEnd);
189
- element.removeEventListener('pointerup', onPointerEnd);
190
- element.removeEventListener('pointercancel', onPointerEnd);
191
160
  };
192
- }, [ref, isEnabled, isHeldRef]);
161
+ }, [ref, isEnabled]);
193
162
 
194
163
  return {isAtRestRef};
195
164
  }
@@ -1,68 +1,49 @@
1
1
  ---
2
2
  schema_version: 3
3
- template_version: 7
3
+ template_version: 3
4
4
  kind: component
5
5
  id: component:Pagination
6
- authority: current
6
+ authority: draft
7
7
  archive_reason: null
8
8
  superseded_by: null
9
- approved_by: cixzhang
10
- approved_at: 2026-10-31
9
+ approved_by: null
10
+ approved_at: null
11
11
  owners: [cixzhang]
12
- review_triggers: [public-api, behavior, layout, theming, accessibility]
12
+ review_triggers: [theming]
13
13
  verified_by:
14
14
  [
15
15
  packages/core/src/Pagination/Pagination.test.tsx,
16
- packages/core/src/hooks/useListFocus.test.tsx,
16
+ packages/core/src/Button/Button.test.tsx,
17
+ packages/core/src/Text/Text.test.tsx,
18
+ packages/core/src/NumberInput/NumberInput.test.tsx,
19
+ packages/core/src/Selector/Selector.test.tsx,
17
20
  packages/core/src/theme/themingTargets.test.ts,
18
21
  scripts/check-knowledge.mjs,
19
22
  ]
20
23
  modules: []
21
24
  families: []
22
- design_specs: [design:bidirectionality, design:reduced-motion]
23
- architecture:
24
- [
25
- architecture:component-theming-surface,
26
- architecture:internationalization,
27
- architecture:public-component-api,
28
- ]
25
+ design_specs: []
26
+ architecture: [architecture:component-theming-surface]
29
27
  contributing: []
30
- system_specs:
31
- [spec:AST-020/FR15, spec:AST-085, spec:AST-086, spec:AST-094, spec:AST-102]
28
+ system_specs: []
32
29
  ---
33
30
 
34
31
  # Pagination component contract
35
32
 
36
- ## Contract at a glance
37
-
38
- | Area | Contract |
39
- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
40
- | Public contract | None changes. Pagination takes `page`, `onChange`, `changeAction`, `totalItems`, `totalPages`, `hasMore`, `pageSize`, `pageSizeOptions`, `onPageSizeChange`, `variant`, `pageLabel`, `hasFirstLast`, `step`, `siblingCount`, `size`, `isDisabled`, `label`, and base props. |
41
- | Behavior | A labelled navigation landmark with Previous and Next buttons around a variant-specific indicator. Every page change calls `onChange`, announces the new page, and runs an optional `changeAction` with an optimistic page. |
42
- | End-user impact | People move through pages by buttons, page numbers, dots, or typing a page, and screen-reader users hear the page they landed on. A keyboard user on Next at the last page loses focus because Next becomes natively disabled. |
43
- | Builder impact | None. |
44
- | Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Boundary and disabled buttons use native `disabled`, the dots are not exposed as a radio group and have no coarse-pointer hit area, and delegated Buttons carry their own gaps; all are listed under Current-state impact. |
45
- | Review checks | Reject a page change outside 1 to the total, a page change without an announcement, a disabled Pagination that changes page, a landmark without a name, or a delegated control re-themed by Pagination. |
46
- | Governing rules | `spec:AST-020` FR15, DEC-4; `spec:AST-085` FR1, FR4, FR7; `spec:AST-086`; `spec:AST-094` FR42; `spec:AST-102` FR4; `design:bidirectionality` DR6; `design:reduced-motion` DR1; `architecture:component-theming-surface`; `architecture:internationalization` INV1a. |
47
-
48
- This table is a review projection; the body below is authoritative.
49
-
50
33
  ## Intent
51
34
 
52
- Pagination presents controls for moving through pages and may let people choose
53
- a page size or enter a page directly. It owns the page arithmetic, which
54
- controls render for each variant, the page-change pipeline and announcement,
55
- and its four local theming targets. Consumer usage lives in
56
- `Pagination.doc.mjs`.
35
+ Pagination presents controls for moving through pages and may let people choose a
36
+ page size or enter a page directly. This draft records its current consumer
37
+ anatomy, four local theming targets, delegated control ownership, and current
38
+ unreached Ellipsis without changing runtime behavior, styling, targets, or public
39
+ API.
57
40
 
58
41
  ## Compatibility and migration
59
42
 
60
- - Released default preserved: `yes`; `variant="pages"`, `pageSize={10}`,
61
- `step={1}`, `siblingCount={1}`, `size="md"`
62
- - Compatibility class: records shipped behavior; no public prop, default,
63
- export, or DOM change
64
- - Controlled/uncontrolled behavior: controlled; `page` is the committed page,
65
- and Pagination shows an optimistic page only while a `changeAction` is pending
43
+ - Released default preserved: `yes`
44
+ - Compatibility class: additive documentation only; runtime, DOM, styling,
45
+ targets, aliases, and public API remain unchanged
46
+ - Controlled/uncontrolled behavior: unchanged
66
47
  - Migration decision: none
67
48
 
68
49
  Consumer migration instructions belong in consumer docs and release notes.
@@ -77,113 +58,84 @@ Consumer migration instructions belong in consumer docs and release notes.
77
58
  targets.
78
59
  - Choosing which stable controls and readouts render for the current paging
79
60
  configuration.
80
- - Page-count arithmetic, step clamping, the page range with ellipses, and the
81
- page-change pipeline and announcement.
82
61
 
83
62
  **Does not own / non-goals**
84
63
 
85
64
  - Button, Text, NumberInput, or Selector presentation and targets; those remain
86
65
  owned by their respective components.
87
66
  - Button icon artwork or other internals of delegated controls.
88
- - A public target for Ellipsis; none exists (OQ2).
89
- - Fetching or slicing the data being paged — owned by the caller.
67
+ - A public target for Ellipsis; none exists on current `main`.
68
+ - New paging behavior, variants, state, public API, or theming targets.
90
69
 
91
70
  ## Public concepts
92
71
 
93
- | Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
94
- | ---------- | ---------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- | ----------- | ---------------------- | --------- | ------------------------------------------------------------------- |
95
- | Page | integer from 1 | The current page. | Always. | required | `component:Pagination` | Stable | Not clamped; Previous and Next follow it. |
96
- | Data shape | `totalItems`, `totalPages`, or `hasMore` | Known item count, known page count, or cursor paging. | `totalPages` wins over the count derived from `totalItems`. | unknown | `component:Pagination` | Stable | A zero or negative total renders nothing. |
97
- | Variant | `pages`, `count`, `compact`, `dots`, `input`, `none` | What sits between Previous and Next. | Indicators that need a total render nothing without one. | `pages` | `component:Pagination` | Stable | TypeScript rejects values absent from `PaginationVariantMap`. |
98
- | Step | positive integer | Pages Previous and Next move per press. | Always. | `1` | `component:Pagination` | Stable | A non-integer or value below 1 becomes 1. |
99
- | Page size | positive integer; optional option list | Items per page; a selector when options are given. | Always. | `10` | `component:Pagination` | Stable | A non-finite size becomes 10; a fraction floors; below 1 becomes 1. |
100
- | First/last | on, off | Jump buttons flanking Previous and Next. | `input` (on by default) and `compact` (off by default) with a known total. | per variant | `component:Pagination` | Stable | Other variants ignore it. |
101
- | Size | `sm`, `md` | Control size. | Always. | `md` | `component:Pagination` | Stable | TypeScript rejects other values. |
72
+ No new public concept is introduced. Consumer props, presentations, defaults,
73
+ and usage remain documented in `Pagination.doc.mjs`.
102
74
 
103
75
  ## Behavioral and layout contract
104
76
 
105
- | ID | Invariant | Basis |
106
- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
107
- | FR1 | The current render contains one Pagination landmark (`<nav>` named by `label`, else the localized "Pagination", unless a caller's `aria-labelledby` names it) and Previous/next buttons. Page-size selector, First/last buttons, Page number buttons, Ellipsis, Count readout, Compact readout, Dots, Page input label, Page input, and Page input total appear only when their existing conditions are met. Pagination renders nothing when `totalItems` or the resolved page count is zero or less. | Current source and tests |
108
- | FR2 | Pagination, Dot, Page input label, and Page input total carry the four current local targets `pagination` (with `data-variant` and `data-size`), `pagination-dot` (`data-active`, `data-size`), `pagination-input-label` (`data-size`), and `pagination-input-total` (`data-size`). | `architecture:component-theming-surface`; current source |
109
- | FR3 | Page-size selector delegates to Selector; First/last, Previous/next, and Page number buttons delegate to Button; Count and Compact readouts delegate to Text; Page input delegates to NumberInput. The delegated Buttons carry `component:Button`'s gaps: their press scale applies under reduced motion (`design:reduced-motion` DR1) and their height is fixed (`spec:AST-102` FR4). | Current source; `design:reduced-motion` DR1; `spec:AST-102` FR4 |
110
- | FR4 | Ellipsis is stable visible Pagination-rendered content in a numbered presentation, hidden from assistive technology, and currently carries no public target. | Current source |
111
- | FR5 | The page count is `totalPages`, else `totalItems / pageSize` rounded up, else unknown. Previous is available above page 1; Next is available below the known count, or when `hasMore` with no count. Previous and Next move by `step`, clamped to 1 and the known count; First goes to 1 and Last to the count. | Current tests |
112
- | FR6 | Every page change calls `onChange(page)`, announces "Page X of Y" (or "Page X" without a count) through the shared polite channel, and runs `changeAction(page)` in a transition while the optimistic page shows. A later change while one is pending starts a fresh transition. Pagination shows no other pending treatment. | `spec:AST-086`; current tests |
113
- | FR7 | `pages` shows page buttons for the range when the count is known: every page when the count fits `5 + 2 × siblingCount` slots, otherwise, near an end, `3 + 2 × siblingCount` consecutive pages from that end, an ellipsis, and the other end (page 1 of 10 shows `1 2 3 4 5 … 10`); elsewhere the first page, an ellipsis, the current page with `siblingCount` neighbours, an ellipsis, and the last page. Each page button shows its number, is named "Go to page N", and the current one has `aria-current="page"`. | Current tests |
114
- | FR8 | `count` shows "X–Y of Z" for the visible item range (needs `totalItems`); `compact` shows "Page X of Y" (needs a count); `none` shows nothing between the buttons. | Current tests |
115
- | FR9 | With a known count, `dots` renders one dot button per page in a group named by the localized page-indicators label, as one composite single-choice control: a single roving Tab stop on the current dot; ArrowLeft and ArrowRight follow the reading direction (`design:bidirectionality` DR6) and wrap, Home and End reach the first and last dot, and focus landing on a dot selects its page; a click focuses the dot. While disabled, dots stay focusable with `aria-disabled` and change no page. Because the dots already play the APG radio group's role, they MUST expose its required parts: a `radiogroup` container and `radio` dots named by their page with `aria-checked` on the current one (`spec:AST-020` FR15, DEC-4); the arrow keys and Home/End are the composite's adopted extras. Implementation gap: the container is `role="group"` and the dots are buttons with `aria-current` on the current page. Under a coarse pointer each dot MUST gain an invisible hit area, clamped to half the gap between dots (`spec:AST-094` FR42). Implementation gap: dots are 8 px (6 px at `sm`) with no hit area. | `spec:AST-020` FR15, DEC-4; `spec:AST-094` FR42; `design:bidirectionality` DR6; current source and tests |
116
- | FR10 | `input` renders the page label (visual only), a hidden-label integer NumberInput bounded to 1 and the count, and "/ N" when the count is known. Committing a different page changes to it; the input is disabled without a known count. | `component:NumberInput`; current tests |
117
- | FR11 | With `pageSizeOptions`, a Selector labelled "Items per page" shows the options; choosing one calls `onPageSizeChange(size)` and then changes to page 1. | Current tests |
118
- | FR12 | Previous, Next, First, and Last name themselves with localized phrases (Previous and Next name the stride when `step` is above 1) and show that name as a tooltip only while available. Their chevrons mirror under RTL. | `architecture:internationalization`; current source and tests |
119
- | FR13 | `isDisabled` blocks every page change and disables every control. A disabled or boundary control MUST stay focusable with `aria-disabled` and keep focus when it becomes unavailable (`spec:AST-085` FR1, FR4, FR7). Implementation gap: dots and the page-size Selector use `aria-disabled`, but the Buttons use their native-disabled path, so a focused Previous, Next, First, or Last that reaches a boundary drops focus. | `spec:AST-085`; current source and tests |
120
- | FR14 | `ref`, `className`, `style`, `xstyle`, `data-testid`, and other base props reach the landmark. A caller's `aria-label` never replaces the computed landmark name (`label`, else the localized default); other caller ARIA props, such as `aria-labelledby`, still reach the landmark. `data-testid` also reaches the input variant's NumberInput as `<id>-input`. | Current tests |
77
+ | ID | Candidate invariant | Basis | Draft review state |
78
+ | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
79
+ | FR1 | The current render contains one Pagination landmark and Previous/next buttons. Page-size selector, First/last buttons, Page number buttons, Ellipsis, Count readout, Compact readout, Dots, Page input label, Page input, and Page input total appear only when their existing conditions are met. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
80
+ | FR2 | Pagination, Dot, Page input label, and Page input total carry the four current local targets `pagination`, `pagination-dot`, `pagination-input-label`, and `pagination-input-total`. | Current source, docs, and history | Verified current inventory; focused placement coverage is absent |
81
+ | FR3 | Page-size selector delegates to Selector; First/last, Previous/next, and Page number buttons delegate to Button; Count and Compact readouts delegate to Text; Page input delegates to NumberInput. | Current source and owner evidence | Verified current ownership; no target change |
82
+ | FR4 | Ellipsis is stable visible Pagination-rendered content in a numbered presentation and currently carries no public target. | Current source, tests, and target docs | Verified current reachability; long-term theming intent remains unsettled |
121
83
 
122
84
  ### Allowed variation
123
85
 
124
- - **AV1 — Theme paint.** Themes may restyle the local targets; delegated
125
- controls follow their own targets.
126
- - **AV2 — Custom variants.** None. The variant axis MUST be closed
127
- (`architecture:component-theming-surface` INV14). Implementation gap: the
128
- variant map is open to module augmentation, and an augmented variant renders
129
- Previous and Next only.
86
+ - **AV1 — Paging data.** Current page, total pages, total items, page size, and
87
+ stride may vary without changing anatomy ownership.
88
+ - **AV2 — Presentation.** Existing presentation selection changes which optional
89
+ stable parts are present; presentation names and runtime states are not anatomy.
90
+ - **AV3 — Delegated rendering.** Button, Text, NumberInput, and Selector may
91
+ change internal element shape while preserving their own public contracts.
130
92
 
131
93
  ### Representative states
132
94
 
133
- | State | Required invariant | Allowed variation |
134
- | -------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------- |
135
- | First page | Previous unavailable; Next available. | Variant. |
136
- | Middle page, `pages` | Range with ellipses; current page `aria-current`. | `siblingCount`. |
137
- | Cursor paging | No count; Next follows `hasMore`; count-only indicators hidden. | — |
138
- | Input variant | Label, bounded input, total; First and Last by default. | `pageLabel`. |
139
- | Disabled | No page change from any control. Implementation gap: native `disabled` on Buttons (FR13). | — |
140
- | Dots | One Tab stop; arrows, Home, and End select. Implementation gap: group of buttons, not a radio group (FR9). | Size. |
141
- | Zero items | Nothing renders. | — |
95
+ | State | Required invariant | Allowed variation |
96
+ | ----------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
97
+ | Numbered, known page count | Page number buttons render; Ellipsis appears only where pages are omitted. | Page count, sibling range, and active page. |
98
+ | Count with known item total | Count readout renders between Previous/next buttons. | Range and total text. |
99
+ | Compact with known page count | Compact readout renders between Previous/next buttons; First/last render only when opted in. | Current and total page text and first/last opt-in. |
100
+ | Dots with known page count | One Dot renders for each page and active state stays on the Dot target. | Dot count and active Dot. |
101
+ | Input with known page count | Page input label, Page input, and Page input total render; First/last may render. | Label text and first/last opt-out. |
102
+ | Input with unknown page count | Page input label and disabled Page input remain; total and First/last are absent. | Cursor-backed current page. |
103
+ | None | Previous/next buttons remain without a presentation-specific part between them. | Enabled state follows current paging availability. |
104
+
105
+ The optional Page-size selector may precede the paging controls in any current
106
+ presentation when page-size options are provided.
142
107
 
143
108
  ### Transformation and precedence order
144
109
 
145
- - **ORD1 — Page count.** `totalPages`, then `ceil(totalItems / pageSize)`, then
146
- unknown.
147
- - **ORD2 — Page change.** Disabled guard → `onChange` → announcement →
148
- optimistic page and `changeAction`.
149
- - **ORD3 — First/last.** `hasFirstLast` for `input` (default on) and `compact`
150
- (default off); omitted without a known count.
110
+ - No new page calculation, range generation, optimistic update, or styling
111
+ precedence rule is introduced.
151
112
 
152
113
  ### Performance and resources
153
114
 
154
- - **PR1 — Bounded resources.** The dots share one roving-focus handler on
155
- their group. The delegated Buttons add the press controller's shared window
156
- and document listeners; each tooltip's `interactionRef` adds pointer and focus
157
- listeners on its Button, and the Tooltip layer installs the shared
158
- gesture-counter document listeners once per page.
115
+ - No new performance or resource rule is introduced.
159
116
 
160
117
  ## Accessibility contract
161
118
 
162
- - **AR1 — Landmark.** A named `nav` landmark (FR1).
163
- - **AR2 — Current page.** `aria-current="page"` on the current page button
164
- (FR7). The dots MUST expose the current page with `aria-checked` in a radio
165
- group; FR9 records the gap.
166
- - **AR3 — Announcement.** FR6.
167
- - **AR4 — Disabled and boundaries.** FR13.
168
- - **AR5 — Decorative parts.** The ellipsis and the input variant's page label
169
- are hidden from assistive technology; the input is named by its hidden label.
119
+ This draft does not change or extend Pagination's existing navigation landmark,
120
+ button naming, current-page semantics, roving Dot focus, live announcements, or
121
+ input bounds.
170
122
 
171
123
  ## Design relationships
172
124
 
173
125
  | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
174
126
  | --------------------- | ------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |
175
127
  | Pagination | Groups the page-size and paging controls in a navigation landmark. | Current source and public docs | Supporting | FR1, FR2 |
176
- | Page-size selector | Lets people choose the number of items shown per page. | `component:Selector` | Supporting | FR3, FR11 |
177
- | First/last buttons | Jump directly to the first or last known page. | `component:Button` | Supporting | FR3, FR5, FR12 |
178
- | Previous/next buttons | Move backward or forward through pages. | `component:Button` | Prominent | FR3, FR5, FR12 |
179
- | Page number button | Selects one page directly in the numbered presentation. | `component:Button` | Prominent | FR3, FR7 |
180
- | Ellipsis | Indicates an omitted span of page numbers. | Current source and public docs | Supporting | FR4, FR7 |
181
- | Count readout | Presents the visible item range and total. | `component:Text` | Prominent | FR3, FR8 |
182
- | Compact readout | Presents the current and total page counts. | `component:Text` | Prominent | FR3, FR8 |
183
- | Dot | Presents and selects one page in the dot presentation. | Current source and public docs | Prominent | FR2, FR9 |
184
- | Page input label | Names the editable page field visually. | Current source and public docs | Supporting | FR2, FR10 |
185
- | Page input | Accepts a direct page-number entry. | `component:NumberInput` | Prominent | FR3, FR10 |
186
- | Page input total | Presents the known total after the editable page field. | Current source and public docs | Supporting | FR2, FR10 |
128
+ | Page-size selector | Lets people choose the number of items shown per page. | `component:Selector` | Supporting | FR1, FR3 |
129
+ | First/last buttons | Jump directly to the first or last known page. | `component:Button` | Supporting | FR1, FR3 |
130
+ | Previous/next buttons | Move backward or forward through pages. | `component:Button` | Prominent | FR1, FR3 |
131
+ | Page number button | Selects one page directly in the numbered presentation. | `component:Button` | Prominent | FR1, FR3 |
132
+ | Ellipsis | Indicates an omitted span of page numbers. | Current source and public docs | Supporting | FR1, FR4 |
133
+ | Count readout | Presents the visible item range and total. | `component:Text` | Prominent | FR1, FR3 |
134
+ | Compact readout | Presents the current and total page counts. | `component:Text` | Prominent | FR1, FR3 |
135
+ | Dot | Presents and selects one page in the dot presentation. | Current source and public docs | Prominent | FR1, FR2 |
136
+ | Page input label | Names the editable page field visually. | Current source and public docs | Supporting | FR1, FR2 |
137
+ | Page input | Accepts a direct page-number entry. | `component:NumberInput` | Prominent | FR1, FR3 |
138
+ | Page input total | Presents the known total after the editable page field. | Current source and public docs | Supporting | FR1, FR2 |
187
139
 
188
140
  The three Button rows are separate stable controls with different conditions and
189
141
  jobs; they do not create Pagination-owned Button targets. Presentation values,
@@ -239,62 +191,36 @@ does not decide whether it should remain unreachable.
239
191
  target mapping, delegation, state placement, and factual `none` dispositions.
240
192
  - Button, Text, NumberInput, and Selector retain ownership of their delegated
241
193
  targets and presentation.
242
- - `spec:AST-085` owns disabled focusability; FR13 records the gap.
243
- - `spec:AST-020` FR15 owns which APG parts the dots adopt; FR9 records the gap.
244
- - `spec:AST-094` FR42 owns coarse-pointer hit areas; FR9 records the gap.
245
- - `spec:AST-086` owns the page announcement channel.
246
194
 
247
195
  ## Verification map
248
196
 
249
- | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
250
- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
251
- | FR1, FR14 | `Pagination.test.tsx` basic-rendering, zero-item, and rest-forwarding cases | Default and custom label; zero items or pages; `data-testid`, `id`, `aria-describedby` | A missing or misnamed landmark, a render at zero, or a dropped `data-testid`, `id`, or `aria-*` fails. Evidence gap: no test asserts `ref`, `className`, `style`, `xstyle`, the computed `aria-label` replacing a caller's, a caller's `aria-labelledby` reaching the landmark, or the input variant's `<id>-input` test id. | `audit:Pagination/anatomy` |
252
- | FR2 | `themingTargets.test.ts` | Rendered targets | A rendered class absent from the documented targets fails. Evidence gap: no test asserts the placement or reflected properties of the four local targets (OQ1). | `audit:Pagination/theming` |
253
- | FR3 | `Pagination.test.tsx` "does not introduce Stack theme targets around navigation controls" | Navigation controls | An added Stack target fails. Evidence gap: no test asserts each delegated owner; the delegated Button gaps are asserted by `component:Button`'s own records, not here. | `audit:Pagination/theming` |
254
- | FR4, FR7 | `generatePageRange` cases; `Pagination.test.tsx` pages cases ("renders page number buttons", "marks current page with aria-current", "shows ellipsis for many pages") | Left, right, and two-sided omission; `siblingCount` 0 and 2 | A wrong range, a missing ellipsis, or a missing `aria-current` fails. Evidence gap: no test asserts that the ellipsis is hidden from assistive technology. | `audit:Pagination/behavior` |
255
- | FR5, ORD1 | `Pagination.test.tsx` boundary, cursor, step, page-size guarding, and totalItems cases | First, middle, last, single page; `hasMore`; step clamp; invalid `pageSize` | A move past a bound or a wrong count derived from `totalItems` and `pageSize` fails. Evidence gap: no test passes both `totalItems` and `totalPages`, so ORD1's precedence is untested. | `audit:Pagination/behavior` |
256
- | FR6, ORD2 | `Pagination.test.tsx` page-change and changeAction cases | Mount, page button, Previous, Next, dot; pending, interrupted, and synchronous Actions; disabled | A missing `onChange`, announcement, or optimistic page, a `changeAction` before `onChange`, or an Action while disabled fails. Evidence gap: no test asserts the announcement's order relative to `onChange`. | `audit:Pagination/behavior` |
257
- | FR8 | `Pagination.test.tsx` count and compact cases | Count range and last-page clamp; compact text | A wrong readout fails. | `audit:Pagination/behavior` |
258
- | FR9 | `Pagination.test.tsx` dots cases ("uses roving tabindex — active dot has tabIndex 0, others -1", "ArrowRight moves focus to the next dot and selects it", "Home selects the first page, End the last", the wrap cases, "does not navigate with arrow keys when disabled", "marks active dot with aria-current" asserting the current gap pending conformance); `useListFocus.test.tsx` RTL cases | Dots; RTL; disabled | A second Tab stop, an arrow or Home/End that does not select, a missing wrap, a disabled dot that drops focus or changes page, or reversed RTL arrows fail. Evidence gap: no Pagination-level RTL dots test and no coarse-pointer hit-area test. | `audit:Pagination/accessibility` |
259
- | FR10 | `Pagination.test.tsx` input and pageLabel cases | Known and unknown totals; Enter, blur, invalid, below and above range; custom label; disabled | A wrong bound, a missing commit or announcement, or a commit while disabled fails. | `audit:Pagination/behavior` |
260
- | FR11 | `Pagination.test.tsx` page-size selector cases | With and without `pageSizeOptions` | Evidence gap: the page-size cases only check that the landmark and buttons render, so no test asserts the Selector's presence or absence, `onPageSizeChange`, or the reset to page 1. | `audit:Pagination/behavior` |
261
- | FR12, ORD3 | `Pagination.test.tsx` first/last, step-name, tooltip, and RTL chevron cases | `hasFirstLast` on `compact` and `input`; stride names; RTL | A wrong name, a missing First or Last, a Previous or Next without a tooltip, or a First or Last chevron that does not mirror like Previous and Next fails. Evidence gap: no test asserts the tooltip text, that the tooltip is absent while a control is unavailable, or that the chevrons mirror under RTL. | `audit:Pagination/accessibility` |
262
- | FR13 | `Pagination.test.tsx` disabled-state and boundary cases, asserting native `disabled` on the Buttons as the current gap pending conformance | Disabled; first and last page | A page change while disabled fails. Evidence gap: no test asserts focus kept at a boundary. | `audit:Pagination/accessibility` |
263
- | PR1, AR1–AR5 | PR1 has no test (evidence gap). AR1 to AR5 are covered by the FR1, FR6, FR7, FR9, FR10, and FR13 rows. | — | — | `audit:Pagination/accessibility` |
264
- | Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Pagination/theming` |
265
-
266
- ## Current-state impact
267
-
268
- - **Dots semantics (FR9).** The dots act as one single-choice control but are
269
- exposed as a group of buttons with `aria-current`, not a radio group, against
270
- `spec:AST-020` FR15.
271
- - **Dot hit area (FR9).** Dots are 8 px (6 px at `sm`) with no coarse-pointer
272
- hit area, against `spec:AST-094` FR42.
273
- - **Open variant axis (AV2).** The variant map accepts module-augmented
274
- values, which render Previous and Next only, against
275
- `architecture:component-theming-surface` INV14.
276
- - **Page-count docs (FR5, ORD1).** `totalPages` wins over the count derived
277
- from `totalItems`, while the prop documentation says `totalItems` takes
278
- precedence when both are given.
279
- - **Delegated Button gaps (FR3).** The page and navigation Buttons scale on a
280
- press under reduced motion and hold a fixed height, as `component:Button`
281
- records, against `design:reduced-motion` DR1 and `spec:AST-102` FR4.
282
- - **Boundary and disabled focus (FR13).** Previous, Next, First, Last, and page
283
- buttons use native `disabled`, so a keyboard user on Next at the last page
284
- loses focus, against `spec:AST-085` FR1, FR4, and FR7.
197
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
198
+ | ------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------- |
199
+ | FR1 | `Pagination.test.tsx` presentation, page-size, input, and navigation suites | Numbered, count, compact, dots, input, none, known/unknown | Removing or misplacing a stable control fails existing role, text, or interaction assertions. | `audit:Pagination/anatomy` |
200
+ | FR2 | Source inspection, public target metadata, target-introduction history, and `themingTargets.test.ts` | Four local targets and their current capabilities | Removing a current target fails the global inventory; focused placement is not currently pinned. | `audit:Pagination/theming` |
201
+ | FR3 | Pagination composition tests plus Button, Text, NumberInput, and Selector target tests and metadata | All delegated controls and readouts | A composed owner losing its target fails owner coverage; replacing it requires this map to change. | `audit:Pagination/theming` |
202
+ | FR4 | `generatePageRange` tests, render-source inspection, and current target metadata | Left, right, and two-sided omission | Adding or documenting an Ellipsis target requires an explicit map and target-inventory update. | `audit:Pagination/theming` |
203
+ | Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and four current local targets | Missing, extra, prefixed, stale, or multiply assigned local mappings fail repository validation. | `audit:Pagination/theming` |
204
+
205
+ Pagination has broad behavior coverage but no focused assertions for placement
206
+ of its four local target classes. Delegated owner tests pin the owner targets;
207
+ Pagination tests pin that the corresponding controls render, not their target
208
+ class composition.
285
209
 
286
210
  ## Decision log
287
211
 
288
- No component-local decision.
212
+ None. This draft records current facts and introduces no component-local design,
213
+ API, behavior, or theming decision.
289
214
 
290
215
  ## Open questions
291
216
 
292
217
  - **OQ1 — Which focused tests should pin placement and reflected properties for
293
218
  the four local Pagination targets?** (`checkable`)
294
219
  - **OQ2 — Should Ellipsis gain a stable public theming target?** (`human-api`)
295
- Its current lack of reachability does not decide the answer.
220
+ Its current lack of reachability is an audit gap, not settled intent.
296
221
 
297
222
  ## Content boundary
298
223
 
299
- This file does not duplicate consumer prop tables/examples, current audit
300
- results, implementation steps, or system rules. It links to their owners.
224
+ This file does not duplicate consumer prop tables/examples, paging algorithms,
225
+ implementation steps, owner-component internals, or system theming rules. It
226
+ links to their owners.
@@ -202,19 +202,19 @@ anatomy-theming map.
202
202
 
203
203
  ## Verification map
204
204
 
205
- | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
206
- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
207
- | FR1, ORD1 | `Presentation.test.tsx`; `NativeTimeInput.test.tsx` mode cases | Each value × pointer; deprecated mapping; both props | A substituted surface, a lost fallback, or `nativePicker` winning fails. Evidence gap: no real-browser check of the surface per pointer, as `spec:AST-043` asks. No test covers `presentation="popover"`. | `audit:TimeInput/behavior` |
208
- | FR3–FR5, AR2 | `TimeInput.test.tsx` typing, blur, invalid, stepping, IME, and format cases, including "shows the catalog format hint for the resolved hour format" (24-hour) | 12h, 24h, seconds; invalid and out of range | A commit of an invalid time, a missing alert, or a step during IME fails. Evidence gap: no test asserts the 12-hour format hint, stepping from the current time when empty, or a step that would leave the range. No test steps while a draft is pending. | `audit:TimeInput/behavior` |
209
- | FR6 | `NativeTimeInput.test.tsx` | Coarse default; range; pending Action; clear; clock button | An out-of-range native commit, or a reopened picker after clear, fails. | `audit:TimeInput/behavior` |
210
- | FR7, ORD3, AR4 | `Presentation.test.tsx` sheet cases | Forced and adaptive sheet; disabled | A sheet field that is not inert while disabled fails. Evidence gap: no test opens the sheet by keyboard or asserts the clock button's tab order. No test disables an out-of-range wheel option or clamps a wheel change. | `audit:TimeInput/behavior` |
211
- | FR8 | `TimeInput.test.tsx` clear cases; `NativeTimeInput.test.tsx` clear case | With value; empty | A clear on an empty field, or no `undefined`, fails. Evidence gap: no test asserts the focus move after clear on either surface, `changeAction` on clear, or a clear or Save press under reduced motion. | `audit:TimeInput/behavior` |
212
- | FR9, AR3 | `TimeInput.test.tsx` disabled suites; `NativeTimeInput.test.tsx` and `Presentation.test.tsx` disabled cases; `InputGroup.test.tsx` disabled-propagation cases | Each surface; with reason; draft in progress | A lost tab stop, a value change, or a caller `onClick` fails. Evidence gap: no test asserts that caller `onKeyDown` and similar handlers still run while disabled (the FR9 gap). | `audit:TimeInput/accessibility` |
213
- | FR10 | `TimeInput.test.tsx` InputGroup suite | Grouped with description and status | A duplicate label, a visible status icon, or a missed announcement fails. Evidence gap: no test groups the sheet surface. | `audit:TimeInput/accessibility` |
214
- | FR11 | `TimeInput.fr10.test.tsx` | Each surface; handler composition | A base prop off the control, or a caller handler that cancels built-ins, fails. | `audit:TimeInput/api` |
215
- | FR12 | `TimeInput.test.tsx` status and theme-state cases | Status; disabled | A missing state attribute fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TimeInput/theming` |
216
- | FR2, ORD2 | Evidence gap: no TimeInput test of the pending Action's optimistic value | — | — | `audit:TimeInput/behavior` |
217
- | AR1, PR1 | Covered by the FR10 and FR11 rows for naming. Evidence gap: no test asserts the single coarse-pointer query that decides the surface | — | — | `audit:TimeInput/behavior` |
205
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
206
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
207
+ | FR1, ORD1 | `Presentation.test.tsx`; `NativeTimeInput.test.tsx` mode cases | Each value × pointer; deprecated mapping; both props | A substituted surface, a lost fallback, or `nativePicker` winning fails. Evidence gap: no real-browser check of the surface per pointer, as `spec:AST-043` asks. No test covers `presentation="popover"`. | `audit:TimeInput/behavior` |
208
+ | FR3–FR5, AR2 | `TimeInput.test.tsx` typing, blur, invalid, stepping, IME, and format cases | 12h, 24h, seconds; invalid and out of range | A commit of an invalid time, a missing alert, or a step during IME fails. Evidence gap: no test asserts the format hint, stepping from the current time when empty, or a step that would leave the range. No test steps while a draft is pending. | `audit:TimeInput/behavior` |
209
+ | FR6 | `NativeTimeInput.test.tsx` | Coarse default; range; pending Action; clear; clock button | An out-of-range native commit, or a reopened picker after clear, fails. | `audit:TimeInput/behavior` |
210
+ | FR7, ORD3, AR4 | `Presentation.test.tsx` sheet cases | Forced and adaptive sheet; disabled | A sheet field that is not inert while disabled fails. Evidence gap: no test opens the sheet by keyboard or asserts the clock button's tab order. No test disables an out-of-range wheel option or clamps a wheel change. | `audit:TimeInput/behavior` |
211
+ | FR8 | `TimeInput.test.tsx` clear cases; `NativeTimeInput.test.tsx` clear case | With value; empty | A clear on an empty field, or no `undefined`, fails. Evidence gap: no test asserts the focus move after clear on either surface, `changeAction` on clear, or a clear or Save press under reduced motion. | `audit:TimeInput/behavior` |
212
+ | FR9, AR3 | `TimeInput.test.tsx` disabled suites; `NativeTimeInput.test.tsx` and `Presentation.test.tsx` disabled cases; `InputGroup.test.tsx` disabled-propagation cases | Each surface; with reason; draft in progress | A lost tab stop, a value change, or a caller `onClick` fails. Evidence gap: no test asserts that caller `onKeyDown` and similar handlers still run while disabled (the FR9 gap). | `audit:TimeInput/accessibility` |
213
+ | FR10 | `TimeInput.test.tsx` InputGroup suite | Grouped with description and status | A duplicate label, a visible status icon, or a missed announcement fails. Evidence gap: no test groups the sheet surface. | `audit:TimeInput/accessibility` |
214
+ | FR11 | `TimeInput.fr10.test.tsx` | Each surface; handler composition | A base prop off the control, or a caller handler that cancels built-ins, fails. | `audit:TimeInput/api` |
215
+ | FR12 | `TimeInput.test.tsx` status and theme-state cases | Status; disabled | A missing state attribute fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TimeInput/theming` |
216
+ | FR2, ORD2 | Evidence gap: no TimeInput test of the pending Action's optimistic value | — | — | `audit:TimeInput/behavior` |
217
+ | AR1, PR1 | Covered by the FR10 and FR11 rows for naming. Evidence gap: no test asserts the single coarse-pointer query that decides the surface | — | — | `audit:TimeInput/behavior` |
218
218
 
219
219
  ## Current-state impact
220
220