@gntik-ai/blocks 0.8.0 → 0.10.0

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 (77) hide show
  1. package/dist/index.d.ts +138 -21
  2. package/dist/index.js +897 -376
  3. package/dist/index.js.map +1 -1
  4. package/package.json +3 -3
  5. package/src/billing/CostBreakdown/CostBreakdown.test.tsx +10 -0
  6. package/src/billing/CostBreakdown/CostBreakdown.tsx +50 -43
  7. package/src/billing/SpendVsBudget/SpendVsBudget.test.tsx +10 -0
  8. package/src/billing/SpendVsBudget/SpendVsBudget.tsx +35 -31
  9. package/src/builders/FlowBuilder/FlowBuilder.test.tsx +237 -2
  10. package/src/builders/FlowBuilder/FlowBuilder.tsx +101 -29
  11. package/src/builders/FlowBuilder/block.meta.ts +1 -1
  12. package/src/builders/FlowBuilder/connections.ts +30 -12
  13. package/src/builders/FlowBuilder/examples/ControlledGraph.tsx +8 -0
  14. package/src/builders/FlowBuilder/graph-state.ts +78 -0
  15. package/src/builders/LogViewer/LogViewer.labels.test.tsx +90 -0
  16. package/src/builders/LogViewer/LogViewer.test.tsx +11 -0
  17. package/src/builders/LogViewer/LogViewer.tsx +70 -31
  18. package/src/builders/LogViewer/block.meta.ts +14 -1
  19. package/src/builders/LogViewer/examples/Spanish.tsx +30 -0
  20. package/src/data-display/ChartCard/ChartCard.locale.test.tsx +15 -0
  21. package/src/data-display/ChartCard/ChartCard.test.tsx +9 -0
  22. package/src/data-display/ChartCard/ChartCard.tsx +81 -67
  23. package/src/data-display/ChartCard/block.meta.ts +1 -1
  24. package/src/data-display/DescriptionListCard/DescriptionListCard.labels.test.tsx +73 -0
  25. package/src/data-display/DescriptionListCard/DescriptionListCard.tsx +37 -7
  26. package/src/data-display/DescriptionListCard/block.meta.ts +11 -1
  27. package/src/data-display/DescriptionListCard/examples/Spanish.tsx +22 -0
  28. package/src/feedback/EmptyStates/EmptyStates.labels.test.tsx +185 -0
  29. package/src/feedback/EmptyStates/EmptyStates.tsx +73 -20
  30. package/src/feedback/EmptyStates/block.meta.ts +73 -1
  31. package/src/feedback/EmptyStates/examples/Spanish.tsx +41 -0
  32. package/src/feedback/ErrorPanel/ErrorPanel.labels.test.tsx +99 -0
  33. package/src/feedback/ErrorPanel/ErrorPanel.tsx +38 -9
  34. package/src/feedback/ErrorPanel/block.meta.ts +19 -1
  35. package/src/feedback/ErrorPanel/examples/Spanish.tsx +30 -0
  36. package/src/feedback/InlineCallout/InlineCallout.labels.test.tsx +62 -0
  37. package/src/feedback/InlineCallout/InlineCallout.tsx +22 -9
  38. package/src/feedback/InlineCallout/block.meta.ts +9 -1
  39. package/src/feedback/InlineCallout/examples/Spanish.tsx +19 -0
  40. package/src/feedback/Skeletons/Skeletons.labels.test.tsx +24 -0
  41. package/src/forms/FileUploadPanel/FileUploadPanel.test.tsx +22 -1
  42. package/src/forms/FileUploadPanel/FileUploadPanel.tsx +4 -4
  43. package/src/forms/FileUploadPanel/fixtures.ts +0 -12
  44. package/src/forms/FileUploadPanel/format-bytes.test.ts +8 -0
  45. package/src/page-chrome/PageHeader/PageHeader.labels.test.tsx +56 -0
  46. package/src/page-chrome/PageHeader/PageHeader.test.tsx +18 -0
  47. package/src/page-chrome/PageHeader/PageHeader.tsx +21 -4
  48. package/src/page-chrome/PageHeader/block.meta.ts +8 -1
  49. package/src/page-chrome/PageHeader/examples/Labels.tsx +16 -0
  50. package/src/page-chrome/PageHeader/examples/Spanish.tsx +11 -0
  51. package/src/scheduling/AgendaList/AgendaList.test.tsx +25 -0
  52. package/src/scheduling/AgendaList/AgendaList.tsx +7 -2
  53. package/src/scheduling/AgendaList/AgendaListLocale.test.tsx +11 -0
  54. package/src/scheduling/AgendaList/block.meta.ts +1 -1
  55. package/src/scheduling/AgendaList/examples/Locale.tsx +29 -0
  56. package/src/scheduling/MonthCalendar/MonthCalendar.test.tsx +111 -1
  57. package/src/scheduling/MonthCalendar/MonthCalendar.tsx +19 -9
  58. package/src/scheduling/MonthCalendar/block.meta.ts +1 -1
  59. package/src/scheduling/MonthCalendar/examples/Locale.tsx +19 -0
  60. package/src/scheduling/WeekCalendar/WeekCalendar.test.tsx +73 -2
  61. package/src/scheduling/WeekCalendar/WeekCalendar.tsx +26 -12
  62. package/src/scheduling/WeekCalendar/block.meta.ts +1 -1
  63. package/src/scheduling/WeekCalendar/examples/Locale.tsx +19 -0
  64. package/src/scheduling/shared/dates.test.ts +75 -0
  65. package/src/scheduling/shared/dates.ts +46 -22
  66. package/src/scheduling/shared/useSchedulingClock.ts +13 -0
  67. package/src/shell/GlobalSearch/GlobalSearch.test.tsx +12 -0
  68. package/src/shell/GlobalSearch/fixtures.ts +2 -2
  69. package/src/tables/DataTable/DataTable.labels.test.tsx +2 -0
  70. package/src/tables/DataTable/DataTable.locale.test.tsx +153 -0
  71. package/src/tables/DataTable/DataTable.server-pagination.test.tsx +1 -1
  72. package/src/tables/DataTable/DataTable.test.tsx +16 -0
  73. package/src/tables/DataTable/block.meta.ts +2 -0
  74. package/src/tables/DataTable/data-table-row.tsx +18 -2
  75. package/src/tables/DataTable/data-table-utils.ts +18 -4
  76. package/src/tables/DataTable/labels.ts +2 -0
  77. package/src/tables/PaginationFooter/PaginationFooter.i18n.test.tsx +26 -0
@@ -0,0 +1,11 @@
1
+ import { I18nProvider } from '@gntik-ai/ui';
2
+ import { PageHeader } from '../PageHeader';
3
+
4
+ /** Caller-supplied content is unchanged; the tablist name follows the active catalog. */
5
+ export default function Spanish() {
6
+ return (
7
+ <I18nProvider locale="es">
8
+ <PageHeader />
9
+ </I18nProvider>
10
+ );
11
+ }
@@ -1,3 +1,4 @@
1
+ import { I18nProvider } from '@gntik-ai/ui';
1
2
  import { render, screen, within } from '@testing-library/react';
2
3
  import userEvent from '@testing-library/user-event';
3
4
  import { expectNoAxeViolations } from '../../test/a11y';
@@ -26,3 +27,27 @@ describe('AgendaList', () => {
26
27
  expect(screen.getByRole('heading', { name: 'Nothing scheduled' })).toBeInTheDocument();
27
28
  });
28
29
  });
30
+
31
+ it.each([
32
+ ['en-US', undefined, '9:30 AM–10:00 AM'],
33
+ ['es-ES', undefined, '09:30–10:00'],
34
+ ['en-US', 'h23', '09:30–10:00'],
35
+ ] as const)('formats agenda ranges for %s with override %s', (locale, hourCycle, expected) => {
36
+ render(
37
+ <I18nProvider locale={locale}>
38
+ <AgendaList
39
+ hourCycle={hourCycle}
40
+ events={[
41
+ {
42
+ id: 'clock',
43
+ title: 'Review',
44
+ kind: 'task',
45
+ start: new Date(2026, 3, 15, 9, 30),
46
+ end: new Date(2026, 3, 15, 10),
47
+ },
48
+ ]}
49
+ />
50
+ </I18nProvider>,
51
+ );
52
+ expect(screen.getByText(expected)).toBeInTheDocument();
53
+ });
@@ -1,13 +1,16 @@
1
1
  import { useId, useMemo } from 'react';
2
2
  import { Badge, EmptyState, cn, useI18n } from '@gntik-ai/ui';
3
3
  import { CalendarDays, ChevronRight, Clock } from '@gntik-ai/icons';
4
+ import { useSchedulingClock } from '../shared/useSchedulingClock';
4
5
  import { EventTile } from '../shared/EventTile';
5
- import { addDays, dayKey, formatDay, formatRange, sameDay } from '../shared/dates';
6
+ import { addDays, dayKey, formatDay, formatRange, sameDay, type HourCycle } from '../shared/dates';
6
7
  import { defaultEventKinds, groupByDay, kindOf, TONE, type EventKind, type ScheduleEvent } from '../shared/events';
7
8
  import { sampleEvents, sampleToday } from '../shared/fixtures';
8
9
 
9
10
  export interface AgendaListProps {
10
11
  events?: ScheduleEvent[];
12
+ /** Clock used for event ranges; defaults to the provider or runtime locale. */
13
+ hourCycle?: HourCycle;
11
14
  /** The app's "today": labels the Today/Tomorrow groups. */
12
15
  today?: Date;
13
16
  /** Only events on or after this day. Defaults to `today`; pass null for all. */
@@ -30,6 +33,7 @@ export interface AgendaListProps {
30
33
  /** Upcoming scheduled work grouped by day, each row with a kind tile, time range and location. */
31
34
  export function AgendaList({
32
35
  events = sampleEvents,
36
+ hourCycle: hourCycleProp,
33
37
  today = sampleToday,
34
38
  from,
35
39
  days = 7,
@@ -43,6 +47,7 @@ export function AgendaList({
43
47
  className,
44
48
  }: AgendaListProps) {
45
49
  const { t, locale } = useI18n();
50
+ const clock = useSchedulingClock(hourCycleProp);
46
51
  const title = titleProp ?? t('calendar.agenda');
47
52
  const emptyTitle = emptyTitleProp ?? t('calendar.emptyTitle');
48
53
  const emptyDescription = emptyDescriptionProp ?? t('calendar.emptyDescription');
@@ -105,7 +110,7 @@ export function AgendaList({
105
110
  >
106
111
  {list.map((event) => {
107
112
  const kind = kindOf(event, kinds);
108
- const range = formatRange(event.start, event.end, locale);
113
+ const range = formatRange(event.start, event.end, clock.locale, clock.hourCycle);
109
114
  const content = (
110
115
  <>
111
116
  <EventTile kind={kind} />
@@ -0,0 +1,11 @@
1
+ import { render, screen } from '@testing-library/react';
2
+ import { expectNoAxeViolations } from '../../test/a11y';
3
+ import Locale from './examples/Locale';
4
+
5
+ it('gives each agenda locale example a distinct landmark name', async () => {
6
+ const { container } = render(<Locale />);
7
+ expect(screen.getByRole('region', { name: 'Agenda (en-US)' })).toBeInTheDocument();
8
+ expect(screen.getByRole('region', { name: 'Agenda (es-ES)' })).toBeInTheDocument();
9
+ expect(screen.getByRole('region', { name: 'Agenda (en-US, h23)' })).toBeInTheDocument();
10
+ await expectNoAxeViolations(container);
11
+ });
@@ -5,6 +5,6 @@ export const meta: BlockMeta = {
5
5
  family: 'scheduling',
6
6
  status: 'beta',
7
7
  description:
8
- 'Upcoming scheduled work grouped by day (Today/Tomorrow labels), each row with a kind tile, time range, location and kind badge; empty state included.',
8
+ 'Upcoming scheduled work grouped by day (Today/Tomorrow labels), each row with a kind tile, locale-formatted time range, location and kind badge; empty state included. hourCycle overrides the provider/runtime clock. Locale examples show en-US, es-ES, then en-US with the 24-hour override.',
9
9
  uses: ['Badge', 'EmptyState'],
10
10
  };
@@ -0,0 +1,29 @@
1
+ import { I18nProvider, useI18n } from '@gntik-ai/ui';
2
+ import { AgendaList } from '../AgendaList';
3
+
4
+ function LocaleAgenda({ hourCycle }: { hourCycle?: 'h23' }) {
5
+ const { locale, t } = useI18n();
6
+ return (
7
+ <AgendaList
8
+ title={`${t('calendar.agenda')} (${locale}${hourCycle ? `, ${hourCycle}` : ''})`}
9
+ hourCycle={hourCycle}
10
+ />
11
+ );
12
+ }
13
+
14
+ /** Compare US defaults, Spanish defaults, and explicit overrides under US English. */
15
+ export default function Locale() {
16
+ return (
17
+ <div className="space-y-6">
18
+ <I18nProvider locale="en-US">
19
+ <LocaleAgenda />
20
+ </I18nProvider>
21
+ <I18nProvider locale="es-ES">
22
+ <LocaleAgenda />
23
+ </I18nProvider>
24
+ <I18nProvider locale="en-US">
25
+ <LocaleAgenda hourCycle="h23" />
26
+ </I18nProvider>
27
+ </div>
28
+ );
29
+ }
@@ -1,4 +1,5 @@
1
- import { render, screen } from '@testing-library/react';
1
+ import { Calendar, I18nProvider, localeWeekStart } from '@gntik-ai/ui';
2
+ import { render, screen, within } from '@testing-library/react';
2
3
  import userEvent from '@testing-library/user-event';
3
4
  import { expectNoAxeViolations } from '../../test/a11y';
4
5
  import { MonthCalendar } from './MonthCalendar';
@@ -30,3 +31,112 @@ describe('MonthCalendar', () => {
30
31
  expect(screen.getByRole('heading', { name: 'April 2026' })).toBeInTheDocument();
31
32
  });
32
33
  });
34
+
35
+ it.each([
36
+ ['en-US', 'Sunday', '2026-03-29'],
37
+ ['es-ES', 'lunes', '2026-03-30'],
38
+ ])('starts the April grid with the locale weekday (%s)', (locale, header, firstDate) => {
39
+ const { container } = render(
40
+ <I18nProvider locale={locale}>
41
+ <MonthCalendar events={[]} today={new Date(2026, 3, 15)} />
42
+ </I18nProvider>,
43
+ );
44
+ expect(screen.getAllByRole('columnheader')[0]).toHaveAccessibleName(header);
45
+ expect(container.querySelector('[data-date]')).toHaveAttribute('data-date', firstDate);
46
+ });
47
+
48
+ it.each([
49
+ ['en-US', undefined, '9:30 AM'],
50
+ ['es-ES', undefined, '09:30'],
51
+ ['en-US', 'h23', '09:30'],
52
+ ] as const)('formats month event times for %s with override %s', (locale, hourCycle, expected) => {
53
+ render(
54
+ <I18nProvider locale={locale}>
55
+ <MonthCalendar
56
+ hourCycle={hourCycle}
57
+ events={[
58
+ {
59
+ id: 'clock',
60
+ title: 'Review',
61
+ kind: 'task',
62
+ start: new Date(2026, 3, 15, 9, 30),
63
+ end: new Date(2026, 3, 15, 10),
64
+ },
65
+ ]}
66
+ />
67
+ </I18nProvider>,
68
+ );
69
+ expect(screen.getByText(expected)).toBeInTheDocument();
70
+ });
71
+
72
+ it.each([
73
+ ['en-US', undefined, '2026-04-12', '2026-04-18'],
74
+ ['es-ES', undefined, '2026-04-13', '2026-04-19'],
75
+ ['en-US', 1, '2026-04-13', '2026-04-19'],
76
+ ] as const)('moves to week edges for %s with override %s', async (locale, weekStartsOn, home, end) => {
77
+ const user = userEvent.setup();
78
+ const { container } = render(
79
+ <I18nProvider locale={locale}>
80
+ <MonthCalendar events={[]} weekStartsOn={weekStartsOn} today={new Date(2026, 3, 15)} />
81
+ </I18nProvider>,
82
+ );
83
+ const day = (key: string) => container.querySelector<HTMLElement>(`[data-date="${key}"]`)!;
84
+ day('2026-04-15').focus();
85
+ await user.keyboard('{Home}');
86
+ expect(day(home)).toHaveFocus();
87
+ day('2026-04-15').focus();
88
+ await user.keyboard('{End}');
89
+ expect(day(end)).toHaveFocus();
90
+ if (weekStartsOn === 1) {
91
+ expect(screen.getAllByRole('columnheader')[0]).toHaveAccessibleName('Monday');
92
+ expect(container.querySelector('[data-date]')).toHaveAttribute('data-date', '2026-03-30');
93
+ }
94
+ });
95
+
96
+ it.each(['en-US', 'en-GB'])('matches the ui Calendar without a provider in a %s runtime', (runtimeLocale) => {
97
+ const NativeFormatter = Intl.DateTimeFormat;
98
+ vi.stubGlobal(
99
+ 'Intl',
100
+ Object.create(Intl, {
101
+ DateTimeFormat: {
102
+ value: class extends NativeFormatter {
103
+ constructor(locale?: Intl.LocalesArgument, options?: Intl.DateTimeFormatOptions) {
104
+ super(locale ?? runtimeLocale, options);
105
+ }
106
+ },
107
+ },
108
+ }),
109
+ );
110
+ try {
111
+ render(
112
+ <>
113
+ <MonthCalendar events={[]} />
114
+ <Calendar defaultMonth={new Date(2026, 3, 1)} />
115
+ </>,
116
+ );
117
+ const grids = screen.getAllByRole('grid');
118
+ const header = (grid: HTMLElement) => within(grid).getAllByRole('columnheader')[0]!;
119
+ const date = new Date(2026, 0, 4 + localeWeekStart(undefined));
120
+ expect(header(grids[0]!)).toHaveAccessibleName(new Intl.DateTimeFormat('en', { weekday: 'long' }).format(date));
121
+ expect(header(grids[1]!).querySelector('abbr')).toHaveAttribute(
122
+ 'title',
123
+ new Intl.DateTimeFormat(undefined, { weekday: 'long' }).format(date),
124
+ );
125
+ } finally {
126
+ vi.unstubAllGlobals();
127
+ }
128
+ });
129
+
130
+ it('marks only weekend cells', () => {
131
+ render(
132
+ <I18nProvider locale="en-US">
133
+ <MonthCalendar events={[]} />
134
+ </I18nProvider>,
135
+ );
136
+ const cells = screen.getAllByRole('gridcell');
137
+ expect(cells.filter((cell) => cell.hasAttribute('data-weekend'))).toHaveLength(12);
138
+ for (const cell of cells) {
139
+ const label = within(cell).getByRole('button').getAttribute('aria-label') ?? '';
140
+ expect(cell.hasAttribute('data-weekend')).toBe(/^(Saturday|Sunday),/.test(label));
141
+ }
142
+ });
@@ -1,7 +1,9 @@
1
1
  import { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
2
- import { cn, useI18n } from '@gntik-ai/ui';
2
+ import { cn, useI18n, localeWeekStart, type WeekDay } from '@gntik-ai/ui';
3
+ import { useSchedulingClock } from '../shared/useSchedulingClock';
3
4
  import { CalendarHeader } from '../shared/CalendarHeader';
4
5
  import {
6
+ type HourCycle,
5
7
  addDays,
6
8
  addMonths,
7
9
  dayKey,
@@ -10,6 +12,7 @@ import {
10
12
  formatTime,
11
13
  formatWeekday,
12
14
  monthGrid,
15
+ weekendDays,
13
16
  sameDay,
14
17
  sameMonth,
15
18
  startOfDay,
@@ -21,6 +24,10 @@ import { sampleEvents, sampleToday } from '../shared/fixtures';
21
24
 
22
25
  export interface MonthCalendarProps {
23
26
  events?: ScheduleEvent[];
27
+ /** Clock used for event times; defaults to the provider or runtime locale. */
28
+ hourCycle?: HourCycle;
29
+ /** First weekday; defaults to the provider or runtime locale. */
30
+ weekStartsOn?: WeekDay;
24
31
  /** The app's "today" (the block never reads the clock). */
25
32
  today?: Date;
26
33
  /** Month shown first (uncontrolled). Defaults to the month of `today`. */
@@ -39,16 +46,15 @@ export interface MonthCalendarProps {
39
46
  className?: string;
40
47
  }
41
48
 
42
- /** Monday-first weekdays (2026-01-05 is a Monday). */
43
- const WEEK = Array.from({ length: 7 }, (_, i) => new Date(2026, 0, 5 + i));
44
-
45
49
  /**
46
- * Month view of scheduled work: a Monday-first grid with up to N events per day.
50
+ * Month view of scheduled work: a locale-first grid with up to N events per day.
47
51
  * Keyboard: arrows move by day/week, Home/End to the week edges, PageUp/PageDown by month,
48
52
  * Enter/Space selects.
49
53
  */
50
54
  export function MonthCalendar({
51
55
  events = sampleEvents,
56
+ hourCycle: hourCycleProp,
57
+ weekStartsOn: weekStartsOnProp,
52
58
  today = sampleToday,
53
59
  defaultMonth,
54
60
  onMonthChange,
@@ -60,6 +66,8 @@ export function MonthCalendar({
60
66
  className,
61
67
  }: MonthCalendarProps) {
62
68
  const { t, locale, dir } = useI18n();
69
+ const clock = useSchedulingClock(hourCycleProp);
70
+ const weekStartsOn = weekStartsOnProp ?? localeWeekStart(clock.locale);
63
71
  const titleId = useId();
64
72
  const [selected, setSelected] = useState<Date>(() => startOfDay(defaultSelected ?? today));
65
73
  const [focused, setFocused] = useState<Date>(() => startOfDay(defaultSelected ?? defaultMonth ?? today));
@@ -67,7 +75,8 @@ export function MonthCalendar({
67
75
  const gridRef = useRef<HTMLDivElement>(null);
68
76
  const moveFocus = useRef(false);
69
77
  const byDay = useMemo(() => groupByDay(events), [events]);
70
- const weeks = monthGrid(month);
78
+ const weeks = monthGrid(month, weekStartsOn);
79
+ const weekend = weekendDays(clock.locale);
71
80
  // The roving tab stop stays inside the visible month.
72
81
  const tabStop = sameMonth(focused, month) ? focused : sameMonth(selected, month) ? selected : month;
73
82
 
@@ -96,7 +105,7 @@ export function MonthCalendar({
96
105
  };
97
106
 
98
107
  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, date: Date) => {
99
- const weekStart = startOfWeek(date);
108
+ const weekStart = startOfWeek(date, weekStartsOn);
100
109
  const map: Record<string, () => Date> = {
101
110
  ArrowLeft: () => addDays(date, dir === 'rtl' ? 1 : -1),
102
111
  ArrowRight: () => addDays(date, dir === 'rtl' ? -1 : 1),
@@ -130,7 +139,7 @@ export function MonthCalendar({
130
139
  />
131
140
  <div ref={gridRef} role="grid" aria-labelledby={titleId}>
132
141
  <div role="row" className="grid grid-cols-7 border-b border-border bg-secondary/30">
133
- {WEEK.map((day) => (
142
+ {(weeks[0] ?? []).map((day) => (
134
143
  <div
135
144
  key={day.getDay()}
136
145
  role="columnheader"
@@ -154,6 +163,7 @@ export function MonthCalendar({
154
163
  <div
155
164
  key={key}
156
165
  role="gridcell"
166
+ data-weekend={weekend.includes(date.getDay() as WeekDay) ? '' : undefined}
157
167
  aria-selected={isSelected}
158
168
  className="min-w-0 border-e border-b border-border/70 [&:nth-child(7)]:border-e-0"
159
169
  >
@@ -201,7 +211,7 @@ export function MonthCalendar({
201
211
  <span className={cn('size-1.5 shrink-0 rounded-full', TONE[kindOf(e, kinds).tone].dot)} />
202
212
  <span className="truncate text-[11px] text-foreground/80">{e.title}</span>
203
213
  <span className="ms-auto hidden shrink-0 font-mono text-[10px] text-muted-foreground xl:block">
204
- {formatTime(e.start, locale)}
214
+ {formatTime(e.start, clock.locale, clock.hourCycle)}
205
215
  </span>
206
216
  </span>
207
217
  ))}
@@ -5,6 +5,6 @@ export const meta: BlockMeta = {
5
5
  family: 'scheduling',
6
6
  status: 'beta',
7
7
  description:
8
- 'Monday-first month grid of scheduled work with per-day event lines, today/selected states, month navigation and full grid keyboard support.',
8
+ 'Locale-first month grid of scheduled work with per-day event lines, today/selected states, month navigation and full grid keyboard support. weekStartsOn and hourCycle override provider/runtime defaults; data-weekend marks locale weekends without styling. Locale examples show en-US, es-ES, then en-US with Monday-first and 24-hour overrides.',
9
9
  uses: ['Button', 'IconButton'],
10
10
  };
@@ -0,0 +1,19 @@
1
+ import { I18nProvider } from '@gntik-ai/ui';
2
+ import { MonthCalendar } from '../MonthCalendar';
3
+
4
+ /** Compare US defaults, Spanish defaults, and explicit overrides under US English. */
5
+ export default function Locale() {
6
+ return (
7
+ <div className="space-y-6">
8
+ <I18nProvider locale="en-US">
9
+ <MonthCalendar />
10
+ </I18nProvider>
11
+ <I18nProvider locale="es-ES">
12
+ <MonthCalendar />
13
+ </I18nProvider>
14
+ <I18nProvider locale="en-US">
15
+ <MonthCalendar weekStartsOn={1} hourCycle="h23" />
16
+ </I18nProvider>
17
+ </div>
18
+ );
19
+ }
@@ -1,3 +1,4 @@
1
+ import { I18nProvider } from '@gntik-ai/ui';
1
2
  import { render, screen, within } from '@testing-library/react';
2
3
  import userEvent from '@testing-library/user-event';
3
4
  import { expectNoAxeViolations } from '../../test/a11y';
@@ -5,7 +6,7 @@ import { WeekCalendar } from './WeekCalendar';
5
6
 
6
7
  describe('WeekCalendar', () => {
7
8
  it('renders the sample week with its events per day', async () => {
8
- const { container } = render(<WeekCalendar />);
9
+ const { container } = render(<WeekCalendar weekStartsOn={1} hourCycle="h23" />);
9
10
  expect(screen.getByRole('heading', { name: 'Apr 13 – 19, 2026' })).toBeInTheDocument();
10
11
  const wednesday = screen.getByRole('list', { name: 'Wednesday, April 15' });
11
12
  expect(within(wednesday).getAllByRole('listitem')).toHaveLength(9);
@@ -16,7 +17,7 @@ describe('WeekCalendar', () => {
16
17
  const user = userEvent.setup();
17
18
  const onEventClick = vi.fn();
18
19
  const onWeekChange = vi.fn();
19
- render(<WeekCalendar onEventClick={onEventClick} onWeekChange={onWeekChange} />);
20
+ render(<WeekCalendar weekStartsOn={1} hourCycle="h23" onEventClick={onEventClick} onWeekChange={onWeekChange} />);
20
21
  await user.click(screen.getByRole('button', { name: 'Checkout hotfix, 09:00–10:00, eu-west-1' }));
21
22
  expect(onEventClick).toHaveBeenCalledWith(expect.objectContaining({ title: 'Checkout hotfix' }));
22
23
  await user.click(screen.getByRole('button', { name: 'Next week' }));
@@ -25,3 +26,73 @@ describe('WeekCalendar', () => {
25
26
  await expectNoAxeViolations(document.body);
26
27
  });
27
28
  });
29
+
30
+ it.each([
31
+ ['en-US', undefined, 'Sunday, April 12', 12],
32
+ ['es-ES', undefined, 'lunes, 13 de abril', 13],
33
+ ['en-US', 1, 'Monday, April 13', 13],
34
+ ] as const)(
35
+ 'aligns initial week, navigation and Today for %s with override %s',
36
+ async (locale, weekStartsOn, firstLabel, day) => {
37
+ const user = userEvent.setup();
38
+ const onWeekChange = vi.fn();
39
+ render(
40
+ <I18nProvider locale={locale}>
41
+ <WeekCalendar
42
+ events={[]}
43
+ today={new Date(2026, 3, 15)}
44
+ weekStartsOn={weekStartsOn}
45
+ onWeekChange={onWeekChange}
46
+ />
47
+ </I18nProvider>,
48
+ );
49
+ expect(screen.getAllByRole('list')[0]).toHaveAccessibleName(firstLabel);
50
+ await user.click(screen.getByRole('button', { name: locale === 'es-ES' ? 'Semana siguiente' : 'Next week' }));
51
+ expect(onWeekChange).toHaveBeenLastCalledWith(new Date(2026, 3, day + 7));
52
+ await user.click(screen.getByRole('button', { name: locale === 'es-ES' ? 'Semana anterior' : 'Previous week' }));
53
+ expect(onWeekChange).toHaveBeenLastCalledWith(new Date(2026, 3, day));
54
+ await user.click(screen.getByRole('button', { name: locale === 'es-ES' ? 'Hoy' : 'Today' }));
55
+ expect(onWeekChange).toHaveBeenLastCalledWith(new Date(2026, 3, day));
56
+ },
57
+ );
58
+
59
+ it.each([
60
+ ['en-US', undefined, '9:30 AM–10:00 AM', '9 AM'],
61
+ ['es-ES', undefined, '09:30–10:00', '09:00'],
62
+ ['en-US', 'h23', '09:30–10:00', '09:00'],
63
+ ] as const)('formats event names and gutter labels for %s with override %s', (locale, hourCycle, range, hour) => {
64
+ render(
65
+ <I18nProvider locale={locale}>
66
+ <WeekCalendar
67
+ hourCycle={hourCycle}
68
+ onEventClick={() => {}}
69
+ events={[
70
+ {
71
+ id: 'clock',
72
+ title: 'Review',
73
+ kind: 'task',
74
+ start: new Date(2026, 3, 15, 9, 30),
75
+ end: new Date(2026, 3, 15, 10),
76
+ },
77
+ ]}
78
+ />
79
+ </I18nProvider>,
80
+ );
81
+ expect(screen.getByRole('button', { name: `Review, ${range}` })).toBeInTheDocument();
82
+ expect(screen.getByText(hour, { exact: true })).toBeInTheDocument();
83
+ });
84
+
85
+ it('marks Saturday and Sunday day columns only', () => {
86
+ render(
87
+ <I18nProvider locale="en-US">
88
+ <WeekCalendar events={[]} />
89
+ </I18nProvider>,
90
+ );
91
+ const columns = screen.getAllByRole('list');
92
+ expect(columns.filter((column) => column.hasAttribute('data-weekend'))).toHaveLength(2);
93
+ for (const column of columns) {
94
+ expect(column.hasAttribute('data-weekend')).toBe(
95
+ /^(Saturday|Sunday),/.test(column.getAttribute('aria-label') ?? ''),
96
+ );
97
+ }
98
+ });
@@ -1,7 +1,10 @@
1
1
  import { useEffect, useId, useMemo, useRef, useState, type ReactNode } from 'react';
2
- import { cn, useI18n } from '@gntik-ai/ui';
2
+ import { cn, useI18n, localeWeekStart, type WeekDay } from '@gntik-ai/ui';
3
+ import { useSchedulingClock } from '../shared/useSchedulingClock';
3
4
  import { CalendarHeader } from '../shared/CalendarHeader';
4
5
  import {
6
+ type HourCycle,
7
+ formatHour,
5
8
  addDays,
6
9
  dayKey,
7
10
  formatDay,
@@ -13,19 +16,24 @@ import {
13
16
  sameDay,
14
17
  startOfWeek,
15
18
  weekDays,
19
+ weekendDays,
16
20
  } from '../shared/dates';
17
21
  import { defaultEventKinds, groupByDay, kindOf, TONE, type EventKind, type ScheduleEvent } from '../shared/events';
18
22
  import { sampleEvents, sampleToday } from '../shared/fixtures';
19
23
 
20
24
  export interface WeekCalendarProps {
21
25
  events?: ScheduleEvent[];
26
+ /** First weekday; defaults to the provider or runtime locale. */
27
+ weekStartsOn?: WeekDay;
28
+ /** Clock used for events and hour labels; defaults to the provider or runtime locale. */
29
+ hourCycle?: HourCycle;
22
30
  /** The app's "today" (the block never reads the clock). */
23
31
  today?: Date;
24
32
  /** Current time for the "now" line, shown when it falls in the visible week. Defaults to `today`. */
25
33
  now?: Date;
26
34
  /** A date inside the week shown first (uncontrolled). Defaults to `today`. */
27
35
  defaultWeek?: Date;
28
- /** Called with the Monday of the newly shown week. */
36
+ /** Called with the first day of the newly shown week. */
29
37
  onWeekChange?: (weekStart: Date) => void;
30
38
  /** Makes events buttons. */
31
39
  onEventClick?: (event: ScheduleEvent) => void;
@@ -41,7 +49,6 @@ export interface WeekCalendarProps {
41
49
  }
42
50
 
43
51
  const HOURS = Array.from({ length: 24 }, (_, h) => h);
44
- const pad = (n: number) => String(n).padStart(2, '0');
45
52
 
46
53
  interface Placed {
47
54
  event: ScheduleEvent;
@@ -89,6 +96,8 @@ function layoutDay(list: readonly ScheduleEvent[], hourHeight: number): Placed[]
89
96
  /** Week view: seven day columns over a scrolling 24-hour time grid, with a "now" line. */
90
97
  export function WeekCalendar({
91
98
  events = sampleEvents,
99
+ weekStartsOn: weekStartsOnProp,
100
+ hourCycle: hourCycleProp,
92
101
  today = sampleToday,
93
102
  now,
94
103
  defaultWeek,
@@ -102,11 +111,15 @@ export function WeekCalendar({
102
111
  className,
103
112
  }: WeekCalendarProps) {
104
113
  const { t, locale } = useI18n();
114
+ const clock = useSchedulingClock(hourCycleProp);
115
+ const weekStartsOn = weekStartsOnProp ?? localeWeekStart(clock.locale);
105
116
  const titleId = useId();
106
- const [weekStart, setWeekStart] = useState<Date>(() => startOfWeek(defaultWeek ?? today));
117
+ const [weekStart, setWeekStart] = useState<Date>(() => startOfWeek(defaultWeek ?? today, weekStartsOn));
107
118
  const scrollRef = useRef<HTMLDivElement>(null);
108
119
  const byDay = useMemo(() => groupByDay(events), [events]);
109
- const days = weekDays(weekStart);
120
+ const days = weekDays(weekStart, weekStartsOn);
121
+ const visibleStart = days[0] ?? weekStart;
122
+ const weekend = weekendDays(clock.locale);
110
123
  const nowAt = now ?? today;
111
124
  const nowVisible = days.some((d) => sameDay(d, nowAt));
112
125
 
@@ -126,9 +139,9 @@ export function WeekCalendar({
126
139
  title={formatWeekRange(days, locale)}
127
140
  prevLabel={t('calendar.previousWeek')}
128
141
  nextLabel={t('calendar.nextWeek')}
129
- onPrev={() => show(addDays(weekStart, -7))}
130
- onNext={() => show(addDays(weekStart, 7))}
131
- onToday={() => show(startOfWeek(today))}
142
+ onPrev={() => show(addDays(visibleStart, -7))}
143
+ onNext={() => show(addDays(visibleStart, 7))}
144
+ onToday={() => show(startOfWeek(today, weekStartsOn))}
132
145
  actions={actions}
133
146
  />
134
147
  <div className="overflow-x-auto">
@@ -173,7 +186,7 @@ export function WeekCalendar({
173
186
  className="absolute end-2 font-mono text-[10px] text-muted-foreground"
174
187
  style={{ top: h * hourHeight - 6 }}
175
188
  >
176
- {pad(h)}:00
189
+ {formatHour(h, clock.locale, clock.hourCycle)}
177
190
  </span>
178
191
  ))}
179
192
  </div>
@@ -193,20 +206,21 @@ export function WeekCalendar({
193
206
  return (
194
207
  <ul
195
208
  key={dayKey(d)}
209
+ data-weekend={weekend.includes(d.getDay() as WeekDay) ? '' : undefined}
196
210
  aria-label={formatDay(d, locale)}
197
211
  className="relative border-s border-border/70 first:border-s-0"
198
212
  >
199
213
  {layoutDay(list, hourHeight).map(({ event, top, height: h, lane, lanes }) => {
200
214
  const kind = kindOf(event, kinds);
201
215
  const tone = TONE[kind.tone];
202
- const range = formatRange(event.start, event.end, locale);
216
+ const range = formatRange(event.start, event.end, clock.locale, clock.hourCycle);
203
217
  const body = (
204
218
  <>
205
219
  <span className="block truncate text-[11px] leading-tight font-semibold text-foreground">
206
220
  {event.title}
207
221
  </span>
208
- <span className="block truncate font-mono text-[10px] text-muted-foreground">
209
- {formatTime(event.start, locale)}
222
+ <span className="block truncate font-mono text-[10px] text-foreground">
223
+ {formatTime(event.start, clock.locale, clock.hourCycle)}
210
224
  </span>
211
225
  </>
212
226
  );
@@ -5,6 +5,6 @@ export const meta: BlockMeta = {
5
5
  family: 'scheduling',
6
6
  status: 'beta',
7
7
  description:
8
- 'Seven-day time grid with positioned events (overlaps side by side), a now line, week navigation and optional clickable events.',
8
+ 'Locale-first seven-day time grid with positioned events (overlaps side by side), a now line, week navigation and optional clickable events. weekStartsOn and hourCycle override provider/runtime defaults; data-weekend marks locale weekends without styling. Locale examples show en-US, es-ES, then en-US with Monday-first and 24-hour overrides.',
9
9
  uses: ['Button', 'IconButton'],
10
10
  };
@@ -0,0 +1,19 @@
1
+ import { I18nProvider } from '@gntik-ai/ui';
2
+ import { WeekCalendar } from '../WeekCalendar';
3
+
4
+ /** Compare US defaults, Spanish defaults, and explicit overrides under US English. */
5
+ export default function Locale() {
6
+ return (
7
+ <div className="space-y-6">
8
+ <I18nProvider locale="en-US">
9
+ <WeekCalendar />
10
+ </I18nProvider>
11
+ <I18nProvider locale="es-ES">
12
+ <WeekCalendar />
13
+ </I18nProvider>
14
+ <I18nProvider locale="en-US">
15
+ <WeekCalendar weekStartsOn={1} hourCycle="h23" />
16
+ </I18nProvider>
17
+ </div>
18
+ );
19
+ }