@12-apps/ui 6.86.1 → 6.87.0

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

@@ -0,0 +1,386 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import type { CSSObject } from '@mui/material/styles/index.js';
+
+import { rem, sxRem } from '../../../tokens/relative';
+import { SCHEDULE_GRID_METRICS as M } from './ScheduleGrid.metrics';
+import { blockToneStyles, breakHatch } from './schedule-tones';
+import type { ScheduleBlockTone } from './ScheduleGrid.types';
+
+/**
+ * The grid's root: the container the column widths answer to (container
+ * queries, never media queries — the grid may sit in a narrow pane).
+ */
+export const rootSx: SxProps<Theme> = { containerType: 'inline-size', minWidth: 0, width: '100%' };
+
+/** The columns a row has: the name, the days, the total (when there is one). */
+function trackCount(dayCount: number, hasTotal: boolean): number {
+  return 1 + dayCount + (hasTotal ? 1 : 0);
+}
+
+/**
+ * The narrowest container a layout fits in, in px: its name column, its days
+ * at their minimum, its total, and the gaps between them — for THIS grid's
+ * day count, so a fortnight scrolls where a week still fits.
+ */
+function fitsFrom(dayCount: number, hasTotal: boolean, name: number, day: number, total: number): number {
+  return name + dayCount * day + (hasTotal ? total : 0) + (trackCount(dayCount, hasTotal) - 1) * M.gap;
+}
+
+/** `@container (width < px)`: every bound is "from px up" (ranges are exclusive below, inclusive above). */
+function below(theme: Theme, px: number): string {
+  return `@container (width < ${rem(theme, px)})`;
+}
+
+/**
+ * The column widths, as variables every row reads, by the container's width:
+ * - from `wide` up: 200px names, days of at least 104px with their grips;
+ * - from `compact` up: 140px names, 40px total, days of at least 98px — still
+ *   unscrolled, grips kept, the header row sticking to the page;
+ * - below `compact`: days of at least 152px, grips kept; the body scrolls
+ *   sideways under the pinned names and the header row follows it sideways
+ *   while it still sticks to the page (`useSidewaysScroll` sets its scroll);
+ * - below 600px: 120px names, 136px days, no grips.
+ * The `wide` and `compact` bounds come from this grid's own day count
+ * (`fitsFrom`). Container queries, never media queries.
+ */
+export function frameSx(dayCount: number, hasTotal: boolean): SxProps<Theme> {
+  return (theme: Theme) => {
+    const terms = ['var(--sg-name)', `${dayCount} * var(--sg-day)`, `${trackCount(dayCount, hasTotal) - 1} * ${rem(theme, M.gap)}`];
+    if (hasTotal) terms.push('var(--sg-total)');
+    const wide = fitsFrom(dayCount, hasTotal, M.nameColumn.wide, M.dayMin.wide, M.totalColumn.wide);
+    const compact = fitsFrom(dayCount, hasTotal, M.nameColumn.compact, M.dayMin.compact, M.totalColumn.compact);
+    return {
+      '--sg-name': rem(theme, M.nameColumn.wide),
+      '--sg-total': rem(theme, M.totalColumn.wide),
+      '--sg-day': rem(theme, M.dayMin.wide),
+      // What every row is at least: its own columns at their minimums.
+      '--sg-min': `calc(${terms.join(' + ')})`,
+      [below(theme, wide)]: {
+        '--sg-name': rem(theme, M.nameColumn.compact),
+        '--sg-total': rem(theme, M.totalColumn.compact),
+        '--sg-day': rem(theme, M.dayMin.compact),
+        '& [data-sg-block]': { paddingLeft: rem(theme, M.blockPadding.tight), paddingRight: rem(theme, M.blockPadding.tight) },
+      },
+      [below(theme, compact)]: {
+        '--sg-day': rem(theme, M.dayMin.scrolled),
+        '& [data-sg-block]': {
+          paddingLeft: rem(theme, M.blockPadding.start),
+          paddingRight: rem(theme, M.blockPadding.end),
+        },
+        // A cell the keyboard reaches is brought out beside the pinned names, never under them.
+        '& > [data-sg-scroll]': {
+          overflowX: 'auto',
+          overscrollBehaviorX: 'contain',
+          scrollPaddingInlineStart: `calc(var(--sg-name) + ${rem(theme, M.gap)})`,
+        },
+        // The header row follows the days sideways (the grid sets its scroll). It is no scroller of
+        // its own: a scroller with nothing focusable inside is a tab stop of its own.
+        // `contain` still holds on a hidden overflow: a sideways swipe over the header is never the
+        // browser's back / forward gesture.
+        '& > [data-sg-head]': { overflowX: 'hidden', overscrollBehaviorX: 'contain' },
+        // The pinned column: the names (and the cell above them, and the group
+        // titles) stay while the days scroll under them.
+        '& [role="rowheader"], & [data-sg-corner]': {
+          position: 'sticky',
+          left: 0,
+          zIndex: 2,
+          backgroundColor: theme.palette.background.default,
+          // Covers the gap after it too, so nothing scrolling shows between the name and the days.
+          boxShadow: `${rem(theme, M.gap)} 0 0 ${theme.palette.background.default}`,
+        },
+        '& [data-sg-group-title]': { position: 'sticky', left: 0, width: 'fit-content' },
+      },
+      [below(theme, M.narrowBelow)]: {
+        '--sg-name': rem(theme, M.nameColumn.narrow),
+        '--sg-day': rem(theme, M.dayMin.narrow),
+        // A phone-sized pane is read and tapped, not dragged (a phone renders
+        // DayRuler per day): the grips would eat the block (Shift+arrows still copy).
+        '& [data-sg-grip]': { display: 'none' },
+        '& [data-sg-block]': { paddingLeft: rem(theme, M.cellPadding), paddingRight: rem(theme, M.cellPadding) },
+      },
+      display: 'flex',
+      flexDirection: 'column',
+      minWidth: 0,
+      userSelect: 'none',
+    };
+  };
+}
+
+/** The body: scrolls sideways (under the compact bound) when the days' minimums do not fit. */
+export const scrollSx: SxProps<Theme> = { minWidth: 0 };
+
+/** One line of the grid — the header or a person — as the shared columns. */
+/** A style that may sit in an `sx` array next to another. */
+type SxPart = (theme: Theme) => CSSObject;
+
+export function rowGridSx(dayCount: number, hasTotal: boolean): SxPart {
+  return (theme: Theme) => ({
+    display: 'grid',
+    gridTemplateColumns: `var(--sg-name) repeat(${dayCount}, minmax(var(--sg-day), 1fr))${hasTotal ? ' var(--sg-total)' : ''}`,
+    gap: rem(theme, M.gap),
+    alignItems: 'stretch',
+    minWidth: 'var(--sg-min)',
+  });
+}
+
+/**
+ * Around the header row: opaque, pinned to the top of the PAGE (or whatever
+ * scrolls the grid vertically) — it is not inside the sideways scroller, so
+ * it sticks at every width; while the days scroll it follows them sideways.
+ */
+export function headerSx(stickyTop: number): SxPart {
+  return (theme: Theme) => ({
+    position: 'sticky',
+    top: rem(theme, stickyTop),
+    zIndex: 3,
+    backgroundColor: theme.palette.background.default,
+  });
+}
+
+/** The header row itself, inside its sticky frame. */
+export const headerRowSx: SxPart = (theme: Theme) => ({
+  paddingTop: theme.spacing(0.75),
+  paddingBottom: theme.spacing(0.75),
+});
+
+export function headerCellSx(today: boolean): SxProps<Theme> {
+  return {
+    fontSize: sxRem(M.headerLabel),
+    fontWeight: 500,
+    color: today ? 'primary.main' : 'text.primary',
+    p: 0.5,
+    minWidth: 0,
+    // A long label ("Hoje · Seg 19/10") wraps to a second line, as the prototype's: never cut.
+    '& > *': { display: 'block', overflowWrap: 'anywhere' },
+  };
+}
+
+export const headerSublabelSx: SxProps<Theme> = {
+  fontSize: sxRem(M.headerSublabel),
+  fontWeight: 400,
+  color: 'text.secondary',
+};
+
+export const totalHeaderSx: SxProps<Theme> = {
+  fontSize: sxRem(M.total),
+  color: 'text.secondary',
+  textAlign: 'right',
+  alignSelf: 'end',
+  p: 0.5,
+  pr: 0,
+};
+
+export const groupTitleSx: SxProps<Theme> = {
+  fontSize: sxRem(M.groupTitle),
+  letterSpacing: '0.05em',
+  textTransform: 'uppercase',
+  color: 'text.secondary',
+  fontWeight: 500,
+  pt: 1.5,
+  pb: 0.5,
+  m: 0,
+};
+
+/** A person's line: one grid row, then the gap below it. */
+export const personRowSx: SxPart = (theme: Theme) => ({ marginBottom: rem(theme, M.gap) });
+
+export const nameCellSx: SxProps<Theme> = {
+  display: 'flex',
+  flexDirection: 'column',
+  justifyContent: 'center',
+  pr: 0.5,
+  minWidth: 0,
+};
+
+export const totalCellSx: SxProps<Theme> = {
+  fontSize: sxRem(M.total),
+  color: 'text.secondary',
+  textAlign: 'right',
+  alignSelf: 'center',
+  whiteSpace: 'nowrap',
+};
+
+/** What a cell is drawing right now. */
+export interface CellLook {
+  today: boolean;
+  blocked: boolean;
+  /** A create or copy will land here: dashed, with the hours as ghost text. */
+  target: boolean;
+  /** The pointer is over it while a block moves. */
+  over: boolean;
+  /** The cell's own "+" button may be pressed. */
+  interactive: boolean;
+}
+
+function hatch(theme: Theme): string {
+  const a = theme.palette.action.hover;
+  const b = theme.palette.action.selected;
+  const w = rem(theme, M.hatch);
+  const w2 = rem(theme, M.hatch * 2);
+  return `repeating-linear-gradient(135deg, ${a} 0, ${a} ${w}, ${b} ${w}, ${b} ${w2})`;
+}
+
+export function cellSx(look: CellLook): SxProps<Theme> {
+  return (theme: Theme): CSSObject => {
+    const base: CSSObject = {
+      position: 'relative',
+      minHeight: rem(theme, M.cellMinHeight),
+      borderRadius: rem(theme, M.cellRadius),
+      backgroundColor: theme.palette.action.hover,
+      border: `1px solid ${look.today ? theme.palette.primary.main : theme.palette.divider}`,
+      padding: rem(theme, M.cellPadding),
+      display: 'flex',
+      flexDirection: 'column',
+      gap: rem(theme, M.blockGap),
+      boxSizing: 'border-box',
+      minWidth: 0,
+      cursor: look.interactive ? 'cell' : 'default',
+    };
+    if (look.blocked) {
+      return { ...base, background: hatch(theme), borderColor: theme.palette.divider, cursor: 'not-allowed' };
+    }
+    if (look.target) {
+      return {
+        ...base,
+        border: `${rem(theme, M.targetBorder)} dashed ${theme.palette.primary.main}`,
+        backgroundColor: theme.palette.action.selected,
+      };
+    }
+    if (look.over) return { ...base, borderColor: theme.palette.primary.main, backgroundColor: theme.palette.action.selected };
+    return base;
+  };
+}
+
+/** The empty cell's button: the whole cell, a quiet "+" in its middle. */
+export const plusButtonSx: SxProps<Theme> = (theme: Theme) => ({
+  flex: '1 1 auto',
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  font: 'inherit',
+  background: 'transparent',
+  border: 0,
+  p: 0,
+  m: 0,
+  color: theme.palette.text.disabled,
+  cursor: 'inherit',
+  borderRadius: rem(theme, M.cellRadius - M.cellPadding),
+  '& svg': { fontSize: rem(theme, M.plusIcon) },
+  // The "+" is swapped for the ghost on pointer down: were it the press's
+  // target, the browser would drop the click once it left the DOM.
+  '& > *': { pointerEvents: 'none' },
+  '&:hover': { color: theme.palette.text.secondary },
+  '&:focus-visible': { outline: `${rem(theme, M.ring)} solid ${theme.palette.primary.main}`, outlineOffset: 0 },
+  // A drag's ghost text sits where the prototype writes it: top left.
+  '&[data-ghost]': { justifyContent: 'flex-start', alignItems: 'flex-start' },
+});
+
+/** The ghost text of a cell a create or copy will land on. */
+export const ghostSx: SxProps<Theme> = (theme: Theme) => ({
+  fontSize: rem(theme, M.blockFont),
+  fontWeight: 500,
+  color: theme.palette.primary.main,
+  px: 0.75,
+  py: 0.5,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+});
+
+/** A closed day's word ("Afastamento"): one line inside its cell, cut with an ellipsis (the full word in `title`). */
+export const blockedLabelSx: SxProps<Theme> = (theme: Theme) => ({
+  display: 'block',
+  fontSize: rem(theme, M.blockFont),
+  color: theme.palette.text.secondary,
+  px: 0.75,
+  py: 0.5,
+  lineHeight: 1.3,
+  minWidth: 0,
+  maxWidth: '100%',
+  boxSizing: 'border-box',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+});
+
+export function blockSx(tone: ScheduleBlockTone, opts: { selected: boolean; movable: boolean }): SxProps<Theme> {
+  return (theme: Theme): CSSObject => ({
+    ...blockToneStyles(theme, tone),
+    position: 'relative',
+    display: 'block',
+    width: '100%',
+    minWidth: 0,
+    maxWidth: '100%',
+    boxSizing: 'border-box',
+    textAlign: 'left',
+    font: 'inherit',
+    fontSize: rem(theme, M.blockFont),
+    fontWeight: 500,
+    lineHeight: 1.35,
+    borderRadius: rem(theme, M.blockRadius),
+    padding: `${rem(theme, M.blockPadding.y)} ${rem(theme, M.blockPadding.end)} ${rem(theme, M.blockPadding.y)} ${rem(theme, M.blockPadding.start)}`,
+    cursor: opts.movable ? 'grab' : 'pointer',
+    margin: 0,
+    boxShadow: opts.selected ? `0 0 0 ${rem(theme, M.ring)} ${theme.palette.primary.main}` : 'none',
+    '&:focus-visible': { outline: `${rem(theme, M.ring)} solid ${theme.palette.primary.main}`, outlineOffset: rem(theme, M.ringOffset) },
+    // The hours stay on one line; the note wraps (the block grows), as the prototype's
+    // "↻ a cada 2 / semanas": a note is never cut, so a break keeps its end.
+    '& > [data-sg-line]': { position: 'relative', display: 'block' },
+    '& > [data-sg-line="label"]': { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' },
+    '& > [data-sg-line="note"]': { fontWeight: 400, overflowWrap: 'anywhere' },
+  });
+}
+
+/** A break inside a block: a hatched band across its height, under its text. */
+export function breakSx(span: { start: number; end: number }): SxProps<Theme> {
+  return (theme: Theme) => ({
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    left: `${span.start * 100}%`,
+    width: `${(span.end - span.start) * 100}%`,
+    background: breakHatch(theme, rem(theme, M.breakStripe.ink), rem(theme, M.breakStripe.ink + M.breakStripe.gap)),
+    pointerEvents: 'none',
+  });
+}
+
+export function gripSx(side: 'l' | 'r'): SxProps<Theme> {
+  return (theme: Theme) => ({
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    [side === 'l' ? 'left' : 'right']: 0,
+    width: rem(theme, M.grip.width),
+    cursor: 'ew-resize',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    '&::before': {
+      content: '""',
+      display: 'block',
+      width: rem(theme, M.grip.barWidth),
+      height: rem(theme, M.grip.barHeight),
+      borderRadius: rem(theme, M.grip.barRadius),
+      backgroundColor: 'currentColor',
+      opacity: 0.5,
+    },
+  });
+}
+
+export const skeletonCellSx: SxProps<Theme> = (theme: Theme) => ({
+  minHeight: rem(theme, M.cellMinHeight),
+  borderRadius: rem(theme, M.cellRadius),
+  backgroundColor: theme.palette.action.hover,
+});
+
+export const SR_ONLY_SX: SxProps<Theme> = {
+  position: 'absolute',
+  width: sxRem(1),
+  height: sxRem(1),
+  padding: 0,
+  margin: sxRem(-1),
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};

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

@@ -0,0 +1,142 @@
+'use client';
+
+import Box from '@mui/material/Box/index.js';
+import React, { useEffect, useRef } from 'react';
+
+import { EN_US_UI_LABELS } from '../../../en-US.labels';
+import { resolveLabels } from '../../../utils/resolve-labels';
+import { focusables, handleGridKey } from './ScheduleGrid.keyboard';
+import { GridBody, GridHeader, type CellAbilities } from './ScheduleGrid.parts';
+import { frameSx, headerSx, rootSx, rowGridSx, scrollSx, SR_ONLY_SX } from './ScheduleGrid.styles';
+import type { ScheduleGridProps } from './ScheduleGrid.types';
+import { useAnnouncer } from './useAnnouncer';
+import { useGridDrag } from './useGridDrag';
+import { useSidewaysScroll } from './useSidewaysScroll';
+
+/**
+ * After a keyboard move the host re-renders the block in its new cell (a new
+ * element): focus follows it there. After a create on an empty day's "+" (Enter,
+ * Space or a click) the "+" gives way to the host's new block: focus moves to
+ * it, so the arrows go on from there — after a click without scrolling. A host
+ * that refused keeps focus where it was; the next key or pointer press forgets
+ * the wait.
+ */
+type FollowTarget = { kind: 'move'; id: string; day: number } | { kind: 'create'; row: string; day: number; pointer: boolean };
+
+/** The empty day's "+" an event landed on, if any. */
+function plusOf(target: EventTarget): HTMLElement | null {
+  if (!(target instanceof HTMLElement)) return null;
+  const plus = target.closest<HTMLElement>('button[data-sg-focus]');
+  return plus && plus.dataset.sgBlock === undefined && plus.dataset.sgRow !== undefined ? plus : null;
+}
+
+function useFollowFocus(rootRef: React.RefObject<HTMLElement | null>) {
+  const pending = useRef<FollowTarget | null>(null);
+  useEffect(() => {
+    const follow = pending.current;
+    if (!follow || !rootRef.current) return;
+    const block = focusables(rootRef.current).find((el) =>
+      Number(el.dataset.sgDay) !== follow.day || el.dataset.sgBlock === undefined
+        ? false
+        : follow.kind === 'move'
+          ? el.dataset.sgBlock === follow.id
+          : el.dataset.sgRow === follow.row,
+    );
+    if (!block) return;
+    // After a click the cell stays where the pointer left it: no scroll at all (FUT-3825 R1).
+    block.focus(follow.kind === 'create' && follow.pointer ? { preventScroll: true } : undefined);
+    pending.current = null;
+  });
+  return {
+    follow: (id: string, day: number): void => {
+      pending.current = { kind: 'move', id, day };
+    },
+    /** A key that presses an empty day's "+" (its click creates there). */
+    followCreate: (event: React.KeyboardEvent): void => {
+      const plus = plusOf(event.target);
+      if ((event.key !== 'Enter' && event.key !== ' ') || !plus?.dataset.sgRow) return;
+      pending.current = { kind: 'create', row: plus.dataset.sgRow, day: Number(plus.dataset.sgDay), pointer: false };
+    },
+    /** A pointer click on an empty day's "+" (a key's click, `detail` 0, is the key's). */
+    followClickCreate: (event: React.MouseEvent): void => {
+      const plus = plusOf(event.target);
+      if (event.detail === 0 || !plus?.dataset.sgRow) return;
+      pending.current = { kind: 'create', row: plus.dataset.sgRow, day: Number(plus.dataset.sgDay), pointer: true };
+    },
+    forget: (): void => {
+      pending.current = null;
+    },
+  };
+}
+
+function abilitiesOf(props: ScheduleGridProps): CellAbilities {
+  const open = !props.readOnly && !props.loading;
+  return { create: open && Boolean(props.onCreate), copy: open && Boolean(props.onCopy), move: open && Boolean(props.onMove) };
+}
+
+/**
+ * People (or resources) 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).
+ *
+ * Click an empty cell to create on that day; drag across empty cells of a row
+ * to create on each; drag a block's edge grip along its row to copy it; drag
+ * its middle to move it to another day or row; click it to open it. Touch
+ * scrolls and never drags. Every gesture has a keyboard twin.
+ *
+ * The grid reports gestures; the hours, limits and refusals are the host's.
+ */
+export function ScheduleGrid(props: ScheduleGridProps): React.JSX.Element {
+  const { columns, groups, cell, onCreate, onCopy, onMove } = props;
+  const testId = props.dataTestId ?? 'schedule-grid';
+  const labels = resolveLabels(EN_US_UI_LABELS.scheduleGrid, props.labels);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const { text: announcement, say } = useAnnouncer();
+  const focus = useFollowFocus(rootRef);
+  const dragApi = useGridDrag(rootRef, { cell, onCreate, onCopy, onMove });
+  const can = abilitiesOf(props);
+  const rows = groups.flatMap((group) => group.rows);
+  const hasTotal = props.totalLabel !== undefined || rows.some((row) => row.total !== undefined);
+  const rowSx = rowGridSx(columns.length, hasTotal);
+
+  const headRef = useRef<HTMLDivElement | null>(null);
+  const bodyRef = useRef<HTMLDivElement | null>(null);
+  const sideways = useSidewaysScroll(headRef, bodyRef);
+
+  const onKeyDown = (event: React.KeyboardEvent): void => {
+    sideways.release();
+    focus.forget();
+    if (!rootRef.current) return;
+    if (can.create) focus.followCreate(event);
+    handleGridKey(event, { root: rootRef.current, rows, columns, cell, can, onCopy, onMove, labels, say, follow: focus.follow });
+  };
+
+  return (
+    <Box sx={rootSx} data-testid={testId}>
+      <Box
+        ref={rootRef}
+        role="table"
+        aria-label={props['aria-label']}
+        aria-busy={props.loading || undefined}
+        aria-description={props.loading ? labels.loading : undefined}
+        sx={frameSx(columns.length, hasTotal)}
+        onKeyDown={onKeyDown}
+        onPointerDownCapture={focus.forget}
+        onClickCapture={can.create ? focus.followClickCreate : undefined}
+      >
+        {/* The header row sits outside the sideways scroller, so it sticks to the page; it follows the days sideways. */}
+        <Box ref={headRef} role="none" sx={headerSx(props.stickyTop ?? 0)} data-sg-head="" data-testid={`${testId}-head`} onWheel={sideways.forwardWheel}>
+          <GridHeader columns={columns} totalLabel={hasTotal ? (props.totalLabel ?? '') : undefined} rowSx={rowSx} testId={testId} />
+        </Box>
+        <Box ref={bodyRef} role="none" sx={scrollSx} data-sg-scroll="" data-testid={`${testId}-scroll`} onScroll={sideways.follow}
+          onFocus={sideways.bringOut}
+          onPointerDownCapture={sideways.press}
+        >
+          <GridBody grid={props} rows={rows} rowSx={rowSx} hasTotal={hasTotal} can={can} dragApi={dragApi} labels={labels} testId={testId} />
+        </Box>
+      </Box>
+      <Box sx={SR_ONLY_SX} aria-live="polite" role="status" data-testid={`${testId}-live`}>
+        {announcement}
+      </Box>
+    </Box>
+  );
+}

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

@@ -0,0 +1,144 @@
+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;
+}
+
+/** 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;
+}
+
+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 and not blocked).
+   */
+  onCreate?: (rowId: string, days: number[]) => void;
+  /** A block's edge grip dragged along its row: the crossed days that are empty and not blocked. */
+  onCopy?: (blockId: string, days: number[]) => void;
+  /** A block's middle dropped on an empty, open cell of any row. */
+  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;
+}