@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/scheduling/WeekCalendar/WeekCalendar.tsx

@@ -0,0 +1,274 @@
+import { useEffect, useId, useMemo, useRef, useState, type ReactNode } from 'react';
+import { cn, useI18n } from '@gntik-ai/ui';
+import { CalendarHeader } from '../shared/CalendarHeader';
+import {
+  addDays,
+  dayKey,
+  formatDay,
+  formatRange,
+  formatTime,
+  formatWeekday,
+  formatWeekRange,
+  hourOf,
+  sameDay,
+  startOfWeek,
+  weekDays,
+} from '../shared/dates';
+import { defaultEventKinds, groupByDay, kindOf, TONE, type EventKind, type ScheduleEvent } from '../shared/events';
+import { sampleEvents, sampleToday } from '../shared/fixtures';
+
+export interface WeekCalendarProps {
+  events?: ScheduleEvent[];
+  /** The app's "today" (the block never reads the clock). */
+  today?: Date;
+  /** Current time for the "now" line, shown when it falls in the visible week. Defaults to `today`. */
+  now?: Date;
+  /** A date inside the week shown first (uncontrolled). Defaults to `today`. */
+  defaultWeek?: Date;
+  /** Called with the Monday of the newly shown week. */
+  onWeekChange?: (weekStart: Date) => void;
+  /** Makes events buttons. */
+  onEventClick?: (event: ScheduleEvent) => void;
+  kinds?: Record<string, EventKind>;
+  /** Hour the grid scrolls to on mount. */
+  scrollToHour?: number;
+  /** Pixels per hour. */
+  hourHeight?: number;
+  /** Max height of the scrolling time grid in px. */
+  height?: number;
+  actions?: ReactNode;
+  className?: string;
+}
+
+const HOURS = Array.from({ length: 24 }, (_, h) => h);
+const pad = (n: number) => String(n).padStart(2, '0');
+
+interface Placed {
+  event: ScheduleEvent;
+  top: number;
+  height: number;
+  lane: number;
+  lanes: number;
+}
+
+/** Side-by-side lanes for overlapping events within one day. */
+function layoutDay(list: readonly ScheduleEvent[], hourHeight: number): Placed[] {
+  const placed: Placed[] = [];
+  let cluster: Placed[] = [];
+  let clusterEnd = -1;
+  let laneEnds: number[] = [];
+  const close = () => {
+    for (const p of cluster) p.lanes = laneEnds.length;
+    cluster = [];
+    laneEnds = [];
+  };
+  for (const event of list) {
+    const start = hourOf(event.start);
+    const end = Math.max(sameDay(event.start, event.end) ? hourOf(event.end) : 24, start + 0.25);
+    if (start >= clusterEnd) close();
+    let lane = laneEnds.findIndex((e) => e <= start);
+    if (lane === -1) {
+      lane = laneEnds.length;
+      laneEnds.push(end);
+    } else laneEnds[lane] = end;
+    clusterEnd = Math.max(clusterEnd, end);
+    const p: Placed = {
+      event,
+      top: start * hourHeight + 1,
+      height: Math.max((end - start) * hourHeight - 2, 18),
+      lane,
+      lanes: 1,
+    };
+    cluster.push(p);
+    placed.push(p);
+  }
+  close();
+  return placed;
+}
+
+/** Week view: seven day columns over a scrolling 24-hour time grid, with a "now" line. */
+export function WeekCalendar({
+  events = sampleEvents,
+  today = sampleToday,
+  now,
+  defaultWeek,
+  onWeekChange,
+  onEventClick,
+  kinds = defaultEventKinds,
+  scrollToHour = 7,
+  hourHeight = 52,
+  height = 480,
+  actions,
+  className,
+}: WeekCalendarProps) {
+  const { t, locale } = useI18n();
+  const titleId = useId();
+  const [weekStart, setWeekStart] = useState<Date>(() => startOfWeek(defaultWeek ?? today));
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const byDay = useMemo(() => groupByDay(events), [events]);
+  const days = weekDays(weekStart);
+  const nowAt = now ?? today;
+  const nowVisible = days.some((d) => sameDay(d, nowAt));
+
+  useEffect(() => {
+    if (scrollRef.current) scrollRef.current.scrollTop = Math.max(scrollToHour * hourHeight - 8, 0);
+  }, [scrollToHour, hourHeight]);
+
+  const show = (start: Date) => {
+    setWeekStart(start);
+    onWeekChange?.(start);
+  };
+
+  return (
+    <div className={cn('overflow-hidden rounded-xl border border-border bg-card', className)}>
+      <CalendarHeader
+        titleId={titleId}
+        title={formatWeekRange(days, locale)}
+        prevLabel={t('calendar.previousWeek')}
+        nextLabel={t('calendar.nextWeek')}
+        onPrev={() => show(addDays(weekStart, -7))}
+        onNext={() => show(addDays(weekStart, 7))}
+        onToday={() => show(startOfWeek(today))}
+        actions={actions}
+      />
+      <div className="overflow-x-auto">
+        <div className="min-w-[640px]">
+          <div aria-hidden className="flex border-b border-border">
+            <div className="w-14 shrink-0 border-e border-border/70" />
+            <div className="grid flex-1 grid-cols-7">
+              {days.map((d) => {
+                const isToday = sameDay(d, today);
+                return (
+                  <div
+                    key={dayKey(d)}
+                    className="flex flex-col items-center justify-center border-s border-border/70 py-2 first:border-s-0"
+                  >
+                    <span className="text-[11px] text-muted-foreground">{formatWeekday(d, locale)}</span>
+                    <span
+                      className={cn(
+                        'mt-1 inline-flex size-7 items-center justify-center rounded-full text-[13px] tabular-nums',
+                        isToday ? 'bg-primary font-semibold text-primary-foreground' : 'font-medium text-foreground',
+                      )}
+                    >
+                      {d.getDate()}
+                    </span>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+          <div
+            ref={scrollRef}
+            tabIndex={0}
+            role="region"
+            aria-labelledby={titleId}
+            className="overflow-y-auto focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus-ring"
+            style={{ maxHeight: height }}
+          >
+            <div className="relative flex" style={{ height: 24 * hourHeight }}>
+              <div aria-hidden className="relative w-14 shrink-0 border-e border-border/70">
+                {HOURS.slice(1).map((h) => (
+                  <span
+                    key={h}
+                    className="absolute end-2 font-mono text-[10px] text-muted-foreground"
+                    style={{ top: h * hourHeight - 6 }}
+                  >
+                    {pad(h)}:00
+                  </span>
+                ))}
+              </div>
+              <div className="relative flex-1">
+                <div aria-hidden className="absolute inset-0">
+                  {HOURS.map((h) => (
+                    <div
+                      key={h}
+                      className="border-t border-border/70 first:border-t-0"
+                      style={{ height: hourHeight }}
+                    />
+                  ))}
+                </div>
+                <div className="relative grid h-full grid-cols-7">
+                  {days.map((d) => {
+                    const list = byDay.get(dayKey(d)) ?? [];
+                    return (
+                      <ul
+                        key={dayKey(d)}
+                        aria-label={formatDay(d, locale)}
+                        className="relative border-s border-border/70 first:border-s-0"
+                      >
+                        {layoutDay(list, hourHeight).map(({ event, top, height: h, lane, lanes }) => {
+                          const kind = kindOf(event, kinds);
+                          const tone = TONE[kind.tone];
+                          const range = formatRange(event.start, event.end, locale);
+                          const body = (
+                            <>
+                              <span className="block truncate text-[11px] leading-tight font-semibold text-foreground">
+                                {event.title}
+                              </span>
+                              <span className="block truncate font-mono text-[10px] text-muted-foreground">
+                                {formatTime(event.start, locale)}
+                              </span>
+                            </>
+                          );
+                          const box = cn(
+                            'block h-full w-full overflow-hidden rounded-md border-s-2 px-2 py-1 text-start',
+                            tone.soft,
+                            tone.bar,
+                          );
+                          return (
+                            <li
+                              key={event.id}
+                              className="absolute px-0.5"
+                              style={{
+                                top,
+                                height: h,
+                                insetInlineStart: `${(lane / lanes) * 100}%`,
+                                width: `${100 / lanes}%`,
+                              }}
+                            >
+                              {onEventClick ? (
+                                <button
+                                  type="button"
+                                  aria-label={`${event.title}, ${range}${event.location ? `, ${event.location}` : ''}`}
+                                  onClick={() => onEventClick(event)}
+                                  className={cn(
+                                    box,
+                                    'transition-colors hover:bg-accent/40 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-focus-ring motion-reduce:transition-none',
+                                  )}
+                                >
+                                  {body}
+                                </button>
+                              ) : (
+                                <div className={box} title={`${event.title} · ${range}`}>
+                                  {body}
+                                  <span className="sr-only">, {range}</span>
+                                </div>
+                              )}
+                            </li>
+                          );
+                        })}
+                      </ul>
+                    );
+                  })}
+                </div>
+                {nowVisible && (
+                  <div
+                    aria-hidden
+                    className="pointer-events-none absolute inset-x-0 z-10 flex items-center"
+                    style={{ top: hourOf(nowAt) * hourHeight }}
+                  >
+                    <span className="-ms-1 size-2 shrink-0 rounded-full bg-primary" />
+                    <span className="h-px flex-1 bg-primary" />
+                    <span className="shrink-0 rounded bg-primary px-1 font-mono text-[9px] text-primary-foreground">
+                      {t('calendar.now')}
+                    </span>
+                  </div>
+                )}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Week calendar',
+  family: 'scheduling',
+  status: 'beta',
+  description:
+    'Seven-day time grid with positioned events (overlaps side by side), a now line, week navigation and optional clickable events.',
+  uses: ['Button', 'IconButton'],
+};

package/src/scheduling/index.ts

@@ -0,0 +1,11 @@
+export * from './MonthCalendar/MonthCalendar';
+export { meta as monthCalendarMeta } from './MonthCalendar/block.meta';
+export * from './WeekCalendar/WeekCalendar';
+export { meta as weekCalendarMeta } from './WeekCalendar/block.meta';
+export * from './AgendaList/AgendaList';
+export { meta as agendaListMeta } from './AgendaList/block.meta';
+export * from './TimeSlotPicker/TimeSlotPicker';
+export { meta as timeSlotPickerMeta } from './TimeSlotPicker/block.meta';
+export { sampleTimeSlots } from './TimeSlotPicker/fixtures';
+export { defaultEventKinds, type ScheduleEvent, type EventKind, type EventTone } from './shared/events';
+export { sampleEvents as sampleScheduleEvents, sampleToday as sampleScheduleToday } from './shared/fixtures';

package/src/scheduling/shared/CalendarHeader.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react';
+import { Button, IconButton, useI18n } from '@gntik-ai/ui';
+import { ChevronLeft, ChevronRight } from '@gntik-ai/icons';
+
+export interface CalendarHeaderProps {
+  titleId: string;
+  title: string;
+  subtitle?: string;
+  prevLabel: string;
+  nextLabel: string;
+  onPrev: () => void;
+  onNext: () => void;
+  onToday: () => void;
+  actions?: ReactNode;
+}
+
+/** Title + previous / today / next navigation + caller actions. */
+export function CalendarHeader({
+  titleId,
+  title,
+  subtitle,
+  prevLabel,
+  nextLabel,
+  onPrev,
+  onNext,
+  onToday,
+  actions,
+}: CalendarHeaderProps) {
+  const { t } = useI18n();
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-3 border-b border-border px-4 py-3 sm:px-5">
+      <div className="min-w-0">
+        <h3
+          id={titleId}
+          aria-live="polite"
+          className="truncate text-[15px] font-semibold tracking-tight text-foreground"
+        >
+          {title}
+        </h3>
+        {subtitle && <p className="mt-0.5 truncate font-mono text-[11px] text-muted-foreground">{subtitle}</p>}
+      </div>
+      <div className="flex shrink-0 items-center gap-2">
+        <div className="flex items-center gap-1">
+          <IconButton icon={ChevronLeft} label={prevLabel} variant="secondary" size="sm" onClick={onPrev} />
+          <Button variant="secondary" size="sm" onClick={onToday}>
+            {t('calendar.today')}
+          </Button>
+          <IconButton icon={ChevronRight} label={nextLabel} variant="secondary" size="sm" onClick={onNext} />
+        </div>
+        {actions}
+      </div>
+    </div>
+  );
+}

package/src/scheduling/shared/EventTile.tsx

@@ -0,0 +1,21 @@
+import { cn } from '@gntik-ai/ui';
+import { TONE, type EventKind } from './events';
+
+/** Square type tile (no avatars on scheduled work). */
+export function EventTile({ kind, className }: { kind: EventKind; className?: string }) {
+  const Glyph = kind.icon;
+  const tone = TONE[kind.tone];
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'inline-flex size-9 shrink-0 items-center justify-center rounded-lg',
+        tone.soft,
+        tone.icon,
+        className,
+      )}
+    >
+      <Glyph size={17} />
+    </span>
+  );
+}

package/src/scheduling/shared/dates.ts

@@ -0,0 +1,98 @@
+/** Native-Date helpers for the scheduling blocks. Weeks start on Monday. */
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** Local calendar key "YYYY-MM-DD". */
+export function dayKey(d: Date): string {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+export function startOfDay(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate());
+}
+
+export function addDays(d: Date, n: number): Date {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate() + n);
+}
+
+export function addMonths(d: Date, n: number): Date {
+  return new Date(d.getFullYear(), d.getMonth() + n, 1);
+}
+
+export function startOfMonth(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), 1);
+}
+
+export function sameDay(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+
+export function sameMonth(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+
+/** Monday of the week containing `d`. */
+export function startOfWeek(d: Date): Date {
+  return addDays(startOfDay(d), -((d.getDay() + 6) % 7));
+}
+
+export function weekDays(d: Date): Date[] {
+  const mon = startOfWeek(d);
+  return Array.from({ length: 7 }, (_, i) => addDays(mon, i));
+}
+
+/** Six Monday-first weeks covering the month of `d`. */
+export function monthGrid(d: Date): Date[][] {
+  const start = startOfWeek(startOfMonth(d));
+  return Array.from({ length: 6 }, (_, w) => Array.from({ length: 7 }, (_, i) => addDays(start, w * 7 + i)));
+}
+
+/** Decimal hour of the day: 10:30 → 10.5. */
+export function hourOf(d: Date): number {
+  return d.getHours() + d.getMinutes() / 60;
+}
+
+const cache = new Map<string, Intl.DateTimeFormat>();
+/** Cached Intl formatter; `locale` defaults to en-US (pass `useI18n().locale` to localise). */
+const fmt = (locale: string | undefined, opts: Intl.DateTimeFormatOptions) => {
+  const key = `${locale ?? 'en-US'}|${JSON.stringify(opts)}`;
+  let f = cache.get(key);
+  if (!f) {
+    f = new Intl.DateTimeFormat(locale ?? 'en-US', opts);
+    cache.set(key, f);
+  }
+  return f;
+};
+
+/** "09:30". */
+export const formatTime = (d: Date, locale?: string) =>
+  fmt(locale, { hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).format(d);
+/** "09:30–10:00". */
+export const formatRange = (start: Date, end: Date, locale?: string) =>
+  `${formatTime(start, locale)}–${formatTime(end, locale)}`;
+/** "Wednesday, April 15, 2026". */
+export const formatFullDate = (d: Date, locale?: string) =>
+  fmt(locale, { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }).format(d);
+/** "Wednesday, April 15". */
+export const formatDay = (d: Date, locale?: string) =>
+  fmt(locale, { weekday: 'long', month: 'long', day: 'numeric' }).format(d);
+/** "April 2026". */
+export const formatMonth = (d: Date, locale?: string) => fmt(locale, { month: 'long', year: 'numeric' }).format(d);
+/** "Apr 15". */
+export const formatShort = (d: Date, locale?: string) => fmt(locale, { month: 'short', day: 'numeric' }).format(d);
+/** "Wed". */
+export const formatWeekday = (d: Date, locale?: string, weekday: 'short' | 'long' = 'short') =>
+  fmt(locale, { weekday }).format(d);
+
+/** "Apr 13 – 19, 2026" (or across months / years). */
+export function formatWeekRange(days: readonly Date[], locale?: string): string {
+  const first = days[0];
+  const last = days[days.length - 1];
+  if (!first || !last) return '';
+  if (locale && !locale.toLowerCase().startsWith('en'))
+    return fmt(locale, { month: 'short', day: 'numeric', year: 'numeric' }).formatRange(first, last);
+  if (sameMonth(first, last)) return `${formatShort(first)} – ${last.getDate()}, ${last.getFullYear()}`;
+  if (first.getFullYear() === last.getFullYear())
+    return `${formatShort(first)} – ${formatShort(last)}, ${last.getFullYear()}`;
+  return `${formatShort(first)}, ${first.getFullYear()} – ${formatShort(last)}, ${last.getFullYear()}`;
+}

package/src/scheduling/shared/events.ts

@@ -0,0 +1,90 @@
+import { CalendarCheck, Cog, Database, RefreshCw, ShieldCheck, Upload, type LucideIcon } from '@gntik-ai/icons';
+import type { BadgeTone } from '@gntik-ai/ui';
+import { dayKey } from './dates';
+
+/** A scheduled item on a calendar. */
+export interface ScheduleEvent {
+  id: string;
+  title: string;
+  start: Date;
+  end: Date;
+  /** Key into the `kinds` map (job, deploy, review, backup, maintenance…). */
+  kind?: string;
+  /** Region, room or target, shown after the time. */
+  location?: string;
+}
+
+export type EventTone = 'primary' | 'violet' | 'cyan' | 'amber' | 'neutral';
+
+export interface EventKind {
+  label: string;
+  icon: LucideIcon;
+  tone: EventTone;
+}
+
+/** Default kinds: brand green for jobs, categorical accents for the rest (never severity). */
+export const defaultEventKinds: Record<string, EventKind> = {
+  job: { label: 'Job', icon: RefreshCw, tone: 'primary' },
+  deploy: { label: 'Deploy', icon: Upload, tone: 'violet' },
+  review: { label: 'Review', icon: ShieldCheck, tone: 'cyan' },
+  backup: { label: 'Backup', icon: Database, tone: 'amber' },
+  maintenance: { label: 'Maintenance', icon: Cog, tone: 'neutral' },
+};
+
+const FALLBACK: EventKind = { label: 'Event', icon: CalendarCheck, tone: 'primary' };
+
+export function kindOf(event: ScheduleEvent, kinds: Record<string, EventKind>): EventKind {
+  return (event.kind ? kinds[event.kind] : undefined) ?? FALLBACK;
+}
+
+/** Token classes per tone. Text stays foreground on category tints (no contrast alias for them). */
+export const TONE: Record<EventTone, { dot: string; soft: string; bar: string; icon: string; badge: BadgeTone }> = {
+  primary: {
+    dot: 'bg-primary',
+    soft: 'bg-primary/12',
+    bar: 'border-primary',
+    icon: 'text-primary-text',
+    badge: 'primary',
+  },
+  violet: {
+    dot: 'bg-category-violet',
+    soft: 'bg-category-violet/14',
+    bar: 'border-category-violet',
+    icon: 'text-foreground',
+    badge: 'violet',
+  },
+  cyan: {
+    dot: 'bg-category-cyan',
+    soft: 'bg-category-cyan/14',
+    bar: 'border-category-cyan',
+    icon: 'text-foreground',
+    badge: 'cyan',
+  },
+  amber: {
+    dot: 'bg-category-amber',
+    soft: 'bg-category-amber/16',
+    bar: 'border-category-amber',
+    icon: 'text-foreground',
+    badge: 'amber',
+  },
+  neutral: {
+    dot: 'bg-muted-foreground',
+    soft: 'bg-secondary',
+    bar: 'border-muted-foreground',
+    icon: 'text-muted-foreground',
+    badge: 'neutral',
+  },
+};
+
+/** Events grouped by local day key, each day sorted by start. */
+export function groupByDay(events: readonly ScheduleEvent[]): Map<string, ScheduleEvent[]> {
+  const map = new Map<string, ScheduleEvent[]>();
+  for (const e of events) {
+    const key = dayKey(e.start);
+    const list = map.get(key);
+    if (list) list.push(e);
+    else map.set(key, [e]);
+  }
+  for (const list of map.values()) list.sort((a, b) => a.start.getTime() - b.start.getTime());
+  return map;
+}

package/src/scheduling/shared/fixtures.ts

@@ -0,0 +1,54 @@
+import type { ScheduleEvent } from './events';
+
+/** The sample calendar's "today" (Wed 15 Apr 2026, 10:20). Pass your own `today` in apps. */
+export const sampleToday = new Date(2026, 3, 15, 10, 20);
+
+type Row = [day: number, kind: string, title: string, start: number, hours: number, location?: string];
+
+const ROWS: Row[] = [
+  [3, 'deploy', 'API gateway v3.1', 10, 1, 'eu-west-1'],
+  [7, 'job', 'Data import batch', 6.5, 2],
+  [7, 'review', 'Access review', 14, 1, 'eu-west-1'],
+  [9, 'backup', 'Snapshot · search index', 11, 1.5],
+  [13, 'job', 'Inbox sync', 7, 0.5],
+  [13, 'deploy', 'Billing service v2.4 rollout', 9.5, 1.5, 'us-east-1'],
+  [13, 'review', 'Access review', 14, 1, 'eu-west-1'],
+  [14, 'job', 'Data import batch', 6.5, 2],
+  [14, 'backup', 'Snapshot · search index', 11, 1.5],
+  [14, 'job', 'Usage rollup', 21, 0.5],
+  [15, 'job', 'Inbox sync', 6, 0.5],
+  [15, 'job', 'Report export', 7, 0.5],
+  [15, 'deploy', 'Checkout hotfix', 9, 1, 'eu-west-1'],
+  [15, 'review', 'Compliance review', 10.5, 1.5, 'all regions'],
+  [15, 'backup', 'Snapshot · primary database', 13, 1],
+  [15, 'job', 'Weekly digest', 15, 0.5],
+  [15, 'maintenance', 'Maintenance window', 16, 2, 'ap-south-1'],
+  [15, 'job', 'Search reindex', 19, 1],
+  [15, 'job', 'Usage rollup', 21.5, 0.5],
+  [16, 'job', 'Inbox sync', 7, 0.5],
+  [16, 'deploy', 'Notifications v1.8', 13.5, 1, 'us-east-1'],
+  [16, 'maintenance', 'Node pool upgrade', 22, 1.5],
+  [17, 'review', 'Weekly cost review', 10, 1],
+  [17, 'backup', 'Full backup', 22.5, 1],
+  [18, 'job', 'Weekend health check', 9, 0.5],
+  [19, 'maintenance', 'Certificate rotation', 3, 1],
+  [22, 'job', 'Inbox sync', 7, 0.5],
+  [22, 'deploy', 'Billing service v2.5', 11, 1, 'us-east-1'],
+  [22, 'review', 'Policy review', 15, 1],
+  [24, 'job', 'Data import batch', 6.5, 2],
+  [28, 'maintenance', 'Maintenance window', 16, 2, 'eu-west-1'],
+  [30, 'review', 'Month-end review', 9, 2],
+  [30, 'backup', 'Full backup', 22.5, 1],
+];
+
+const at = (day: number, hour: number) => new Date(2026, 3, day, Math.floor(hour), Math.round((hour % 1) * 60));
+
+/** Sample scheduled work for April 2026 (jobs, deploys, reviews, backups, maintenance). */
+export const sampleEvents: ScheduleEvent[] = ROWS.map(([day, kind, title, start, hours, location], i) => ({
+  id: `evt-${i + 1}`,
+  title,
+  kind,
+  start: at(day, start),
+  end: at(day, start + hours),
+  location,
+}));

package/src/shell/AppSidebar/AppSidebar.test.tsx

@@ -0,0 +1,38 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { AppSidebar } from './AppSidebar';
+
+describe('AppSidebar', () => {
+  it('renders the workspace switcher, navigation, usage, help and user', async () => {
+    const { container } = render(<AppSidebar />);
+    expect(screen.getByRole('button', { name: /Acme Industries/ })).toBeInTheDocument();
+    const nav = screen.getByRole('navigation', { name: 'Main' });
+    expect(within(nav).getByRole('link', { name: 'Projects 12' })).toHaveAttribute('aria-current', 'page');
+    expect(screen.getByRole('meter', { name: 'Monthly requests' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Help & docs' })).toBeInTheDocument();
+    expect(screen.getByText('Dana Whitfield')).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  }, 15_000);
+
+  it('switches workspace and reports navigation', async () => {
+    const user = userEvent.setup();
+    const onWorkspaceChange = vi.fn();
+    const onNavigate = vi.fn();
+    render(<AppSidebar onWorkspaceChange={onWorkspaceChange} onNavigate={onNavigate} />);
+    await user.click(screen.getByRole('button', { name: /Acme Industries/ }));
+    await user.click(await screen.findByRole('menuitemradio', { name: /Northbeam Labs/ }));
+    expect(onWorkspaceChange).toHaveBeenCalledWith(expect.objectContaining({ id: 'northbeam' }));
+    expect(screen.getByRole('button', { name: /Northbeam Labs/ })).toBeInTheDocument();
+    await user.click(screen.getByRole('link', { name: 'Billing' }));
+    expect(onNavigate).toHaveBeenCalledWith(expect.objectContaining({ href: '/billing' }));
+  });
+
+  it('collapsed: icon rail with the brand mark and an icon-only help link', async () => {
+    const { container } = render(<AppSidebar collapsed />);
+    expect(screen.queryByRole('meter')).not.toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Help & docs' })).toBeInTheDocument();
+    expect(screen.getByRole('navigation')).toHaveAttribute('data-collapsed');
+    await expectNoAxeViolations(container);
+  });
+});