@astryxdesign/core 0.4.6 → 0.4.7-canary.29be96d

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 (197) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/dist/BottomSheet/BottomSheet.d.ts +1 -0
  3. package/dist/BottomSheet/BottomSheet.d.ts.map +1 -1
  4. package/dist/BottomSheet/BottomSheet.js +54 -15
  5. package/dist/BottomSheet/BottomSheetEdgeTint.d.ts +6 -0
  6. package/dist/BottomSheet/BottomSheetEdgeTint.d.ts.map +1 -0
  7. package/dist/BottomSheet/BottomSheetEdgeTint.js +62 -0
  8. package/dist/BottomSheet/BottomSheetPanel.d.ts.map +1 -1
  9. package/dist/BottomSheet/BottomSheetPanel.js +1 -0
  10. package/dist/BottomSheet/BottomSheetSwitcher.d.ts +1 -0
  11. package/dist/BottomSheet/BottomSheetSwitcher.d.ts.map +1 -1
  12. package/dist/BottomSheet/BottomSheetSwitcher.js +10 -4
  13. package/dist/BottomSheet/useSheetGestures.d.ts.map +1 -1
  14. package/dist/BottomSheet/useSheetGestures.js +23 -5
  15. package/dist/Breadcrumbs/BreadcrumbItem.d.ts.map +1 -1
  16. package/dist/Breadcrumbs/BreadcrumbItem.js +5 -5
  17. package/dist/Calendar/Calendar.d.ts +3 -1
  18. package/dist/Calendar/Calendar.d.ts.map +1 -1
  19. package/dist/Calendar/Calendar.js +13 -14
  20. package/dist/Calendar/getInitialFocusDate.d.ts +46 -0
  21. package/dist/Calendar/getInitialFocusDate.d.ts.map +1 -0
  22. package/dist/Calendar/getInitialFocusDate.js +62 -0
  23. package/dist/Chat/ChatMessageList.d.ts +22 -3
  24. package/dist/Chat/ChatMessageList.d.ts.map +1 -1
  25. package/dist/Chat/ChatMessageList.js +6 -3
  26. package/dist/DateInput/TouchDateField.d.ts.map +1 -1
  27. package/dist/DateInput/TouchDateField.js +34 -1
  28. package/dist/Dialog/Dialog.d.ts +7 -1
  29. package/dist/Dialog/Dialog.d.ts.map +1 -1
  30. package/dist/Dialog/Dialog.js +48 -22
  31. package/dist/Heading/Heading.d.ts.map +1 -1
  32. package/dist/Heading/Heading.js +6 -2
  33. package/dist/Kbd/Kbd.d.ts.map +1 -1
  34. package/dist/Kbd/Kbd.js +10 -3
  35. package/dist/Markdown/index.d.ts +1 -1
  36. package/dist/Markdown/index.d.ts.map +1 -1
  37. package/dist/Markdown/parser.d.ts +38 -1
  38. package/dist/Markdown/parser.d.ts.map +1 -1
  39. package/dist/Markdown/parser.js +149 -23
  40. package/dist/MultiSelector/MultiSelector.d.ts +15 -1
  41. package/dist/MultiSelector/MultiSelector.d.ts.map +1 -1
  42. package/dist/MultiSelector/MultiSelector.js +17 -6
  43. package/dist/MultiSelector/index.d.ts +1 -1
  44. package/dist/MultiSelector/index.d.ts.map +1 -1
  45. package/dist/Selector/Selector.d.ts.map +1 -1
  46. package/dist/Selector/Selector.js +5 -0
  47. package/dist/Stepper/Step.d.ts +140 -0
  48. package/dist/Stepper/Step.d.ts.map +1 -0
  49. package/dist/Stepper/Step.js +1045 -0
  50. package/dist/Stepper/StepStatus.d.ts +24 -0
  51. package/dist/Stepper/StepStatus.d.ts.map +1 -0
  52. package/dist/Stepper/StepStatus.js +1 -0
  53. package/dist/Stepper/Stepper.d.ts +93 -0
  54. package/dist/Stepper/Stepper.d.ts.map +1 -0
  55. package/dist/Stepper/Stepper.js +184 -0
  56. package/dist/Stepper/StepperContext.d.ts +41 -0
  57. package/dist/Stepper/StepperContext.d.ts.map +1 -0
  58. package/dist/Stepper/StepperContext.js +34 -0
  59. package/dist/Stepper/index.d.ts +8 -0
  60. package/dist/Stepper/index.d.ts.map +1 -0
  61. package/dist/Stepper/index.js +7 -0
  62. package/dist/Stepper/stepper.stylex.d.ts +15 -0
  63. package/dist/Stepper/stepper.stylex.d.ts.map +1 -0
  64. package/dist/Stepper/stepper.stylex.js +20 -0
  65. package/dist/TabList/Tab.d.ts.map +1 -1
  66. package/dist/TabList/Tab.js +5 -1
  67. package/dist/Table/BaseTable.d.ts.map +1 -1
  68. package/dist/Table/BaseTable.js +4 -1
  69. package/dist/Table/plugins/groupedRows/useTableGroupedRows.d.ts.map +1 -1
  70. package/dist/Table/plugins/groupedRows/useTableGroupedRows.js +20 -8
  71. package/dist/Table/plugins/rowStatus/useTableRowStatus.d.ts.map +1 -1
  72. package/dist/Table/plugins/rowStatus/useTableRowStatus.js +10 -3
  73. package/dist/Table/plugins/selection/useTableSelection.d.ts +16 -0
  74. package/dist/Table/plugins/selection/useTableSelection.d.ts.map +1 -1
  75. package/dist/Table/plugins/selection/useTableSelection.js +19 -5
  76. package/dist/Table/types.d.ts +22 -4
  77. package/dist/Table/types.d.ts.map +1 -1
  78. package/dist/Table/useBaseTablePlugins.d.ts.map +1 -1
  79. package/dist/Table/useBaseTablePlugins.js +5 -0
  80. package/dist/Text/Text.d.ts.map +1 -1
  81. package/dist/Text/Text.js +6 -2
  82. package/dist/astryx.css +41 -1
  83. package/dist/hooks/index.d.ts +1 -0
  84. package/dist/hooks/index.d.ts.map +1 -1
  85. package/dist/hooks/index.js +1 -0
  86. package/dist/hooks/useHotkeys.d.ts.map +1 -1
  87. package/dist/hooks/useHotkeys.js +10 -3
  88. package/dist/hooks/useListFocus.d.ts +5 -2
  89. package/dist/hooks/useListFocus.d.ts.map +1 -1
  90. package/dist/hooks/useListFocus.js +12 -6
  91. package/dist/hooks/useMergedRefs.d.ts +18 -0
  92. package/dist/hooks/useMergedRefs.d.ts.map +1 -0
  93. package/dist/hooks/useMergedRefs.js +25 -0
  94. package/dist/index.d.ts +1 -0
  95. package/dist/index.d.ts.map +1 -1
  96. package/dist/index.js +1 -0
  97. package/dist/utils/timeParser.d.ts +1 -1
  98. package/dist/utils/timeParser.d.ts.map +1 -1
  99. package/dist/utils/timeParser.js +26 -12
  100. package/locales/en.json +14 -6
  101. package/locales/pseudo.json +6 -0
  102. package/package.json +8 -3
  103. package/src/Avatar/Avatar.doc.mjs +2 -1
  104. package/src/BottomSheet/BottomSheet.test.tsx +123 -0
  105. package/src/BottomSheet/BottomSheet.tsx +36 -4
  106. package/src/BottomSheet/BottomSheetEdgeTint.test.tsx +225 -0
  107. package/src/BottomSheet/BottomSheetEdgeTint.tsx +82 -0
  108. package/src/BottomSheet/BottomSheetPanel.test.tsx +66 -0
  109. package/src/BottomSheet/BottomSheetPanel.tsx +19 -0
  110. package/src/BottomSheet/BottomSheetSwitcher.tsx +13 -0
  111. package/src/BottomSheet/useSheetGestures.test.ts +27 -0
  112. package/src/BottomSheet/useSheetGestures.ts +25 -5
  113. package/src/Breadcrumbs/BreadcrumbItem.tsx +2 -1
  114. package/src/Button/Button.doc.mjs +22 -0
  115. package/src/Calendar/Calendar.doc.mjs +4 -3
  116. package/src/Calendar/Calendar.test.tsx +52 -0
  117. package/src/Calendar/Calendar.tsx +18 -15
  118. package/src/Calendar/getInitialFocusDate.test.ts +94 -0
  119. package/src/Calendar/getInitialFocusDate.ts +93 -0
  120. package/src/Chat/ChatMessageList.doc.mjs +9 -1
  121. package/src/Chat/ChatMessageList.test.tsx +46 -0
  122. package/src/Chat/ChatMessageList.tsx +28 -4
  123. package/src/CodeBlock/CodeBlock.doc.mjs +6 -0
  124. package/src/ContextMenu/ContextMenu.doc.mjs +5 -0
  125. package/src/DateInput/DateInputTouch.test.tsx +36 -0
  126. package/src/DateInput/TouchDateField.tsx +35 -1
  127. package/src/Dialog/Dialog.doc.mjs +8 -3
  128. package/src/Dialog/Dialog.test.tsx +71 -0
  129. package/src/Dialog/Dialog.tsx +72 -20
  130. package/src/Field/Field.doc.mjs +11 -0
  131. package/src/Heading/Heading.test.tsx +23 -1
  132. package/src/Heading/Heading.tsx +6 -2
  133. package/src/Kbd/Kbd.test.tsx +17 -0
  134. package/src/Kbd/Kbd.tsx +10 -3
  135. package/src/Link/Link.doc.mjs +11 -0
  136. package/src/Markdown/index.ts +1 -0
  137. package/src/Markdown/parser.perf.test.ts +71 -1
  138. package/src/Markdown/parser.test.ts +145 -2
  139. package/src/Markdown/parser.ts +208 -22
  140. package/src/MoreMenu/MoreMenu.doc.mjs +7 -1
  141. package/src/MultiSelector/MultiSelector.doc.mjs +10 -0
  142. package/src/MultiSelector/MultiSelector.test.tsx +105 -0
  143. package/src/MultiSelector/MultiSelector.tsx +50 -6
  144. package/src/MultiSelector/index.ts +1 -0
  145. package/src/NumberInput/NumberInput.doc.mjs +5 -0
  146. package/src/Popover/Popover.test.tsx +27 -1
  147. package/src/PowerSearch/PowerSearch.doc.mjs +10 -0
  148. package/src/Selector/Selector.doc.mjs +11 -0
  149. package/src/Selector/Selector.test.tsx +21 -0
  150. package/src/Selector/Selector.tsx +11 -1
  151. package/src/Stepper/Step.doc.mjs +98 -0
  152. package/src/Stepper/Step.tsx +1638 -0
  153. package/src/Stepper/StepStatus.ts +26 -0
  154. package/src/Stepper/Stepper.doc.mjs +370 -0
  155. package/src/Stepper/Stepper.test.tsx +1024 -0
  156. package/src/Stepper/Stepper.tsx +258 -0
  157. package/src/Stepper/StepperContext.ts +71 -0
  158. package/src/Stepper/index.ts +18 -0
  159. package/src/Stepper/stepper.stylex.ts +19 -0
  160. package/src/TabList/Tab.tsx +5 -1
  161. package/src/TabList/TabList.test.tsx +21 -4
  162. package/src/Table/BaseTable.tsx +6 -3
  163. package/src/Table/Table.test.tsx +35 -0
  164. package/src/Table/plugins/groupedRows/useTableGroupedRows-perf.test.tsx +112 -0
  165. package/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx +100 -0
  166. package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx +17 -8
  167. package/src/Table/plugins/rowStatus/useTableRowStatus.test.tsx +13 -7
  168. package/src/Table/plugins/rowStatus/useTableRowStatus.tsx +12 -3
  169. package/src/Table/plugins/selection/useTableSelection.test.tsx +76 -0
  170. package/src/Table/plugins/selection/useTableSelection.tsx +40 -7
  171. package/src/Table/types.ts +22 -4
  172. package/src/Table/useBaseTablePlugins.ts +5 -0
  173. package/src/Table/useTableGroupedRows.doc.mjs +5 -4
  174. package/src/Table/useTableRowStatus.doc.mjs +1 -1
  175. package/src/Table/useTableSelection.doc.mjs +31 -0
  176. package/src/Text/Text.test.tsx +23 -1
  177. package/src/Text/Text.tsx +6 -2
  178. package/src/TextInput/TextInput.doc.mjs +10 -0
  179. package/src/Toast/Toast.doc.mjs +6 -0
  180. package/src/Tokenizer/Tokenizer.doc.mjs +10 -0
  181. package/src/Toolbar/Toolbar.doc.mjs +5 -0
  182. package/src/__tests__/apiContractDrift.test.tsx +80 -0
  183. package/src/__tests__/fieldContract.test.tsx +24 -0
  184. package/src/__tests__/structuralComponentContract.test.tsx +39 -0
  185. package/src/hooks/index.ts +2 -0
  186. package/src/hooks/useHotkeys.test.ts +18 -0
  187. package/src/hooks/useHotkeys.ts +10 -3
  188. package/src/hooks/useListFocus.doc.mjs +2 -2
  189. package/src/hooks/useListFocus.test.tsx +65 -3
  190. package/src/hooks/useListFocus.ts +15 -7
  191. package/src/hooks/useMergedRefs.doc.mjs +79 -0
  192. package/src/hooks/useMergedRefs.test.tsx +62 -0
  193. package/src/hooks/useMergedRefs.ts +36 -0
  194. package/src/index.ts +1 -0
  195. package/src/theme/MediaTheme.doc.mjs +5 -5
  196. package/src/utils/timeParser.test.ts +6 -1
  197. package/src/utils/timeParser.ts +35 -13
@@ -263,6 +263,58 @@ describe('Calendar', () => {
263
263
  expect(day15).not.toBeDisabled();
264
264
  });
265
265
 
266
+ // ─── Initial Visible Month ───────────────────────────────────
267
+
268
+ describe('opens on a month inside the min/max window', () => {
269
+ beforeEach(() => {
270
+ vi.useFakeTimers({toFake: ['Date']});
271
+ vi.setSystemTime(new Date(2026, 7, 21, 12, 0, 0));
272
+ });
273
+ afterEach(() => {
274
+ vi.useRealTimers();
275
+ });
276
+
277
+ it('opens on today when today is inside the window', () => {
278
+ render(<Calendar min="2026-01-01" max="2026-12-31" />);
279
+
280
+ expect(screen.getByText('August 2026')).toBeInTheDocument();
281
+ });
282
+
283
+ it('opens on min when the window is entirely in the future', () => {
284
+ render(<Calendar min="2027-03-04" max="2027-06-30" />);
285
+
286
+ expect(screen.getByText('March 2027')).toBeInTheDocument();
287
+ expect(getDayButton(4, 'March', 2027)).not.toBeDisabled();
288
+ });
289
+
290
+ it('opens on max when the window is entirely in the past', () => {
291
+ render(<Calendar min="2019-01-01" max="2019-04-30" />);
292
+
293
+ expect(screen.getByText('April 2019')).toBeInTheDocument();
294
+ expect(getDayButton(30, 'April', 2019)).not.toBeDisabled();
295
+ });
296
+
297
+ it('keeps max in the last pane in the two-month layout', () => {
298
+ render(<Calendar numberOfMonths={2} min="2019-01-01" max="2019-04-30" />);
299
+
300
+ expect(screen.getByText('March 2019 – April 2019')).toBeInTheDocument();
301
+ });
302
+
303
+ it('still honors an explicit focusDate outside the window', () => {
304
+ render(
305
+ <Calendar focusDate="2026-01-01" min="2027-03-04" max="2027-06-30" />,
306
+ );
307
+
308
+ expect(screen.getByText('January 2026')).toBeInTheDocument();
309
+ });
310
+
311
+ it('still opens on the selected value outside the window', () => {
312
+ render(<Calendar defaultValue="2031-07-04" min="2019-01-01" />);
313
+
314
+ expect(screen.getByText('July 2031')).toBeInTheDocument();
315
+ });
316
+ });
317
+
266
318
  it('respects custom dateConstraints', () => {
267
319
  // Only allow weekdays
268
320
  const isWeekday = (date: Date) => {
@@ -11,6 +11,7 @@
11
11
  *
12
12
  * SYNC: When modified, update these files to stay in sync:
13
13
  * - /packages/core/src/Calendar/Calendar.doc.mjs (props table, features, implementation notes)
14
+ * - /packages/core/src/Calendar/getInitialFocusDate.ts (which month the calendar opens on)
14
15
  * - /packages/core/src/Calendar/Calendar.test.tsx (tests for new/changed behavior)
15
16
  * - /packages/core/src/Calendar/index.ts (exports if types change)
16
17
  * - /apps/storybook/stories/Calendar.stories.tsx (storybook stories)
@@ -60,6 +61,7 @@ import {
60
61
  } from '../utils/plainDate';
61
62
  import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
62
63
  import {focusOutlineProps} from '../utils/focusOutline.stylex';
64
+ import {getInitialFocusDate} from './getInitialFocusDate';
63
65
  import {
64
66
  computeDayCellState,
65
67
  computeRangeRounding,
@@ -142,7 +144,9 @@ interface CalendarBaseProps extends Omit<
142
144
 
143
145
  /**
144
146
  * Controlled focus date (which month is visible).
145
- * If not provided, defaults to selected date or today.
147
+ * If not provided, defaults to the selected date, else today clamped into
148
+ * the `min`/`max` window (so a window that excludes today opens on the
149
+ * bound nearest to it, not on an all-disabled month).
146
150
  */
147
151
  focusDate?: ISODateString;
148
152
 
@@ -277,20 +281,19 @@ export function Calendar({ref, ...props}: CalendarProps) {
277
281
  // Determine effective value
278
282
  const effectiveValue = value !== undefined ? value : internalValue;
279
283
 
280
- // Focus date state (which month is visible)
281
- const [internalFocusDate, setInternalFocusDate] = useState<PlainDate>(() => {
282
- if (focusDateProp) {
283
- return plainDateFromISO(focusDateProp);
284
- }
285
- if (effectiveValue) {
286
- if (typeof effectiveValue === 'string') {
287
- return plainDateFromISO(effectiveValue);
288
- } else {
289
- return plainDateFromISO(effectiveValue.start);
290
- }
291
- }
292
- return plainDateToday();
293
- });
284
+ // Focus date state (which month is visible). Falls back to today, clamped
285
+ // into the min/max window so a window that doesn't contain today doesn't
286
+ // open on an all-disabled month.
287
+ const [internalFocusDate, setInternalFocusDate] = useState<PlainDate>(() =>
288
+ getInitialFocusDate({
289
+ focusDate: focusDateProp,
290
+ value: effectiveValue,
291
+ min,
292
+ max,
293
+ numberOfMonths,
294
+ today,
295
+ }),
296
+ );
294
297
 
295
298
  // Use controlled focusDate if callback is provided, otherwise use internal state
296
299
  const isControlledFocus =
@@ -0,0 +1,94 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file getInitialFocusDate.test.ts
5
+ * @input Uses vitest
6
+ * @output Test suite for getInitialFocusDate
7
+ * @position Tests for getInitialFocusDate.ts
8
+ *
9
+ * SYNC: When getInitialFocusDate.ts changes, update tests accordingly
10
+ */
11
+
12
+ import {describe, it, expect} from 'vitest';
13
+ import {getInitialFocusDate} from './getInitialFocusDate';
14
+ import {plainDateFromISO, plainDateToISO} from '../utils/plainDate';
15
+
16
+ const TODAY = plainDateFromISO('2026-08-21');
17
+
18
+ function focusISO(options: Partial<Parameters<typeof getInitialFocusDate>[0]>) {
19
+ return plainDateToISO(
20
+ getInitialFocusDate({numberOfMonths: 1, today: TODAY, ...options}),
21
+ );
22
+ }
23
+
24
+ describe('getInitialFocusDate', () => {
25
+ it('opens on today when there are no bounds', () => {
26
+ expect(focusISO({})).toBe('2026-08-21');
27
+ });
28
+
29
+ it('opens on today when today is inside the min/max window', () => {
30
+ expect(focusISO({min: '2026-01-01', max: '2026-12-31'})).toBe('2026-08-21');
31
+ });
32
+
33
+ it('treats the bounds as inclusive', () => {
34
+ expect(focusISO({min: '2026-08-21'})).toBe('2026-08-21');
35
+ expect(focusISO({max: '2026-08-21'})).toBe('2026-08-21');
36
+ });
37
+
38
+ it('opens on min when the whole window is in the future', () => {
39
+ expect(focusISO({min: '2027-03-04', max: '2027-06-30'})).toBe('2027-03-04');
40
+ });
41
+
42
+ it('opens on max when the whole window is in the past', () => {
43
+ expect(focusISO({min: '2019-01-01', max: '2019-04-30'})).toBe('2019-04-01');
44
+ });
45
+
46
+ it('clamps against a one-sided min', () => {
47
+ expect(focusISO({min: '2030-05-17'})).toBe('2030-05-17');
48
+ });
49
+
50
+ it('clamps against a one-sided max', () => {
51
+ expect(focusISO({max: '2020-02-09'})).toBe('2020-02-01');
52
+ });
53
+
54
+ it('lands max in the last pane in the two-month layout', () => {
55
+ // Opening on max's month would spend the second pane entirely
56
+ // out of bounds, so the window's end sits on the right instead.
57
+ expect(focusISO({max: '2020-02-09', numberOfMonths: 2})).toBe('2020-01-01');
58
+ });
59
+
60
+ it('does not shift the two-month layout back past min', () => {
61
+ expect(
62
+ focusISO({min: '2020-02-03', max: '2020-02-09', numberOfMonths: 2}),
63
+ ).toBe('2020-02-03');
64
+ });
65
+
66
+ it('prefers the selected value over the bounds', () => {
67
+ expect(focusISO({value: '2031-07-04', min: '2019-01-01'})).toBe(
68
+ '2031-07-04',
69
+ );
70
+ });
71
+
72
+ it('uses a range value start as the visible month', () => {
73
+ expect(focusISO({value: {start: '2019-03-08', end: '2019-03-19'}})).toBe(
74
+ '2019-03-08',
75
+ );
76
+ });
77
+
78
+ it('prefers an explicit focusDate over everything else', () => {
79
+ expect(
80
+ focusISO({
81
+ focusDate: '2015-11-02',
82
+ value: '2031-07-04',
83
+ min: '2026-01-01',
84
+ max: '2026-12-31',
85
+ }),
86
+ ).toBe('2015-11-02');
87
+ });
88
+
89
+ it('prefers min when the bounds are inverted', () => {
90
+ // Degenerate input (min after max) — resolve it deterministically
91
+ // rather than reading the second bound off a contradiction.
92
+ expect(focusISO({min: '2027-01-01', max: '2020-01-01'})).toBe('2027-01-01');
93
+ });
94
+ });
@@ -0,0 +1,93 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file getInitialFocusDate.ts
5
+ * @input PlainDate utilities, min/max bounds, today
6
+ * @output Exports getInitialFocusDate — the month Calendar opens on
7
+ * @position Calendar-specific helper; used by Calendar.tsx
8
+ *
9
+ * SYNC: When modified, update:
10
+ * - /packages/core/src/Calendar/getInitialFocusDate.test.ts
11
+ * - /packages/core/src/Calendar/Calendar.tsx (the only caller)
12
+ */
13
+
14
+ import type {ISODateString, DateRange} from '../utils/dateTypes';
15
+ import {
16
+ type PlainDate,
17
+ plainDateFromISO,
18
+ plainDateSetFirstOfMonth,
19
+ plainDateAddMonths,
20
+ plainDateIsBefore,
21
+ plainDateIsAfter,
22
+ } from '../utils/plainDate';
23
+
24
+ export interface InitialFocusDateOptions {
25
+ /** Controlled visible month, if the consumer supplied one. */
26
+ focusDate?: ISODateString;
27
+ /** Selected value (single date or range), controlled or uncontrolled. */
28
+ value?: ISODateString | DateRange;
29
+ /** Earliest selectable date. */
30
+ min?: ISODateString;
31
+ /** Latest selectable date. */
32
+ max?: ISODateString;
33
+ /** How many month panes the calendar renders (1 or 2). */
34
+ numberOfMonths: number;
35
+ /** Today, injected so the caller keeps a single memoized source of "now". */
36
+ today: PlainDate;
37
+ }
38
+
39
+ /**
40
+ * Picks the date whose month the calendar opens on.
41
+ *
42
+ * An explicit `focusDate` wins, then the selected value — both are the
43
+ * consumer's own instruction about where to look, so neither is second-guessed
44
+ * against `min`/`max`.
45
+ *
46
+ * Otherwise the calendar opens on today, clamped into the `min`/`max` window.
47
+ * Without the clamp a window that doesn't contain today (a 2019 audit range, a
48
+ * booking window opening next spring) opened on today's month with every day
49
+ * disabled, leaving prev/next clicking as the only way in.
50
+ *
51
+ * When clamping forward to `min`, that month leads: the whole selectable window
52
+ * runs ahead of it. When clamping back to `max`, the last pane lands on `max`'s
53
+ * month instead — with `numberOfMonths={2}` opening on `[max, max + 1]` would
54
+ * spend half the calendar on a month that is entirely out of bounds. That
55
+ * shift never crosses `min`'s month.
56
+ */
57
+ export function getInitialFocusDate(
58
+ options: InitialFocusDateOptions,
59
+ ): PlainDate {
60
+ const {focusDate, value, min, max, numberOfMonths, today} = options;
61
+
62
+ if (focusDate) {
63
+ return plainDateFromISO(focusDate);
64
+ }
65
+
66
+ if (value) {
67
+ return plainDateFromISO(typeof value === 'string' ? value : value.start);
68
+ }
69
+
70
+ const minDate = min ? plainDateFromISO(min) : null;
71
+ const maxDate = max ? plainDateFromISO(max) : null;
72
+
73
+ if (minDate && plainDateIsBefore(today, minDate)) {
74
+ return minDate;
75
+ }
76
+
77
+ if (maxDate && plainDateIsAfter(today, maxDate)) {
78
+ const lastPaneOffset = Math.max(0, numberOfMonths - 1);
79
+ const shifted = plainDateAddMonths(
80
+ plainDateSetFirstOfMonth(maxDate),
81
+ -lastPaneOffset,
82
+ );
83
+ if (
84
+ minDate &&
85
+ plainDateIsBefore(shifted, plainDateSetFirstOfMonth(minDate))
86
+ ) {
87
+ return minDate;
88
+ }
89
+ return shifted;
90
+ }
91
+
92
+ return today;
93
+ }
@@ -7,7 +7,7 @@ export const docs = {
7
7
  subComponentOf: 'Chat',
8
8
  displayName: 'Chat Message List',
9
9
  isHiddenFromOverview: true,
10
- description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,
10
+ description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full; set align="top" to start messages at the top instead.`,
11
11
  props: [
12
12
  {
13
13
  name: 'children',
@@ -45,6 +45,12 @@ export const docs = {
45
45
  type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
46
46
  description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
47
47
  },
48
+ {
49
+ name: 'align',
50
+ type: "'top' | 'bottom'",
51
+ description: "Vertical alignment when the list is shorter than its container. 'bottom' fills free space with a spacer so short conversations sit above the composer; 'top' omits the spacer so messages start at the top. Only affects a non-full list; overflowing lists scroll identically, preserving auto-scroll-to-bottom.",
52
+ default: "'bottom'",
53
+ },
48
54
  {
49
55
  name: 'isStreaming',
50
56
  type: 'boolean',
@@ -65,6 +71,7 @@ export const docsZh = {
65
71
  scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
66
72
  density: '视觉密度,通过上下文传递给子消息。',
67
73
  gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
74
+ align: "列表内容不足一屏时的垂直对齐方式。'bottom' 用占位块填满剩余空间,让简短对话贴近输入框;'top' 省略占位块,让消息从顶部开始。仅影响未填满的列表,溢出后两种模式滚动一致,保持自动滚动到底部。",
68
75
  isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy,让屏幕阅读器等待并在完成后一次性播报,而不是每个 token 都重复播报。',
69
76
  },
70
77
  };
@@ -80,6 +87,7 @@ export const docsDense = {
80
87
  scrollToTopAction: 'async action at scroll top; load older msgs',
81
88
  density: 'visual density; flows to children via context',
82
89
  gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
90
+ align: "'top'|'bottom' (def bottom); bottom spacer pushes short lists down, top starts at top; overflow scrolls same either way",
83
91
  isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
84
92
  },
85
93
  };
@@ -83,4 +83,50 @@ describe('ChatMessageList', () => {
83
83
  );
84
84
  expect(screen.getByTestId('chat-list')).toBeTruthy();
85
85
  });
86
+
87
+ // With no scrollToTopAction the spacer is the only aria-hidden element in
88
+ // the list, so its presence maps 1:1 to the aria-hidden count.
89
+ it('renders the bottom spacer by default', () => {
90
+ render(
91
+ <ChatMessageList data-testid="list">
92
+ <div>msg</div>
93
+ </ChatMessageList>,
94
+ );
95
+ expect(
96
+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
97
+ ).toHaveLength(1);
98
+ });
99
+
100
+ it('renders the bottom spacer when align="bottom"', () => {
101
+ render(
102
+ <ChatMessageList align="bottom" data-testid="list">
103
+ <div>msg</div>
104
+ </ChatMessageList>,
105
+ );
106
+ expect(
107
+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
108
+ ).toHaveLength(1);
109
+ });
110
+
111
+ it('omits the spacer when align="top"', () => {
112
+ render(
113
+ <ChatMessageList align="top" data-testid="list">
114
+ <div>msg</div>
115
+ </ChatMessageList>,
116
+ );
117
+ expect(
118
+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
119
+ ).toHaveLength(0);
120
+ });
121
+
122
+ it('still renders children when align="top"', () => {
123
+ render(
124
+ <ChatMessageList align="top">
125
+ <ChatMessage sender="assistant">
126
+ <ChatMessageBubble>Hello</ChatMessageBubble>
127
+ </ChatMessage>
128
+ </ChatMessageList>,
129
+ );
130
+ expect(screen.getByText('Hello')).toBeTruthy();
131
+ });
86
132
  });
@@ -10,7 +10,8 @@
10
10
  *
11
11
  * Renders a container with role="log" for chat message histories.
12
12
  * Handles density context, configurable gap, empty state,
13
- * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
13
+ * a configurable spacer (align) that pushes messages to the bottom,
14
+ * and an infinite scroll sentinel.
14
15
  *
15
16
  * Auto-scroll and the scroll-to-bottom button are owned by
16
17
  * ChatLayout. When used standalone (without a layout), the list
@@ -73,6 +74,24 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {
73
74
  */
74
75
  gap?: SpacingStep;
75
76
 
77
+ /**
78
+ * Vertical alignment of messages when the list is shorter than its
79
+ * container.
80
+ *
81
+ * - `'bottom'` (default): a spacer fills the free space and pushes
82
+ * messages to the bottom, so a short conversation sits just above the
83
+ * composer — the familiar messaging-app layout.
84
+ * - `'top'`: the spacer is omitted, so messages start at the top and grow
85
+ * downward — better for document-style or log-style lists.
86
+ *
87
+ * This only changes the resting position of a non-full list. Once messages
88
+ * overflow the container the spacer collapses to zero in both modes, so
89
+ * ChatLayout auto-scroll-to-bottom behavior is identical either way.
90
+ *
91
+ * @default 'bottom'
92
+ */
93
+ align?: 'top' | 'bottom';
94
+
76
95
  /**
77
96
  * Whether an assistant message is actively streaming into the list.
78
97
  *
@@ -183,7 +202,8 @@ const gapStyles = stylex.create({
183
202
  *
184
203
  * Renders messages in a flex column with density-based spacing.
185
204
  * Override gap to tune row spacing separately from density.
186
- * A spacer pushes content to the bottom when the list isn't full.
205
+ * By default a spacer pushes content to the bottom when the list isn't full;
206
+ * set `align='top'` to start messages at the top instead.
187
207
  * Supports loading older messages via `scrollToTopAction`.
188
208
  *
189
209
  * Auto-scroll and the scroll-to-bottom button are owned by
@@ -204,6 +224,7 @@ export function ChatMessageList({
204
224
  scrollToTopAction,
205
225
  density = 'balanced',
206
226
  gap,
227
+ align = 'bottom',
207
228
  isStreaming = false,
208
229
  xstyle,
209
230
  className,
@@ -291,8 +312,11 @@ export function ChatMessageList({
291
312
  </div>
292
313
  )}
293
314
 
294
- {/* Spacer pushes messages to bottom when list isn't full */}
295
- <div {...stylex.props(styles.spacer)} aria-hidden />
315
+ {/* Spacer pushes messages to bottom when the list isn't full.
316
+ Omitted for top alignment so messages start at the top. */}
317
+ {align === 'bottom' && (
318
+ <div {...stylex.props(styles.spacer)} aria-hidden />
319
+ )}
296
320
 
297
321
  {/* Messages or empty state */}
298
322
  {hasChildren ? (
@@ -95,6 +95,12 @@ export const docs = {
95
95
  type: 'SyntaxThemeDefinition',
96
96
  description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
97
97
  },
98
+ {
99
+ name: 'highlightMode',
100
+ type: "'auto' | 'ranges' | 'spans'",
101
+ description: 'Syntax highlighting rendering mode.',
102
+ default: "'auto'",
103
+ },
98
104
  {
99
105
  name: 'isCollapsible',
100
106
  type: 'boolean',
@@ -58,6 +58,11 @@ export const docs = {
58
58
  description: 'Accessible name for the menu surface, announced when it opens.',
59
59
  default: "'Context menu'",
60
60
  },
61
+ {
62
+ name: 'onOpenChange',
63
+ type: '(isOpen: boolean) => void',
64
+ description: 'Callback fired when the menu opens or closes.',
65
+ },
61
66
  {
62
67
  name: 'isDisabled',
63
68
  type: 'boolean',
@@ -419,6 +419,42 @@ describe('DateInput — field parity', () => {
419
419
  expect(onChange).toHaveBeenCalledWith(undefined);
420
420
  });
421
421
 
422
+ it('returns focus to the field without letting the page scroll', async () => {
423
+ // Clearing unmounts the clear button, and focusing another element in the
424
+ // same task as that unmount makes iOS Safari scroll the document to the
425
+ // top. Measured on the iOS 26 simulator against the live docsite, field at
426
+ // scrollY 2055: synchronous focus lands at 0, deferred focus stays at
427
+ // 2055. `preventScroll` alone does not fix it, so both halves are
428
+ // asserted: the focus is deferred past the unmount, and it is passed
429
+ // preventScroll. jsdom implements no scrolling, so the guard is asserted
430
+ // at the call.
431
+ vi.useFakeTimers();
432
+ try {
433
+ render(
434
+ <DateInput
435
+ label="Ship date"
436
+ value="2026-03-21"
437
+ hasClear
438
+ onChange={() => {}}
439
+ />,
440
+ );
441
+ const input = field();
442
+ const focus = vi.spyOn(input, 'focus');
443
+
444
+ fireEvent.click(screen.getByRole('button', {name: /Clear Ship date/}));
445
+
446
+ // Not synchronous — that is the whole point.
447
+ expect(focus).not.toHaveBeenCalled();
448
+
449
+ vi.runAllTimers();
450
+
451
+ expect(focus).toHaveBeenCalledWith({preventScroll: true});
452
+ focus.mockRestore();
453
+ } finally {
454
+ vi.useRealTimers();
455
+ }
456
+ });
457
+
422
458
  it('does not open the picker until the field is tapped', () => {
423
459
  withLayout(() => {
424
460
  render(<DateInput label="Ship date" onChange={() => {}} />);
@@ -599,6 +599,16 @@ export function TouchDateField({
599
599
  const [isSheetOpen, setIsSheetOpen] = useState(false);
600
600
  const [isWheelOpen, setIsWheelOpen] = useState(false);
601
601
  const scrollerHandleRef = useRef<MonthScrollerHandle | null>(null);
602
+ // Pending focus handoff from the clear button; see handleClear.
603
+ const clearFocusTimerRef = useRef<number | null>(null);
604
+ useEffect(
605
+ () => () => {
606
+ if (clearFocusTimerRef.current != null) {
607
+ clearTimeout(clearFocusTimerRef.current);
608
+ }
609
+ },
610
+ [],
611
+ );
602
612
 
603
613
  const today = useMemo(() => plainDateToday(), []);
604
614
  const selectedDate = useMemo(
@@ -708,7 +718,31 @@ export function TouchDateField({
708
718
 
709
719
  const handleClear = useCallback(() => {
710
720
  fireChange(undefined);
711
- inputRef.current?.focus();
721
+ // Focus goes back to the field on the NEXT task, not synchronously.
722
+ //
723
+ // Clearing unmounts this button (it only renders while there is a value),
724
+ // and focusing another element in the same task as that unmount makes iOS
725
+ // Safari scroll the whole document to the top — the user is thrown from
726
+ // wherever the field sat to the start of the page. Measured on the iOS 26
727
+ // simulator against the live docsite, field at scrollY 2055: synchronous
728
+ // focus lands at 0, deferred focus stays at 2055.
729
+ //
730
+ // `preventScroll` alone does NOT fix it (verified: still 0) — this is not
731
+ // the browser's ordinary scroll-the-focused-element-into-view step, so the
732
+ // deferral is the load-bearing half. It is kept because the reveal scroll
733
+ // is real too, and unwanted for the same reason: the field the user just
734
+ // tapped is already on screen (+12px on a plain page without it).
735
+ //
736
+ // Skipping the focus entirely would also stop the scroll, but then focus
737
+ // dies with the unmounting button and lands on <body>.
738
+ const field = inputRef.current;
739
+ if (field == null) {
740
+ return;
741
+ }
742
+ clearFocusTimerRef.current = window.setTimeout(() => {
743
+ clearFocusTimerRef.current = null;
744
+ field.focus({preventScroll: true});
745
+ }, 0);
712
746
  }, [fireChange]);
713
747
 
714
748
  /**
@@ -62,14 +62,14 @@ export const docs = {
62
62
  {
63
63
  name: 'width',
64
64
  type: 'number | string',
65
- description: 'Width of the dialog in pixels or any CSS value.',
65
+ description: 'Preferred width of the dialog in pixels or any CSS value. Standard dialogs clamp to their container and the dynamic viewport with spacing-token gutters so narrow viewports keep content on screen.',
66
66
  default: '400',
67
67
  },
68
68
  {
69
69
  name: 'maxHeight',
70
70
  type: 'number | string',
71
- description: 'Maximum height of the dialog.',
72
- default: "'75vh'",
71
+ description: 'Maximum height of the dialog. Defaults to a dynamic viewport value so browser UI changes are reflected where supported.',
72
+ default: "'75dvh'",
73
73
  },
74
74
  {
75
75
  name: 'position',
@@ -90,6 +90,11 @@ export const docs = {
90
90
  description: 'Controls dismissal behavior: required disables Escape and backdrop click; form disables backdrop click after interaction; info allows both.',
91
91
  default: "'info'",
92
92
  },
93
+ {
94
+ name: 'padding',
95
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
96
+ description: 'Internal padding of the dialog using the spacing scale step.',
97
+ },
93
98
  {
94
99
  name: 'isInline',
95
100
  type: 'boolean',