@12-apps/ui 6.86.2 → 6.87.0

package/src/components/data-display/DayRuler/useRulerDrag.ts

@@ -0,0 +1,167 @@
+import type * as React from 'react';
+import { useCallback, useRef, useState } from 'react';
+
+import { useDragWindow, useTrailingClick } from '../ScheduleGrid/drag-session';
+import { DAY_RULER_METRICS as M } from './DayRuler.metrics';
+import { createdSpan, hourAt, moved, resized } from './day-ruler-model';
+import type { DayRulerBlock, RulerHour } from './DayRuler.types';
+
+type Mode = 'create' | 'move' | 'start' | 'end';
+
+/** The gesture in progress: the block as it would land if released now. */
+export interface RulerDrag {
+  mode: Mode;
+  rowId: string;
+  /** Absent for a create. */
+  blockId?: string;
+  start: RulerHour;
+  end: RulerHour;
+  moved: boolean;
+}
+
+interface Origin {
+  /** The track's box, read once when the drag starts (px from the viewport's left, and across). */
+  boxStart: number;
+  boxSize: number;
+  /** The hour pressed. */
+  anchor: RulerHour;
+  /** The block's own hours before the drag (a create has none). */
+  start: RulerHour;
+  end: RulerHour;
+}
+
+interface Scale {
+  from: RulerHour;
+  to: RulerHour;
+  snap: number;
+  createHours: number;
+}
+
+interface RulerHandlers {
+  onCreate?: (rowId: string, start: RulerHour, end: RulerHour) => void;
+  onMove?: (blockId: string, start: RulerHour, end: RulerHour) => void;
+  onResize?: (blockId: string, start: RulerHour, end: RulerHour) => void;
+}
+
+export interface RulerDragApi {
+  drag: RulerDrag | null;
+  /** Pointer down on a row's empty track. */
+  startCreate: (event: React.PointerEvent<HTMLElement>, rowId: string) => void;
+  /** Pointer down on a block's middle (`move`) or on one of its end handles. */
+  startBlock: (event: React.PointerEvent<HTMLElement>, rowId: string, block: DayRulerBlock, mode: 'move' | 'start' | 'end') => void;
+  /** True once, for the click a finished drag leaves behind. */
+  takeClick: () => boolean;
+}
+
+/** A drag starts only for the primary button of a mouse or a pen: touch scrolls, and taps are clicks. */
+function startsDrag(event: React.PointerEvent): boolean {
+  return event.pointerType !== 'touch' && (event.button ?? 0) === 0;
+}
+
+/** The track an event happened on — a block's or a handle's included. */
+function trackOf(target: EventTarget | null): HTMLElement | null {
+  return target instanceof Element ? target.closest<HTMLElement>('[data-dr-track]') : null;
+}
+
+/** The block where the pointer is now, from where the drag began. */
+function next(drag: RulerDrag, origin: Origin, x: number, scale: Scale): RulerDrag {
+  const h = hourAt(x, origin.boxStart, origin.boxSize, scale.from, scale.to, scale.snap);
+  let span: [RulerHour, RulerHour];
+  if (drag.mode === 'create') span = [Math.min(origin.anchor, h), Math.max(origin.anchor, h)];
+  else if (drag.mode === 'move') span = moved(origin.start, origin.end, h - origin.anchor, scale.from, scale.to);
+  else span = resized(origin.start, origin.end, drag.mode, h, M.minHours, scale.from, scale.to);
+  const changed = span[0] !== drag.start || span[1] !== drag.end;
+  return changed ? { ...drag, start: span[0], end: span[1], moved: true } : drag;
+}
+
+/** Report the finished gesture. Returns whether the trailing click must be ignored. */
+function finish(drag: RulerDrag, origin: Origin, scale: Scale, handlers: RulerHandlers): boolean {
+  if (drag.mode === 'create') {
+    const [start, end] = createdSpan(drag.start, drag.end, M.minHours, scale.createHours, scale.to);
+    handlers.onCreate?.(drag.rowId, start, end);
+    return true;
+  }
+  const changed = drag.start !== origin.start || drag.end !== origin.end;
+  if (drag.blockId && changed) {
+    if (drag.mode === 'move') handlers.onMove?.(drag.blockId, drag.start, drag.end);
+    else handlers.onResize?.(drag.blockId, drag.start, drag.end);
+  }
+  // A handle pressed in place is not the block's click; a block moved and
+  // brought back is not one either.
+  return drag.mode !== 'move' || drag.moved;
+}
+
+/**
+ * Click-and-drag on the day ruler (FUT-3825): create on an empty track (a
+ * click alone is `createHours`), slide a block by its middle, change its start
+ * or end by its handles — every hour snapped to `snapMinutes` and kept on the
+ * ruler. Window listeners while a drag runs (a release anywhere commits); the
+ * hour comes from the pointer's x over the track's box as it was when the drag
+ * started. Escape, the window losing focus, or a move with no button down
+ * abandons the drag and puts the block back.
+ */
+export function useRulerDrag(scale: Scale, handlers: RulerHandlers): RulerDragApi {
+  const [drag, setDrag] = useState<RulerDrag | null>(null);
+  const live = useRef<{ drag: RulerDrag; origin: Origin } | null>(null);
+  const latest = useRef({ scale, handlers });
+  latest.current = { scale, handlers };
+  const click = useTrailingClick();
+
+  const set = useCallback((value: { drag: RulerDrag; origin: Origin } | null) => {
+    live.current = value;
+    setDrag(value?.drag ?? null);
+  }, []);
+
+  useDragWindow(drag !== null, {
+    move: (event) => {
+      const current = live.current;
+      if (!current) return;
+      const updated = next(current.drag, current.origin, event.clientX, latest.current.scale);
+      if (updated !== current.drag) set({ drag: updated, origin: current.origin });
+    },
+    up: () => {
+      const current = live.current;
+      set(null);
+      if (current && finish(current.drag, current.origin, latest.current.scale, latest.current.handlers)) click.arm(true);
+    },
+    // Abandoned: nothing reported, the block back at its own hours, the
+    // preview gone. With the button still down, its release is not a click.
+    abort: (reason) => {
+      set(null);
+      if (reason === 'escape' || reason === 'blur') click.arm(false);
+    },
+  });
+
+  const begin = (event: React.PointerEvent<HTMLElement>, value: Omit<RulerDrag, 'moved'>, block?: DayRulerBlock): void => {
+    const track = trackOf(event.currentTarget);
+    if (!track) return;
+    const { left: boxStart, width: boxSize } = track.getBoundingClientRect();
+    const { from, to, snap } = latest.current.scale;
+    const anchor = hourAt(event.clientX, boxStart, boxSize, from, to, snap);
+    const start = block ? block.start : anchor;
+    const end = block ? block.end : anchor;
+    click.reset();
+    set({
+      drag: { ...value, start, end, moved: false },
+      origin: { boxStart, boxSize, anchor, start, end },
+    });
+  };
+
+  const startCreate = (event: React.PointerEvent<HTMLElement>, rowId: string): void => {
+    if (!startsDrag(event) || event.target !== event.currentTarget) return;
+    event.preventDefault();
+    begin(event, { mode: 'create', rowId, start: 0, end: 0 });
+  };
+  const startBlock = (
+    event: React.PointerEvent<HTMLElement>,
+    rowId: string,
+    block: DayRulerBlock,
+    mode: 'move' | 'start' | 'end',
+  ): void => {
+    event.stopPropagation();
+    if (!startsDrag(event)) return;
+    begin(event, { mode, rowId, blockId: block.id, start: block.start, end: block.end }, block);
+  };
+
+  return { drag, startCreate, startBlock, takeClick: click.take };
+}

package/src/components/data-display/DayRuler/useTextFits.ts

@@ -0,0 +1,41 @@
+import type * as React from 'react';
+import { useLayoutEffect, useState } from 'react';
+
+/**
+ * Whether a block's full text fits it, by pixels (FUT-3825): the full text's
+ * own width against the room the block leaves it, re-read whenever the block
+ * is resized. A wide block on a narrow ruler keeps "18:00–23:00"; only one too
+ * short for it says its start.
+ *
+ * The full text is measured with its span shown for the measurement alone
+ * (synchronously, so nothing is painted), even while the short text stands in
+ * for it. Where nothing can be measured (no `ResizeObserver`) it answers
+ * `fallback`.
+ */
+export function useTextFits(block: React.RefObject<HTMLElement | null>, text: string, fallback: boolean): boolean {
+  const [fits, setFits] = useState(fallback);
+
+  useLayoutEffect(() => {
+    const el = block.current;
+    if (!el || typeof ResizeObserver === 'undefined') return undefined;
+    const measure = (): void => {
+      const full = el.querySelector<HTMLElement>('[data-dr-text="full"]');
+      if (!full) return;
+      const shown = full.style.display;
+      full.style.display = 'inline';
+      const range = el.ownerDocument.createRange();
+      range.selectNodeContents(full);
+      const width = range.getBoundingClientRect().width;
+      full.style.display = shown;
+      const style = getComputedStyle(el);
+      const room = el.clientWidth - Number.parseFloat(style.paddingLeft) - Number.parseFloat(style.paddingRight);
+      if (room > 0) setFits(width <= room + 0.5);
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [block, text]);
+
+  return fits;
+}

package/src/components/data-display/ScheduleGrid/ScheduleGrid.keyboard.ts

@@ -0,0 +1,138 @@
+import type * as React from 'react';
+
+import type { ScheduleGridLabels } from '../../../copy/labels';
+import { isOpen, stepDay } from './schedule-grid-model';
+import type { CellAbilities } from './ScheduleGrid.parts';
+import type { ScheduleGridBlock, ScheduleGridCell, ScheduleGridColumn, ScheduleGridRow } from './ScheduleGrid.types';
+
+/**
+ * THE GRID'S KEYBOARD (FUT-3825). Every empty cell's "+" and every block is a
+ * button in the tab order; on top of that:
+ * - arrows move focus to the nearest focusable cell that way;
+ * - Shift+←/→ on a copyable block copies it one day;
+ * - Alt+←/→ on a movable block moves it one day (focus follows it);
+ * either on a block that cannot do it says so (`notMovable`), a taken or
+ * closed day is refused; each is read by the live region. With Ctrl or Meta
+ * the key is not the grid's.
+ */
+export interface GridKeyContext {
+  root: HTMLElement;
+  rows: readonly ScheduleGridRow[];
+  columns: readonly ScheduleGridColumn[];
+  cell: (rowId: string, day: number) => ScheduleGridCell;
+  can: CellAbilities;
+  onCopy?: (blockId: string, days: number[]) => void;
+  onMove?: (blockId: string, toRowId: string, toDay: number) => void;
+  labels: ScheduleGridLabels;
+  say: (text: string) => void;
+  /** Wait for the block at its new day and focus it there. */
+  follow: (blockId: string, day: number) => void;
+}
+
+/** Every focusable part of the grid (empty cells' buttons and blocks). */
+export function focusables(root: HTMLElement): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>('[data-sg-focus]'));
+}
+
+/** Focus the first focusable of the cell at (`rowId`, `day`); false when it has none. */
+function focusCell(root: HTMLElement, rowId: string, day: number): boolean {
+  const target = focusables(root).find((el) => el.dataset.sgRow === rowId && Number(el.dataset.sgDay) === day);
+  target?.focus();
+  return Boolean(target);
+}
+
+interface Arrow {
+  horizontal: boolean;
+  step: -1 | 1;
+}
+
+function arrowOf(key: string): Arrow | null {
+  if (key === 'ArrowLeft') return { horizontal: true, step: -1 };
+  if (key === 'ArrowRight') return { horizontal: true, step: 1 };
+  if (key === 'ArrowUp') return { horizontal: false, step: -1 };
+  if (key === 'ArrowDown') return { horizontal: false, step: 1 };
+  return null;
+}
+
+/** Move focus `arrow`-wards to the nearest cell that has something to focus; a closed or read-only one is passed over. */
+function moveFocus(ctx: GridKeyContext, from: HTMLElement, arrow: Arrow): boolean {
+  const rowIndex = ctx.rows.findIndex((row) => row.id === from.dataset.sgRow);
+  const day = Number(from.dataset.sgDay);
+  if (rowIndex < 0) return false;
+  for (let distance = 1; ; distance += 1) {
+    const offset = arrow.step * distance;
+    const nextDay = arrow.horizontal ? day + offset : day;
+    const row = ctx.rows[arrow.horizontal ? rowIndex : rowIndex + offset];
+    if (!row || nextDay < 0 || nextDay >= ctx.columns.length) return false;
+    if (focusCell(ctx.root, row.id, nextDay)) return true;
+  }
+}
+
+/** Which gesture a modified arrow asks of this block, if the grid allows it. */
+function gestureOf(event: React.KeyboardEvent, block: ScheduleGridBlock, can: CellAbilities): 'copy' | 'move' | null {
+  if (event.shiftKey && !event.altKey) return can.copy && block.copyable ? 'copy' : null;
+  if (event.altKey && !event.shiftKey) return can.move && block.movable ? 'move' : null;
+  return null;
+}
+
+/** The block a key landed on, with its row — or nothing. */
+function blockUnder(ctx: GridKeyContext, el: HTMLElement): { block: ScheduleGridBlock; row: ScheduleGridRow; day: number } | null {
+  const rowId = el.dataset.sgRow ?? '';
+  const day = Number(el.dataset.sgDay);
+  const block = ctx.cell(rowId, day).blocks.find((entry) => entry.id === el.dataset.sgBlock);
+  const row = ctx.rows.find((entry) => entry.id === rowId);
+  return block && row ? { block, row, day } : null;
+}
+
+/** The open day one step away, with its column — or nothing past either end or on a taken / closed day. */
+function openNeighbour(ctx: GridKeyContext, rowId: string, day: number, step: -1 | 1) {
+  const target = stepDay(day, step, ctx.columns.length);
+  if (target === undefined) return null;
+  const column = ctx.columns[target];
+  return column && isOpen(ctx.cell(rowId, target)) ? { day: target, column } : null;
+}
+
+/**
+ * Shift/Alt+←/→ on a block. Returns whether the key was the grid's: a block
+ * that cannot be copied or moved that way refuses it aloud, and the key goes
+ * no further (Alt+← would otherwise be the browser's Back).
+ */
+function blockKey(ctx: GridKeyContext, el: HTMLElement, event: React.KeyboardEvent, step: -1 | 1): boolean {
+  const under = blockUnder(ctx, el);
+  if (!under) return false;
+  const gesture = gestureOf(event, under.block, ctx.can);
+  const { block, row, day } = under;
+  const target = gesture ? openNeighbour(ctx, row.id, day, step) : null;
+  if (!gesture) {
+    ctx.say(ctx.labels.notMovable);
+  } else if (!target) {
+    ctx.say(ctx.labels.refused);
+  } else if (gesture === 'copy') {
+    ctx.onCopy?.(block.id, [target.day]);
+    ctx.say(ctx.labels.copied(block.label, target.column.label));
+  } else {
+    ctx.follow(block.id, target.day);
+    ctx.onMove?.(block.id, row.id, target.day);
+    ctx.say(ctx.labels.moved(block.label, row.label, target.column.label));
+  }
+  return true;
+}
+
+/** Shift OR Alt (not both) and no Ctrl or Meta: a key the grid answers for a block, as the ruler does. */
+const isBlockGesture = (event: React.KeyboardEvent): boolean =>
+  event.shiftKey !== event.altKey && !event.ctrlKey && !event.metaKey;
+
+const hasModifier = (event: React.KeyboardEvent): boolean => event.shiftKey || event.altKey || event.ctrlKey || event.metaKey;
+
+/** The grid's `onKeyDown`. */
+export function handleGridKey(event: React.KeyboardEvent, ctx: GridKeyContext): void {
+  const el = (event.target as HTMLElement).closest<HTMLElement>('[data-sg-focus]');
+  const arrow = arrowOf(event.key);
+  if (!el || !arrow) return;
+  const onBlock = el.dataset.sgBlock !== undefined;
+  if (onBlock && arrow.horizontal && isBlockGesture(event)) {
+    if (blockKey(ctx, el, event, arrow.step)) event.preventDefault();
+    return;
+  }
+  if (!hasModifier(event) && moveFocus(ctx, el, arrow)) event.preventDefault();
+}

package/src/components/data-display/ScheduleGrid/ScheduleGrid.md

@@ -0,0 +1,140 @@
+# ScheduleGrid
+
+People (or any resource) as **rows**, days as **columns**, and **blocks** with a start and an
+end in the cells — the week grid of a staff schedule (FUT-3825, Turnos prototype D). The grid
+reports gestures; the hours, weekly limits, refusals and toasts are the host's.
+
+```
+            Hoje · Seg 19/10   Ter 20/10      Qua 21/10              horas
+            1 turno            1 turno        1 turno
+ENTREGAS
+Luiz        [20:39–00:00   ]   [   +   ]      [   +   ]               3h15
+            [Atrasado      ]
+Kelly       [Em turno      ]   [   +   ]      [|11:00–15:00   |]      4h
+            [desde 08:26   ]                  [|↻ toda semana |]
+```
+
+**When to use it.** A week (or any short run of days) of people × days where a person places,
+copies and moves blocks by hand. **Not** `Calendar` (it picks dates) and **not** `Timeline` (it
+lists events on one axis). For one day by the hour, or for a phone, use `DayRuler`.
+
+## Gestures
+
+| gesture | pointer (mouse, pen) | keyboard | reports |
+|---|---|---|---|
+| create one day | click an empty cell | Enter on its "+" | `onCreate(rowId, [day])` |
+| create several | drag across cells of ONE row | — | `onCreate(rowId, days)` — the crossed days that are empty and not blocked |
+| copy | drag a block's left or right edge grip along its row | Shift+← / Shift+→ | `onCopy(blockId, days)` — never its own day, a taken or a blocked one |
+| move | drag a block's middle to another cell (any row) | Alt+← / Alt+→ | `onMove(blockId, toRowId, toDay)` — only onto an empty, open cell |
+| open | click a block | Enter | `onBlockClick(blockId)` |
+| focus | — | ← → ↑ ↓ to the nearest cell with something to focus | — |
+
+- **Touch never drags** (`pointerType: 'touch'`): the page scrolls; a tap is still a click.
+- While a create or copy drag runs, each target cell is drawn dashed with the hours as ghost
+  text (`createPreview(rowId)` for a create, the block's `label` for a copy); while a move
+  runs, the cell under the pointer is highlighted.
+- A drag that is released anywhere — inside the grid or outside it — commits. **Escape**, the
+  window losing focus, or a move with no button down (released where the page could not see it)
+  abandons it: nothing is reported, the ghost and the highlight go, and the click that release
+  leaves behind is ignored. Only that click is: the next click on any block opens it.
+- A keyboard copy or move, and a refusal (taken, closed, past either end), are read by a polite
+  live region; on a block that is not `copyable` / `movable` it reads `labels.notMovable` ("Este
+  turno não muda por aqui"). With Ctrl or Meta held the keys are not the grid's. After a keyboard move, focus follows the block to its new cell once the host
+  re-renders it there; after a create on a "+" (Enter, Space or a click), focus moves to the
+  block the host renders in that cell, so the arrows go on from there (after a click, without
+  scrolling). A host that renders nothing there keeps focus where it was.
+
+## Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `columns` | `ScheduleGridColumn[]` | `label` (wraps to a second line when its column is short, never cut, and never between a word and the number after it: "Seg 19/10" stays whole; also in `title`), `sublabel?`, `today?` (label in the primary colour, cells framed). A day is its index here. |
+| `groups` | `ScheduleGridGroup[]` | `title?` (upper-case heading, names the row group), `rows`: `id`, `label`, `meta?`, `metaTone?` (`'warning'` for "acima de 40h"), `total?`, `onLabelClick?` (makes the name a button), `labelAccessible?`, `nameAdornment?` (node beside the name — a "Freela" tag; it moves under the name when the column has no room for both), `chips?` (node under the meta — "2 regras ›"; one line, a chip that does not fit shrinks and cuts its label). |
+| `cell` | `(rowId, day) => ScheduleGridCell` | `blocks` (`id`, `label`, `note?`, `tone`, `movable?`, `copyable?`, `selected?`, `title?`, `breakSpan?` — `{ start, end }` as fractions 0…1 of the block, a meal break drawn as a hatched gap; its words go in `note`), `blocked?` (hatched, refuses create and drop), `blockedLabel?`. Called for every cell on each render: keep it cheap. |
+| `totalLabel` | `string?` | The last column's header ("horas"). |
+| `readOnly` | `boolean?` | No "+", no grips, no drag; empty cells are not focusable. Block clicks still reach `onBlockClick`. |
+| `onCreate` / `onCopy` / `onMove` / `onBlockClick` | see Gestures | Each gesture is offered only when its handler is given. |
+| `createPreview` | `(rowId) => string` | The ghost text a create drag shows (the person's last hours). |
+| `loading` | `boolean?` | Header + skeleton rows, `aria-busy`, nothing to press. |
+| `error` | `ReactNode?` | Replaces the body (an `ErrorState` with its retry). |
+| `empty` | `ReactNode?` | Shown when there are no rows at all. |
+| `stickyTop` | `number?` (px, default 0) | Offset of the sticky header row under a pinned page bar. |
+| `aria-label` | `string?` | The grid's name. |
+| `labels` | `Partial<ScheduleGridLabels>` | `createCell(row, column)`, `blockedCell(row, column)`, `copied(block, column)`, `moved(block, row, column)`, `refused`, `loading`. Default: the English pack; a pt-BR host passes `UI_LABELS['pt-BR'].scheduleGrid`. |
+| `dataTestId` | `string?` (default `schedule-grid`) | Parts: `-header`, `-row-${rowId}`, `-cell-${rowId}-${day}`, `-block-${blockId}`, `-grip-l-${blockId}`, `-grip-r-${blockId}`, `-break-${blockId}`, `-live`, `-loading`. |
+
+### Tones — never colour alone
+
+| `tone` | drawn | its `note` carries |
+|---|---|---|
+| `plan` | raised chip, neutral border | "↻ toda semana", "↻ a cada 2 semanas" |
+| `late` | solid warning | "Atrasado" |
+| `away` | dashed warning outline | "Ausente" |
+| `uncovered` | dashed warning outline | "Sem ninguém" |
+| `onduty` | soft success ground, success border | "desde 08:26" |
+
+### Breaks and row adornments
+
+A block's `breakSpan` is drawn as a band of diagonal stripes in the page's ground across the
+block's height, under its text, so the block reads as cut there in every tone; it is decorative
+(`aria-hidden`), and the block's `note` says it in words ("pausa 14:00–15:00"). Values outside
+0…1 are clamped to the block; a span that is empty or reversed (`end <= start`) draws nothing. A row's
+`nameAdornment` and `chips` are the host's nodes (an `@12-apps/ui` `Chip` fits): the grid only
+places them.
+
+## Layout
+
+- Name column 200px · the day columns share the rest equally (`minmax(0, 1fr)`) · total 56px;
+  6px gaps. Cells at least 56px tall; a cell's blocks stack (a split shift is two blocks).
+- A block's hours (`label`) stay on one line (an ellipsis at worst, the full text in `title`);
+  its `note` wraps to a second line when it is long and the block grows taller, as the
+  prototype's "↻ a cada 2 / semanas": a note is never cut, so a break keeps its end.
+- The header row is `position: sticky` (opaque, `background.default`) — it stays at the top of
+  whatever scrolls the grid.
+- A row's name and meta take at most two lines each (the rest cut, the whole text in `title`); a
+  closed day's `blockedLabel` stays on one line inside its cell, cut with an ellipsis.
+- **Container queries, not media queries; every bound is "from that width up".** The bounds come
+  from the grid's own columns (for a week with totals they fall at 1032px and 914px):
+  - while 200px names, days of at least 104px, the 56px total and the gaps fit: the computer frame
+    — a block's hours whole beside its edge grips; a long note wraps;
+  - while 140px names, days of at least 98px (their text 9px off each edge) and a 40px total fit:
+    the same, unscrolled, grips kept, the header row sticking to the page — a 1280 laptop beside
+    the admin's rail and panel, even with an always-visible scrollbar (923px);
+  - below that: days of at least 152px, grips kept, every hours and note line whole; the days
+    scroll sideways under the pinned names, and the header row — outside that scroller — still
+    sticks to the page and follows the days sideways. The header row is no scroller of its own
+    (`overflow-x: hidden`, so it is never a tab stop): the grid sets its scroll from the days',
+    and a sideways wheel or trackpad swipe over it scrolls the days;
+  - below 600px: 120px names, days of at least 136px, no grips (Shift+arrows still copy; the
+    middle still moves).
+  Never a coloured sliver, never cut hours, and the page itself never scrolls sideways — whatever
+  the number of days.
+- **The grid is the computer and tablet view.** On a phone, render `DayRuler` for one day at a
+  time (the approved prototype, d11-phone); the sideways scroll is the grid's fallback in a
+  narrow pane, not a phone layout.
+
+## Accessibility
+
+`role="table"` with `rowgroup` / `row` / `columnheader` / `rowheader` / `cell`; the table holds
+rows only, so the host's `error` and `empty` nodes sit in one full-width row's cell. Every empty
+cell's "+" and every block is a native `<button>` (Tab, Enter, Space); blocks declare their
+shortcuts in `aria-keyshortcuts`, and the `selected` block is `aria-current="true"`. A blocked
+cell is named by `blockedLabel` (or `labels.blockedCell`). The live region is `role="status"`,
+polite, and stays mounted: each sentence clears it and is written on the next frame, so the
+same sentence twice is read twice.
+
+A cell or block the **keyboard** focuses is brought fully into view (WCAG 2.4.11): out from
+under the pinned names, in from past the days' right edge with its 3px focus ring, and down
+from under the sticky header row (the page, or the nearest vertical scroller, scrolls). The
+browser counts a target under a sticky column or header as already in view, so the grid does
+it. A pointer press or a tap is left where it is: scrolling then would move the cell out from
+under the pointer and lose the click.
+
+Every tone's text reads at 4.5:1 on its ground in light and dark mode: the `late` block keeps
+`warning.contrastText` when it reads on `warning.main` and takes the page's dark ink otherwise;
+`away`, `uncovered` and a `warning` meta line deepen the warning step until they read.
+
+## Related
+
+`DayRuler` (the same blocks, one day by the hour), `SequenceResolver` (the problems a late, absent
+or uncovered block opens).

package/src/components/data-display/ScheduleGrid/ScheduleGrid.metrics.ts

@@ -0,0 +1,75 @@
+/**
+ * THE WEEK GRID'S NUMBERS — the approved prototype's (FUT-3823, frame d01 at
+ * 1280), in px. The web reads them through `rem`/`sxRem` so a density mode
+ * scales them.
+ */
+export const SCHEDULE_GRID_METRICS = {
+  /**
+   * The name column: 200px on a wide computer; 140px on a narrow one and while
+   * the days scroll (a long name or meta still takes two lines, never three);
+   * 120px on a phone-sized pane.
+   */
+  nameColumn: { wide: 200, compact: 140, narrow: 120 },
+  /**
+   * The narrowest a day column gets, per layout (see `layoutsOf` in the
+   * styles, which derives each layout's minimum container from these):
+   * - `wide`: with its edge grips, the hours whole ("20:39–00:00" is 67px);
+   *   a long note wraps to a second line (the block grows), as the
+   *   prototype's `.wb .note` does ("↻ a cada 2 / semanas");
+   * - `compact`: the same, the block's text 9px off each edge
+   *   (`blockPadding.tight`), clear of the grips' bars;
+   * - `scrolled`: the days scroll sideways under the pinned names, grips kept,
+   *   every hours and note line whole (the longest note, "↻ a cada 2
+   *   semanas", is 113px; 152 − 24 − 12 is 116);
+   * - `narrow`: a phone-sized pane, no grips, the same.
+   * Never slivers, never cut hours.
+   */
+  dayMin: { wide: 104, compact: 98, scrolled: 152, narrow: 136 },
+  /** The total column ("18h"). */
+  totalColumn: { wide: 56, compact: 40 },
+  /** Below this container width the pane is phone-sized: no grips (a phone renders DayRuler per day). */
+  narrowBelow: 600,
+  /** Between columns and between rows. */
+  gap: 6,
+  cellMinHeight: 56,
+  cellRadius: 8,
+  cellPadding: 4,
+  /** Between two blocks of one cell (a split shift). */
+  blockGap: 4,
+  blockRadius: 6,
+  /** Inside a block: room for the grips on both sides. */
+  blockPadding: { y: 4, start: 10, end: 14, tight: 9 },
+  blockFont: 12,
+  /** The edge grip's hit area and its bar. */
+  grip: { width: 12, barWidth: 3, barHeight: 16, barRadius: 2 },
+  /** The selected block's ring, and every focus ring. */
+  ring: 2,
+  /** How far a block's focus ring stands off it. */
+  ringOffset: 1,
+  /** A wheel that counts in lines (`deltaMode` 1), forwarded from the header: px per line. */
+  wheelLine: 16,
+  /** The dashed outline of a cell a create or copy will land on. */
+  targetBorder: 1.5,
+  headerLabel: 13,
+  headerSublabel: 13,
+  rowName: 14,
+  rowMeta: 13,
+  groupTitle: 12,
+  total: 13,
+  plusIcon: 16,
+  /** Skeleton rows while loading. */
+  skeletonRows: 4,
+  /** The hatch of a blocked cell: stripe width. */
+  hatch: 6,
+  /** The hatch of a break inside a block: stripe width. */
+  breakStripe: { ink: 2, gap: 3 },
+} as const;
+
+/**
+ * THE NAME COLUMN'S NUMBERS, shared by the week grid and the day ruler
+ * (`ScheduleNameCell`): the name as a button. In px.
+ */
+export const SCHEDULE_NAME_METRICS = {
+  button: { minHeight: 24, radius: 4, ringOffset: 2, hitArea: 40 },
+  ring: 2,
+} as const;