@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/scheduling/MonthCalendar/MonthCalendar.tsx

@@ -0,0 +1,223 @@
+import { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';
+import { cn, useI18n } from '@gntik-ai/ui';
+import { CalendarHeader } from '../shared/CalendarHeader';
+import {
+  addDays,
+  addMonths,
+  dayKey,
+  formatFullDate,
+  formatMonth,
+  formatTime,
+  formatWeekday,
+  monthGrid,
+  sameDay,
+  sameMonth,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+} from '../shared/dates';
+import { defaultEventKinds, groupByDay, kindOf, TONE, type EventKind, type ScheduleEvent } from '../shared/events';
+import { sampleEvents, sampleToday } from '../shared/fixtures';
+
+export interface MonthCalendarProps {
+  events?: ScheduleEvent[];
+  /** The app's "today" (the block never reads the clock). */
+  today?: Date;
+  /** Month shown first (uncontrolled). Defaults to the month of `today`. */
+  defaultMonth?: Date;
+  onMonthChange?: (month: Date) => void;
+  /** Initially selected day (uncontrolled). */
+  defaultSelected?: Date;
+  /** Called when a day is activated (click, Enter or Space). */
+  onSelectDate?: (date: Date, events: ScheduleEvent[]) => void;
+  /** Event kinds (label, icon, tone) by `event.kind`. */
+  kinds?: Record<string, EventKind>;
+  /** Event lines per day before "+N more". */
+  maxEventsPerDay?: number;
+  /** Caller actions in the header (e.g. a "Schedule" button). */
+  actions?: ReactNode;
+  className?: string;
+}
+
+/** Monday-first weekdays (2026-01-05 is a Monday). */
+const WEEK = Array.from({ length: 7 }, (_, i) => new Date(2026, 0, 5 + i));
+
+/**
+ * Month view of scheduled work: a Monday-first grid with up to N events per day.
+ * Keyboard: arrows move by day/week, Home/End to the week edges, PageUp/PageDown by month,
+ * Enter/Space selects.
+ */
+export function MonthCalendar({
+  events = sampleEvents,
+  today = sampleToday,
+  defaultMonth,
+  onMonthChange,
+  defaultSelected,
+  onSelectDate,
+  kinds = defaultEventKinds,
+  maxEventsPerDay = 2,
+  actions,
+  className,
+}: MonthCalendarProps) {
+  const { t, locale, dir } = useI18n();
+  const titleId = useId();
+  const [selected, setSelected] = useState<Date>(() => startOfDay(defaultSelected ?? today));
+  const [focused, setFocused] = useState<Date>(() => startOfDay(defaultSelected ?? defaultMonth ?? today));
+  const [month, setMonth] = useState<Date>(() => startOfMonth(defaultMonth ?? defaultSelected ?? today));
+  const gridRef = useRef<HTMLDivElement>(null);
+  const moveFocus = useRef(false);
+  const byDay = useMemo(() => groupByDay(events), [events]);
+  const weeks = monthGrid(month);
+  // The roving tab stop stays inside the visible month.
+  const tabStop = sameMonth(focused, month) ? focused : sameMonth(selected, month) ? selected : month;
+
+  useEffect(() => {
+    if (!moveFocus.current) return;
+    moveFocus.current = false;
+    gridRef.current?.querySelector<HTMLElement>(`[data-date="${dayKey(focused)}"]`)?.focus();
+  }, [focused]);
+
+  const showMonth = (next: Date) => {
+    const first = startOfMonth(next);
+    setMonth(first);
+    onMonthChange?.(first);
+  };
+
+  const go = (date: Date) => {
+    setFocused(date);
+    if (!sameMonth(date, month)) showMonth(date);
+    moveFocus.current = true;
+  };
+
+  const select = (date: Date) => {
+    setSelected(date);
+    setFocused(date);
+    onSelectDate?.(date, byDay.get(dayKey(date)) ?? []);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, date: Date) => {
+    const weekStart = startOfWeek(date);
+    const map: Record<string, () => Date> = {
+      ArrowLeft: () => addDays(date, dir === 'rtl' ? 1 : -1),
+      ArrowRight: () => addDays(date, dir === 'rtl' ? -1 : 1),
+      ArrowUp: () => addDays(date, -7),
+      ArrowDown: () => addDays(date, 7),
+      Home: () => weekStart,
+      End: () => addDays(weekStart, 6),
+      PageUp: () => new Date(date.getFullYear(), date.getMonth() - 1, Math.min(date.getDate(), 28)),
+      PageDown: () => new Date(date.getFullYear(), date.getMonth() + 1, Math.min(date.getDate(), 28)),
+    };
+    const next = map[event.key];
+    if (!next) return;
+    event.preventDefault();
+    go(next());
+  };
+
+  return (
+    <div className={cn('overflow-hidden rounded-xl border border-border bg-card', className)}>
+      <CalendarHeader
+        titleId={titleId}
+        title={formatMonth(month, locale)}
+        prevLabel={t('calendar.previousMonth')}
+        nextLabel={t('calendar.nextMonth')}
+        onPrev={() => showMonth(addMonths(month, -1))}
+        onNext={() => showMonth(addMonths(month, 1))}
+        onToday={() => {
+          showMonth(today);
+          setFocused(startOfDay(today));
+        }}
+        actions={actions}
+      />
+      <div ref={gridRef} role="grid" aria-labelledby={titleId}>
+        <div role="row" className="grid grid-cols-7 border-b border-border bg-secondary/30">
+          {WEEK.map((day) => (
+            <div
+              key={day.getDay()}
+              role="columnheader"
+              aria-label={formatWeekday(day, locale, 'long')}
+              className="py-2 text-center text-[11px] font-medium tracking-wide text-muted-foreground uppercase"
+            >
+              {formatWeekday(day, locale)}
+            </div>
+          ))}
+        </div>
+        {weeks.map((week) => (
+          <div key={dayKey(week[0] ?? month)} role="row" className="grid grid-cols-7">
+            {week.map((date) => {
+              const key = dayKey(date);
+              const list = byDay.get(key) ?? [];
+              const inMonth = sameMonth(date, month);
+              const isToday = sameDay(date, today);
+              const isSelected = sameDay(date, selected);
+              const extra = list.length - maxEventsPerDay;
+              return (
+                <div
+                  key={key}
+                  role="gridcell"
+                  aria-selected={isSelected}
+                  className="min-w-0 border-e border-b border-border/70 [&:nth-child(7)]:border-e-0"
+                >
+                  <button
+                    type="button"
+                    data-date={key}
+                    tabIndex={sameDay(date, tabStop) ? 0 : -1}
+                    aria-label={`${formatFullDate(date, locale)}${list.length ? `, ${t('calendar.events', { count: list.length })}` : ''}`}
+                    aria-current={isToday ? 'date' : undefined}
+                    onClick={() => select(date)}
+                    onKeyDown={(e) => onKeyDown(e, date)}
+                    className={cn(
+                      'flex h-full min-h-14 w-full flex-col items-stretch p-1.5 text-start transition-colors motion-reduce:transition-none sm:min-h-[92px] sm:p-2',
+                      'hover:bg-accent/30 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring',
+                      inMonth ? 'bg-card' : 'bg-secondary/20',
+                    )}
+                  >
+                    <span className="flex items-center justify-between">
+                      <span
+                        className={cn(
+                          'inline-flex size-6 items-center justify-center rounded-full text-[12px] font-medium tabular-nums',
+                          isToday
+                            ? 'bg-primary font-semibold text-primary-foreground'
+                            : isSelected
+                              ? 'bg-secondary text-foreground ring-1 ring-border'
+                              : inMonth
+                                ? 'text-foreground'
+                                : 'text-muted-foreground',
+                        )}
+                      >
+                        {date.getDate()}
+                      </span>
+                      {isSelected && !isToday && <span aria-hidden className="size-1.5 rounded-full bg-primary" />}
+                    </span>
+                    {list.length > 0 && (
+                      <span aria-hidden className="mt-1 flex gap-0.5 sm:hidden">
+                        {list.slice(0, 3).map((e) => (
+                          <span key={e.id} className={cn('size-1.5 rounded-full', TONE[kindOf(e, kinds).tone].dot)} />
+                        ))}
+                      </span>
+                    )}
+                    <span aria-hidden className="mt-1.5 hidden space-y-1 sm:block">
+                      {list.slice(0, maxEventsPerDay).map((e) => (
+                        <span key={e.id} className="flex min-w-0 items-center gap-1.5">
+                          <span className={cn('size-1.5 shrink-0 rounded-full', TONE[kindOf(e, kinds).tone].dot)} />
+                          <span className="truncate text-[11px] text-foreground/80">{e.title}</span>
+                          <span className="ms-auto hidden shrink-0 font-mono text-[10px] text-muted-foreground xl:block">
+                            {formatTime(e.start, locale)}
+                          </span>
+                        </span>
+                      ))}
+                      {extra > 0 && (
+                        <span className="block ps-3 text-[10.5px] text-muted-foreground">
+                          + {t('common.more', { count: extra })}
+                        </span>
+                      )}
+                    </span>
+                  </button>
+                </div>
+              );
+            })}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/scheduling/MonthCalendar/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Month calendar',
+  family: 'scheduling',
+  status: 'beta',
+  description:
+    'Monday-first month grid of scheduled work with per-day event lines, today/selected states, month navigation and full grid keyboard support.',
+  uses: ['Button', 'IconButton'],
+};

package/src/scheduling/TimeSlotPicker/TimeSlotPicker.test.tsx

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { TimeSlotPicker } from './TimeSlotPicker';
+
+describe('TimeSlotPicker', () => {
+  it('renders a radio group with taken slots disabled', async () => {
+    const { container } = render(<TimeSlotPicker description="Wednesday, April 15" />);
+    expect(screen.getByRole('group', { name: 'Available times' })).toBeInTheDocument();
+    expect(screen.getAllByRole('radio')).toHaveLength(25);
+    expect(screen.getByRole('radio', { name: /^09:00/ })).toBeDisabled();
+    await expectNoAxeViolations(container);
+  });
+
+  it('selects by click and by arrow keys', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(<TimeSlotPicker onValueChange={onValueChange} />);
+    await user.click(screen.getByRole('radio', { name: '10:00' }));
+    expect(screen.getByRole('radio', { name: '10:00' })).toBeChecked();
+    expect(onValueChange).toHaveBeenLastCalledWith('10:00');
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('radio', { name: '10:30' })).toBeChecked();
+    expect(onValueChange).toHaveBeenLastCalledWith('10:30');
+  });
+});

package/src/scheduling/TimeSlotPicker/TimeSlotPicker.tsx

@@ -0,0 +1,115 @@
+import { useId, useState } from 'react';
+import { cn, useI18n } from '@gntik-ai/ui';
+import { sampleTimeSlots } from './fixtures';
+
+export interface TimeSlot {
+  /** Submitted value, e.g. "09:30". */
+  value: string;
+  /** Visible label. Defaults to `value`. */
+  label?: string;
+  /** Taken slots render struck through and disabled. Default true. */
+  available?: boolean;
+}
+
+export interface TimeSlotPickerProps {
+  slots?: TimeSlot[];
+  /** Controlled value. */
+  value?: string | null;
+  /** Uncontrolled initial value. */
+  defaultValue?: string | null;
+  onValueChange?: (value: string) => void;
+  /** Group label (the fieldset legend). */
+  legend?: string;
+  /** Secondary line under the legend, e.g. the chosen date. */
+  description?: string;
+  /** Form field name. */
+  name?: string;
+  /** Slot columns from the `sm` breakpoint (two on small screens). */
+  columns?: 2 | 3 | 4 | 6;
+  /** Max height of the scrolling slot list in px. */
+  maxHeight?: number;
+  className?: string;
+}
+
+const COLS: Record<NonNullable<TimeSlotPickerProps['columns']>, string> = {
+  2: 'sm:grid-cols-2',
+  3: 'sm:grid-cols-3',
+  4: 'sm:grid-cols-4',
+  6: 'sm:grid-cols-6',
+};
+
+/**
+ * Pick one time slot. Native radio semantics: Tab enters the group, arrow keys move and select,
+ * taken slots are disabled.
+ */
+export function TimeSlotPicker({
+  slots = sampleTimeSlots,
+  value,
+  defaultValue = null,
+  onValueChange,
+  legend: legendProp,
+  description,
+  name,
+  columns = 4,
+  maxHeight = 244,
+  className,
+}: TimeSlotPickerProps) {
+  const { t } = useI18n();
+  const legend = legendProp ?? t('calendar.availableTimes');
+  const autoName = useId();
+  const descId = useId();
+  const [inner, setInner] = useState<string | null>(defaultValue);
+  const current = value !== undefined ? value : inner;
+
+  const choose = (next: string) => {
+    if (value === undefined) setInner(next);
+    onValueChange?.(next);
+  };
+
+  return (
+    <fieldset aria-describedby={description ? descId : undefined} className={cn('min-w-0', className)}>
+      <legend className="text-[12.5px] font-medium text-foreground">{legend}</legend>
+      {description && (
+        <p id={descId} className="mt-0.5 text-[12px] text-muted-foreground">
+          {description}
+        </p>
+      )}
+      <div className="mt-2.5 overflow-y-auto p-0.5" style={{ maxHeight }}>
+        <div className={cn('grid grid-cols-2 gap-1.5', COLS[columns])}>
+          {slots.map((slot) => {
+            const available = slot.available !== false;
+            return (
+              <label
+                key={slot.value}
+                className={cn('relative block', available ? 'cursor-pointer' : 'cursor-not-allowed')}
+              >
+                <input
+                  type="radio"
+                  name={name ?? autoName}
+                  value={slot.value}
+                  checked={current === slot.value}
+                  disabled={!available}
+                  onChange={() => choose(slot.value)}
+                  className="peer sr-only"
+                />
+                <span
+                  className={cn(
+                    'flex h-8 items-center justify-center rounded-md border font-mono text-[12px] font-medium tabular-nums transition-colors motion-reduce:transition-none',
+                    'peer-focus-visible:outline-2 peer-focus-visible:outline-offset-2 peer-focus-visible:outline-focus-ring',
+                    'peer-checked:border-primary peer-checked:bg-primary peer-checked:text-primary-foreground peer-checked:shadow-sm',
+                    available
+                      ? 'border-border bg-background text-foreground hover:border-muted-foreground/40 hover:bg-secondary/60'
+                      : 'border-border/50 bg-secondary/20 text-muted-foreground line-through',
+                  )}
+                >
+                  {slot.label ?? slot.value}
+                  {!available && <span className="sr-only"> {t('calendar.unavailable')}</span>}
+                </span>
+              </label>
+            );
+          })}
+        </div>
+      </div>
+    </fieldset>
+  );
+}

package/src/scheduling/TimeSlotPicker/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Time slot picker',
+  family: 'scheduling',
+  status: 'beta',
+  description:
+    'Grid of selectable time slots with native radio semantics (arrow keys, form name), taken slots struck through and disabled, controlled or uncontrolled.',
+  uses: [],
+};

package/src/scheduling/TimeSlotPicker/fixtures.ts

@@ -0,0 +1,10 @@
+import type { TimeSlot } from './TimeSlotPicker';
+
+const busy = new Set(['09:00', '09:30', '12:00', '14:30', '15:00', '18:30']);
+
+/** Half-hour slots from 09:00 to 21:00 with a few already taken. */
+export const sampleTimeSlots: TimeSlot[] = Array.from({ length: 25 }, (_, i) => {
+  const minutes = 9 * 60 + i * 30;
+  const value = `${String(Math.floor(minutes / 60)).padStart(2, '0')}:${String(minutes % 60).padStart(2, '0')}`;
+  return { value, available: !busy.has(value) };
+});

package/src/scheduling/WeekCalendar/WeekCalendar.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { WeekCalendar } from './WeekCalendar';
+
+describe('WeekCalendar', () => {
+  it('renders the sample week with its events per day', async () => {
+    const { container } = render(<WeekCalendar />);
+    expect(screen.getByRole('heading', { name: 'Apr 13 – 19, 2026' })).toBeInTheDocument();
+    const wednesday = screen.getByRole('list', { name: 'Wednesday, April 15' });
+    expect(within(wednesday).getAllByRole('listitem')).toHaveLength(9);
+    await expectNoAxeViolations(container);
+  });
+
+  it('changes week and reports event clicks', async () => {
+    const user = userEvent.setup();
+    const onEventClick = vi.fn();
+    const onWeekChange = vi.fn();
+    render(<WeekCalendar onEventClick={onEventClick} onWeekChange={onWeekChange} />);
+    await user.click(screen.getByRole('button', { name: 'Checkout hotfix, 09:00–10:00, eu-west-1' }));
+    expect(onEventClick).toHaveBeenCalledWith(expect.objectContaining({ title: 'Checkout hotfix' }));
+    await user.click(screen.getByRole('button', { name: 'Next week' }));
+    expect(onWeekChange).toHaveBeenCalledWith(new Date(2026, 3, 20));
+    expect(screen.getByRole('heading', { name: 'Apr 20 – 26, 2026' })).toBeInTheDocument();
+    await expectNoAxeViolations(document.body);
+  });
+});