@12-apps/ui 6.86.2 → 6.88.0

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

@@ -0,0 +1,164 @@
+import type * as React from 'react';
+
+import type { ScheduleGridLabels } from '../../../copy/labels';
+
+/**
+ * How a block reads. Each tone is drawn differently AND carries its `note`
+ * text, so colour is never the only signal:
+ * - `plan` — scheduled ("17:00–23:00", note "↻ toda semana");
+ * - `late` — scheduled, started, nobody there ("Atrasado");
+ * - `away` — the person said they will not come ("Ausente");
+ * - `uncovered` — nobody covers it ("Sem ninguém");
+ * - `onduty` — running right now ("Em turno", "desde 08:26").
+ */
+export type ScheduleBlockTone = 'plan' | 'late' | 'away' | 'uncovered' | 'onduty';
+
+/** One day column of the grid. */
+export interface ScheduleGridColumn {
+  /** The day ("Ter 20/10", "Hoje · Seg 19/10"). */
+  label: string;
+  /** Under the label ("3 turnos", "ninguém"). */
+  sublabel?: string;
+  /** Today's column: its label in the primary colour and its cells framed. */
+  today?: boolean;
+  /**
+   * The day has gone: its label in the secondary ink (`today` wins). The
+   * header only — the cells that can take no new turno say so themselves
+   * (`ScheduleGridCell.closed`).
+   */
+  past?: boolean;
+}
+
+/** A row: one person (or resource) across the days. */
+export interface ScheduleGridRow {
+  id: string;
+  /** The name in the first column. Wraps; never pushes the day columns. */
+  label: string;
+  /** A line under the name ("Afastamento · licença maternidade", "70h na semana · acima de 40h"). */
+  meta?: string;
+  /** `warning` draws `meta` in the warning ink (over a limit). Default `default`. */
+  metaTone?: 'default' | 'warning';
+  /** The last column ("18h", "—"). */
+  total?: string;
+  /** Makes the name a button (the person's week, an afastamento). */
+  onLabelClick?: () => void;
+  /** The name button's accessible name, when it says more than `label` ("Ana: horas e afastamento"). */
+  labelAccessible?: string;
+  /**
+   * Beside the name, on its line (a "Freela" tag). It keeps its size; when the
+   * name column has no room for both, it moves under the name.
+   */
+  nameAdornment?: React.ReactNode;
+  /** Under the meta line: the host's chips ("2 regras ›"). One line; a chip that does not fit shrinks, its label cut. */
+  chips?: React.ReactNode;
+}
+
+/** Rows under one heading ("Cozinha"). */
+export interface ScheduleGridGroup {
+  /** Shown upper-case above the rows; also names the row group. Omit for no heading. */
+  title?: string;
+  rows: ScheduleGridRow[];
+}
+
+/**
+ * A stretch inside a block that is not worked (a meal break), drawn hatched
+ * across the block's height. Fractions of the block's length, `0 <= start < end <= 1`;
+ * the words for it ("pausa 14–15") are the block's `note`.
+ */
+export interface ScheduleBlockBreak {
+  start: number;
+  end: number;
+}
+
+/** One block inside a cell. */
+export interface ScheduleGridBlock {
+  /** Stable identity — what `onMove`, `onCopy` and `onBlockClick` report. */
+  id: string;
+  /** The first line ("17:00–23:00", "Em turno"). One line, ellipsis. */
+  label: string;
+  /** The second line ("↻ toda semana", "Atrasado"). Wraps when long; never cut. */
+  note?: string;
+  tone: ScheduleBlockTone;
+  /** Its middle can be dragged to another cell (and Alt+←/→ moves it a day). */
+  movable?: boolean;
+  /** It has edge grips that copy it along its row (and Shift+←/→ copies it a day). */
+  copyable?: boolean;
+  /** Drawn with a ring (the block whose window is open). */
+  selected?: boolean;
+  /** The tooltip and the full text. Default: `label` and `note`. */
+  title?: string;
+  /** A break inside the block, drawn as a hatched gap. */
+  breakSpan?: ScheduleBlockBreak;
+}
+
+/** What a cell holds. */
+export interface ScheduleGridCell {
+  blocks: readonly ScheduleGridBlock[];
+  /**
+   * The day is closed to this row (an afastamento): hatched, refuses a
+   * create and a drop. Blocks already there still show.
+   */
+  blocked?: boolean;
+  /** Written in a blocked cell with no blocks ("Afastamento"). */
+  blockedLabel?: string;
+  /**
+   * The day can take no new turno (it has gone). No "+", the empty cell is no
+   * focus stop, a create or copy drag skips it and a move or keyboard
+   * copy/move onto it is refused — as on a `blocked` day — but with no hatch
+   * and no label: the cell just looks empty. Blocks already there still show
+   * and still open. Drawn with no fill, only the divider border.
+   */
+  closed?: boolean;
+  /**
+   * A closed cell's words for a screen reader ("Já passou"), visually hidden;
+   * nothing on screen. Without it the cell stays unnamed. Ignored on a
+   * `blocked` cell, which has its own name.
+   */
+  closedLabel?: string;
+}
+
+export interface ScheduleGridProps {
+  /** The day columns, in order (seven for a week). A day is its index here. */
+  columns: readonly ScheduleGridColumn[];
+  groups: readonly ScheduleGridGroup[];
+  /** What a cell holds. Called for every row and day on each render: keep it cheap. */
+  cell: (rowId: string, day: number) => ScheduleGridCell;
+  /** The last column's header ("horas"). Without it and without row totals, there is no last column. */
+  totalLabel?: string;
+  /**
+   * No create, copy or move: no "+", no grips, empty cells are not focusable.
+   * Block clicks still reach `onBlockClick` (a read-only window).
+   */
+  readOnly?: boolean;
+  /**
+   * A click on an empty cell (one day), or a drag across empty cells of one
+   * row (every crossed day that is empty, not blocked and not closed).
+   */
+  onCreate?: (rowId: string, days: number[]) => void;
+  /** A block's edge grip dragged along its row: the crossed days that are empty, not blocked and not closed. */
+  onCopy?: (blockId: string, days: number[]) => void;
+  /** A block's middle dropped on an empty, open cell of any row (never a blocked or closed one). */
+  onMove?: (blockId: string, toRowId: string, toDay: number) => void;
+  /** A block clicked, tapped or Entered. */
+  onBlockClick?: (blockId: string) => void;
+  /** The ghost text in the cells a create drag covers — the hours it will get ("08:00–14:00"). */
+  createPreview?: (rowId: string) => string;
+  /** Skeleton rows instead of the body, `aria-busy`, no interaction. */
+  loading?: boolean;
+  /** Replaces the body: the host's error (an `ErrorState` with its retry). */
+  error?: React.ReactNode;
+  /** Shown when there are no rows at all. */
+  empty?: React.ReactNode;
+  /** The header row sticks this far from the top of the scroll container (a sticky page bar above). Default 0. */
+  stickyTop?: number;
+  /** The grid's accessible name ("Escala da semana"). */
+  'aria-label'?: string;
+  /** The component's own words: cell names and the live region's sentences. Default: the English pack. */
+  labels?: Partial<ScheduleGridLabels>;
+  /**
+   * Base test id (default `schedule-grid`). Parts: `-header`, `-row-${rowId}`,
+   * `-cell-${rowId}-${day}`, `-block-${blockId}`, `-grip-l-${blockId}`,
+   * `-grip-r-${blockId}`, `-break-${blockId}`, `-live`, `-loading`.
+   */
+  dataTestId?: string;
+}

package/src/components/data-display/ScheduleGrid/ScheduleNameCell.tsx

@@ -0,0 +1,66 @@
+import Box from '@mui/material/Box/index.js';
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import type * as React from 'react';
+
+import { chipsSx, metaSx, nameButtonSx, nameLineSx, nameTextSx } from './schedule-name.styles';
+
+/** What a row says about its person, in both views. */
+export interface ScheduleNameRow {
+  label: string;
+  meta?: string;
+  metaTone?: 'default' | 'warning';
+  onLabelClick?: () => void;
+  labelAccessible?: string;
+  nameAdornment?: React.ReactNode;
+  chips?: React.ReactNode;
+}
+
+interface ScheduleNameCellProps {
+  row: ScheduleNameRow;
+  /** The cell's own box (where it sits in its view's row). */
+  sx: SxProps<Theme>;
+  /** `rowheader` in the week grid's table; none on the ruler. */
+  role?: string;
+  /** The view's type sizes (px) and the space above the chips (spacing units). */
+  sizes: { name: number; meta: number; chipsTop: number };
+}
+
+/**
+ * The first column of a schedule row (FUT-3825): the name (a button when the
+ * host acts on it), its adornment, its meta line and its chips — one part for
+ * the week grid and the day ruler, so a person reads the same in both.
+ */
+export function ScheduleNameCell({ row, sx, role, sizes }: ScheduleNameCellProps): React.JSX.Element {
+  const name = (
+    <Box component="span" sx={nameTextSx(sizes.name)} title={row.label}>
+      {row.label}
+    </Box>
+  );
+  const named = row.onLabelClick ? (
+    <Box component="button" type="button" sx={nameButtonSx} onClick={row.onLabelClick} aria-label={row.labelAccessible}>
+      {name}
+    </Box>
+  ) : (
+    name
+  );
+  return (
+    <Box role={role} sx={sx}>
+      {row.nameAdornment ? (
+        <Box sx={nameLineSx}>
+          {named}
+          <Box component="span" data-schedule-adornment="">
+            {row.nameAdornment}
+          </Box>
+        </Box>
+      ) : (
+        named
+      )}
+      {row.meta ? (
+        <Box component="span" sx={metaSx(row.metaTone ?? 'default', sizes.meta)} title={row.meta}>
+          {row.meta}
+        </Box>
+      ) : null}
+      {row.chips ? <Box sx={chipsSx(sizes.chipsTop)}>{row.chips}</Box> : null}
+    </Box>
+  );
+}

package/src/components/data-display/ScheduleGrid/drag-session.ts

@@ -0,0 +1,120 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * WHAT THE WEEK GRID'S AND THE DAY RULER'S DRAGS SHARE (FUT-3825): the window
+ * listeners a running drag needs, the ways to abort one, and the click a
+ * finished or aborted drag leaves behind.
+ */
+
+/** Why a drag ended without being committed. */
+export type DragAbort =
+  /** Escape pressed while dragging: the button may still be down. */
+  | 'escape'
+  /** The window lost focus (another app, a dialog): the release may never reach the page. */
+  | 'blur'
+  /** A move arrived with no button down: the release happened where the page could not see it. */
+  | 'released'
+  /** The browser took the pointer (a scroll, a system gesture). */
+  | 'pointercancel';
+
+export interface DragWindowHandlers {
+  move: (event: PointerEvent) => void;
+  /** The release, wherever it happens: a release outside the grid still commits. */
+  up: (event: PointerEvent) => void;
+  abort: (reason: DragAbort) => void;
+}
+
+/**
+ * Listen on the window while `active`: moves, the release, and the four ways a
+ * drag is abandoned. Escape is taken in the capture phase and stopped there,
+ * so a drawer or dialog around the grid does not also close on it.
+ */
+export function useDragWindow(active: boolean, handlers: DragWindowHandlers): void {
+  const latest = useRef(handlers);
+  latest.current = handlers;
+  useEffect(() => {
+    if (!active) return undefined;
+    const onMove = (event: PointerEvent): void => {
+      if (event.buttons === 0) latest.current.abort('released');
+      else latest.current.move(event);
+    };
+    const onUp = (event: PointerEvent): void => latest.current.up(event);
+    const onCancel = (): void => latest.current.abort('pointercancel');
+    const onBlur = (): void => latest.current.abort('blur');
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      event.stopPropagation();
+      latest.current.abort('escape');
+    };
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+    window.addEventListener('pointercancel', onCancel);
+    window.addEventListener('blur', onBlur);
+    window.addEventListener('keydown', onKey, true);
+    return () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      window.removeEventListener('pointercancel', onCancel);
+      window.removeEventListener('blur', onBlur);
+      window.removeEventListener('keydown', onKey, true);
+    };
+  }, [active]);
+}
+
+export interface TrailingClick {
+  /**
+   * Ignore the click this gesture leaves behind. `released`: the button is
+   * already up (a commit), so that click is in flight now; otherwise (an
+   * abort with the button still down) it follows the coming release.
+   */
+  arm: (released: boolean) => void;
+  /** A new drag starts: nothing to ignore. */
+  reset: () => void;
+  /** True once, for the click to ignore. */
+  take: () => boolean;
+}
+
+/**
+ * The click a drag leaves behind, and only that one: the flag lives until the
+ * task after the release (the browser dispatches the release's click before
+ * any task runs) and dies with the next press, so a later click on anything —
+ * a block that cannot move, another cell — is never eaten.
+ */
+export function useTrailingClick(): TrailingClick {
+  const armed = useRef(false);
+  const undo = useRef<(() => void) | null>(null);
+
+  const clear = (): void => {
+    armed.current = false;
+    undo.current?.();
+    undo.current = null;
+  };
+
+  useEffect(() => clear, []);
+
+  const arm = (released: boolean): void => {
+    clear();
+    armed.current = true;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const later = (): void => {
+      timer = setTimeout(clear, 0);
+    };
+    window.addEventListener('pointerdown', clear, true);
+    if (released) later();
+    else window.addEventListener('pointerup', later, { capture: true, once: true });
+    undo.current = () => {
+      if (timer !== undefined) clearTimeout(timer);
+      window.removeEventListener('pointerdown', clear, true);
+      window.removeEventListener('pointerup', later, true);
+    };
+  };
+
+  const take = (): boolean => {
+    const swallow = armed.current;
+    if (swallow) clear();
+    return swallow;
+  };
+
+  return { arm, reset: clear, take };
+}

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

@@ -0,0 +1,12 @@
+export { ScheduleGrid } from './ScheduleGrid';
+export type {
+  ScheduleBlockBreak,
+  ScheduleBlockTone,
+  ScheduleGridBlock,
+  ScheduleGridCell,
+  ScheduleGridColumn,
+  ScheduleGridGroup,
+  ScheduleGridProps,
+  ScheduleGridRow,
+} from './ScheduleGrid.types';
+export type { ScheduleGridLabels } from '../../../copy/labels';

package/src/components/data-display/ScheduleGrid/schedule-grid-model.ts

@@ -0,0 +1,39 @@
+import type { ScheduleGridCell } from './ScheduleGrid.types';
+
+/**
+ * THE GRID'S RULES, as pure functions (FUT-3825): which days a gesture lands
+ * on. The host decides everything else — hours, limits, refusals.
+ */
+
+/** A cell that can take a new turno: nothing in it, not closed to the row (`blocked`) and not gone (`closed`). */
+export function isOpen(cell: ScheduleGridCell): boolean {
+  return !cell.blocked && !cell.closed && cell.blocks.length === 0;
+}
+
+/** Every day from `a` to `b` inclusive, in order, whichever is larger. */
+export function daysBetween(a: number, b: number): number[] {
+  const from = Math.min(a, b);
+  const to = Math.max(a, b);
+  return Array.from({ length: to - from + 1 }, (_, index) => from + index);
+}
+
+/** A create across `anchor…current` of one row: the crossed days that are open (G-R1). */
+export function createTargets(cellOf: (day: number) => ScheduleGridCell, anchor: number, current: number): number[] {
+  return daysBetween(anchor, current).filter((day) => isOpen(cellOf(day)));
+}
+
+/** A copy of the block on `source` across `source…current`: never its own day, never a taken or closed one (G-R2). */
+export function copyTargets(cellOf: (day: number) => ScheduleGridCell, source: number, current: number): number[] {
+  return daysBetween(source, current).filter((day) => day !== source && isOpen(cellOf(day)));
+}
+
+/** A move may land on an open cell that is not its own (G-R3). */
+export function canDrop(target: ScheduleGridCell, sameCell: boolean): boolean {
+  return !sameCell && isOpen(target);
+}
+
+/** The day one step left (-1) or right (+1) of `day`, or `undefined` past either end. */
+export function stepDay(day: number, direction: -1 | 1, dayCount: number): number | undefined {
+  const next = day + direction;
+  return next >= 0 && next < dayCount ? next : undefined;
+}

package/src/components/data-display/ScheduleGrid/schedule-name.styles.ts

@@ -0,0 +1,96 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+
+import { rem } from '../../../tokens/relative';
+import { SCHEDULE_NAME_METRICS as M } from './ScheduleGrid.metrics';
+import { signalInk } from './schedule-tones';
+
+/**
+ * THE PERSON'S NAME COLUMN, shared by the week grid and the day ruler
+ * (FUT-3825): one look for the name, its adornment, its meta line and chips.
+ * Each view passes its own type sizes; everything else is the same.
+ */
+
+/** The name as a button: it reads as text, underlines under the pointer. */
+export const nameButtonSx: SxProps<Theme> = (theme: Theme) => ({
+  // A block of its content's width: an inline-block button would sit on the
+  // line's baseline and its strut would push the meta 6px down.
+  display: 'block',
+  width: 'fit-content',
+  maxWidth: '100%',
+  font: 'inherit',
+  background: 'transparent',
+  border: 0,
+  color: 'inherit',
+  p: 0,
+  textAlign: 'left',
+  cursor: 'pointer',
+  minHeight: rem(theme, M.button.minHeight),
+  borderRadius: rem(theme, M.button.radius),
+  position: 'relative',
+  // A 40px hit area around the 24px name, the look unchanged (a phone's finger).
+  '&::after': {
+    content: '""',
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: '50%',
+    height: rem(theme, M.button.hitArea),
+    transform: 'translateY(-50%)',
+  },
+  '&:hover > span': { textDecoration: 'underline' },
+  '&:focus-visible': {
+    outline: `${rem(theme, M.ring)} solid ${theme.palette.primary.main}`,
+    outlineOffset: rem(theme, M.button.ringOffset),
+  },
+});
+
+/** At most two lines, the rest cut with an ellipsis (the whole text in `title`). */
+const twoLines = {
+  display: '-webkit-box',
+  WebkitBoxOrient: 'vertical',
+  WebkitLineClamp: 2,
+  overflow: 'hidden',
+  overflowWrap: 'anywhere',
+} as const;
+
+export function nameTextSx(size: number): SxProps<Theme> {
+  return (theme: Theme) => ({ ...twoLines, fontSize: rem(theme, size), fontWeight: 500 });
+}
+
+/** The line under the name; `warning` in the signal's ink, readable on the page. */
+export function metaSx(tone: 'default' | 'warning', size: number): SxProps<Theme> {
+  return (theme: Theme) => ({
+    ...twoLines,
+    fontSize: rem(theme, size),
+    mt: 0.25,
+    color: tone === 'warning' ? signalInk(theme, 'warning', theme.palette.background.default) : theme.palette.text.secondary,
+  });
+}
+
+/** The name and its adornment: one line while both fit, the adornment under the name when not. */
+export const nameLineSx: SxProps<Theme> = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  columnGap: 0.75,
+  rowGap: 0.25,
+  minWidth: 0,
+  '& > :first-of-type': { minWidth: 0 },
+  '& > [data-schedule-adornment]': { flexShrink: 0, display: 'inline-flex' },
+};
+
+/** The host's chips under the meta: ONE line; a chip that does not fit shrinks and cuts its label. `top` in spacing units. */
+export function chipsSx(top: number): SxProps<Theme> {
+  return {
+    display: 'flex',
+    flexWrap: 'nowrap',
+    gap: 0.75,
+    mt: top,
+    minWidth: 0,
+    overflow: 'hidden',
+    // Over the name button's 40px hit area, which reaches into the space above them.
+    position: 'relative',
+    zIndex: 1,
+    '& > *': { minWidth: 0, flexShrink: 1, maxWidth: '100%' },
+  };
+}

package/src/components/data-display/ScheduleGrid/schedule-tones.ts

@@ -0,0 +1,126 @@
+import type { Theme } from '@mui/material/styles/index.js';
+import type { CSSObject } from '@mui/material/styles/index.js';
+
+import { blend, darken, decomposeColor, getContrastRatio, getLuminance, lighten } from '../../../tokens/color';
+import { fieldEdge } from '../../../tokens/field-edge';
+import { absoluteInk } from '../../../tokens/ink';
+import { softSignal, surfaces } from '../../../tokens/surfaces';
+import type { ScheduleBlockTone } from './ScheduleGrid.types';
+
+/** WCAG AA for a block's text (12px, not large): every tone's ink clears it on its ground. */
+export const TONE_TEXT_CONTRAST = 4.5;
+
+/** A translucent colour as it shows over an opaque `ground`. */
+function flatten(ground: string, overlay: string): string {
+  const { values, type } = decomposeColor(overlay);
+  const opacity = type.endsWith('a') ? (values[3] ?? 1) : 1;
+  return blend(ground, overlay, opacity);
+}
+
+/** The ground a block with no fill of its own sits on: a cell (or a track) over the page. */
+export function cellGround(theme: Theme): string {
+  return flatten(theme.palette.background.default, theme.palette.action.hover);
+}
+
+/** The first ink that reads at {@link TONE_TEXT_CONTRAST} on `ground`; none does, the one that reads best. */
+export function readableInk(ground: string, candidates: readonly string[]): string {
+  let best = candidates[0] ?? '';
+  let bestRatio = -1;
+  for (const ink of candidates) {
+    const ratio = getContrastRatio(flatten(ground, ink), ground);
+    if (ratio >= TONE_TEXT_CONTRAST) return ink;
+    if (ratio > bestRatio) [best, bestRatio] = [ink, ratio];
+  }
+  return best;
+}
+
+/** `color`, then ten steps of it towards whichever end reads on `ground` — the hue kept as long as it can be. */
+function deepening(color: string, ground: string): string[] {
+  const toward = getLuminance(ground) > LUMINANCE_MIDPOINT ? darken : lighten;
+  return Array.from({ length: 11 }, (_, step) => (step === 0 ? color : toward(color, step / 10)));
+}
+
+/** Where black and white read equally well on a ground (WCAG luminance). */
+const LUMINANCE_MIDPOINT = 0.179;
+
+/**
+ * The signal's readable ink on a ground that is not its own colour: its deep
+ * step on a light ground, its light step on a dark one, deepened further until
+ * it reads at 4.5:1 (MUI's `warning.dark` is 3.6:1 on a light cell).
+ */
+export function signalInk(theme: Theme, signal: 'warning' | 'success', ground: string): string {
+  const step = theme.palette.mode === 'dark' ? theme.palette[signal].light : theme.palette[signal].dark;
+  return readableInk(ground, deepening(step, ground));
+}
+
+/**
+ * The ink on a solid signal fill: the palette's own `contrastText` when it
+ * reads (a host's brand decision), else the page's own text, else black or
+ * white — MUI's default `warning` has white at 3.1:1 on its orange; the
+ * prototype writes it in the dark ink.
+ */
+function inkOnFill(theme: Theme, fill: string, incumbent: string): string {
+  const { black, white } = absoluteInk(theme);
+  return readableInk(fill, [incumbent, theme.palette.text.primary, black, white]);
+}
+
+/**
+ * How a block of each tone is drawn — in the week grid and on the day ruler
+ * alike, so one tone reads the same in both views. `dashedPlan` is the ruler's
+ * escala block (a dashed outline over a faint ground); the grid's plan block is
+ * a raised chip. Never colour alone: every tone also carries its note text.
+ */
+export function blockToneStyles(theme: Theme, tone: ScheduleBlockTone, dashedPlan = false): CSSObject {
+  const hairline = '1px solid';
+  switch (tone) {
+    case 'late':
+      return {
+        backgroundColor: theme.palette.warning.main,
+        color: inkOnFill(theme, theme.palette.warning.main, theme.palette.warning.contrastText),
+        border: `${hairline} ${theme.palette.warning.main}`,
+      };
+    case 'away':
+    case 'uncovered':
+      return {
+        backgroundColor: 'transparent',
+        color: signalInk(theme, 'warning', cellGround(theme)),
+        border: `1px dashed ${theme.palette.warning.main}`,
+      };
+    case 'onduty':
+      return {
+        backgroundColor: softSignal(theme, 'success'),
+        color: theme.palette.text.primary,
+        border: `${hairline} ${theme.palette.success.main}`,
+      };
+    case 'plan':
+    default:
+      return dashedPlan
+        ? {
+            backgroundColor: theme.palette.action.hover,
+            color: theme.palette.text.primary,
+            border: `1px dashed ${theme.palette.text.secondary}`,
+          }
+        : {
+            backgroundColor: surfaces(theme).raised,
+            color: theme.palette.text.primary,
+            border: `${hairline} ${fieldEdge(theme, surfaces(theme).raised)}`,
+          };
+  }
+}
+
+/**
+ * A break inside a block (a meal break): the page's own ground with diagonal
+ * stripes of the disabled action colour, opaque, so the block reads as CUT there in any
+ * tone, light or dark. `stripe` / `period` are CSS lengths (a stripe and the
+ * stripe plus its gap).
+ */
+export function breakHatch(theme: Theme, stripe: string, period: string): string {
+  const ink = theme.palette.action.disabled;
+  const ground = theme.palette.background.default;
+  return `repeating-linear-gradient(135deg, ${ink} 0, ${ink} ${stripe}, ${ground} ${stripe}, ${ground} ${period}), ${ground}`;
+}
+
+/** The thin bar under a ruler row that says the shift is really running. */
+export function actualBarColor(theme: Theme): string {
+  return theme.palette.success.main;
+}

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

@@ -0,0 +1,32 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * The live region's sentence, for the week grid and the day ruler (FUT-3825).
+ *
+ * The region stays mounted: a screen reader watches the node it found, and a
+ * region swapped for a new one per sentence is announced unreliably or not at
+ * all. Each sentence clears the region first and is written on the next frame,
+ * so the same sentence twice ("refused", "refused") is a change both times.
+ */
+export function useAnnouncer(): { text: string; say: (text: string) => void } {
+  const [text, setText] = useState('');
+  const frame = useRef<number | null>(null);
+
+  useEffect(
+    () => () => {
+      if (frame.current !== null) cancelAnimationFrame(frame.current);
+    },
+    [],
+  );
+
+  const say = useCallback((next: string): void => {
+    if (frame.current !== null) cancelAnimationFrame(frame.current);
+    setText('');
+    frame.current = requestAnimationFrame(() => {
+      frame.current = null;
+      setText(next);
+    });
+  }, []);
+
+  return { text, say };
+}