Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(Schedule): month chips lead with the title (#7053)

Cindy Zhang2c5034c5fa97
diff --git a/packages/lab/src/Schedule/Schedule.spec.md b/packages/lab/src/Schedule/Schedule.spec.md
index 16dfde55cf..608803eaee 100644
--- a/packages/lab/src/Schedule/Schedule.spec.md
+++ b/packages/lab/src/Schedule/Schedule.spec.md
@@ -22,6 +22,7 @@ verified_by:
packages/lab/src/Schedule/__tests__/ScheduleTimeGridInitialPosition.a11y.chromium.spec.ts,
packages/lab/src/Schedule/__tests__/ScheduleEventPopover.a11y.chromium.spec.ts,
packages/lab/src/Schedule/__tests__/ScheduleMonthOverflow.a11y.chromium.spec.ts,
+ packages/lab/src/Schedule/__tests__/ScheduleMonthChip.a11y.chromium.spec.ts,
apps/storybook/stories/Schedule.stories.tsx,
scripts/check-knowledge.mjs,
]
@@ -44,15 +45,15 @@ system_specs: [spec:AST-002/DEC-1, spec:AST-025/DEC-1, spec:AST-027/DEC-1]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | One additive option on the time-grid view factories: `renderPopover?: (event: CalendarEvent) => ReactNode` on `createScheduleWeeklyView` and `createScheduleDayView`. `Schedule` props, `ScheduleContextValue`, and the month and list view options gain nothing; the month view's overflow control and day popover are view-owned and take no option. |
-| Behavior | In the week and day views one viewport owns both scroll axes; the day header, all-day row, and hour gutter are sticky items of the same grid as the day columns (FR1–FR3). A range that contains today opens once, one hour before now, and never moves the person's own scroll afterwards (FR4–FR6). Simultaneous events share the column side by side in a deterministic, isolated layout; nothing is covered or dropped (FR7–FR10). With `renderPopover`, each painted event with content is a native button the view renders, and the view opens one popover it owns with that content; without it, the views stay read-only (FR11–FR14). In the month view a week row paints at most three levels of chips; a busy day trades its third level for a "+N more" button that opens the view's one popover listing the whole day, so no event is dropped or painted outside its row (FR15–FR17). |
-| End-user impact | Pointer users open an event's details from the event itself; keyboard users reach and scroll the grid, open an event with Enter or Space, read its details in a dialog, and return to the event on Escape; screen-reader users get named event buttons in day groups that announce their popup, expanded state, and controlled dialog; people with classic scrollbars or narrow windows see one aligned header, gutter, and body; a week opened in the afternoon shows the afternoon; a busy month day shows how many events it hides and lists them all on press. |
-| Builder impact | Optional: build the week or day view with `renderPopover` and return the details content for an event. No migration; read-only callers change nothing. |
-| Compatibility/readiness | Additive within the experimental `@astryxdesign/lab` surface. Read-only markup is preserved apart from the keyboard-reachable viewport that `spec:AST-025` already requires, the month view's table structure, and its "+N more" button on a busy day. |
-| Review checks | Reject an activation prop or callback on `Schedule` or in the context value, trigger props or open state exposed to the caller, a Popover prop passed through the view option (padding, placement, width, controlled state, dismissal), a close or controls argument to `renderPopover`, a popover instance per event, a button that opens nothing, a render prop that replaces the event's painted content, a rank/priority/`isShared` field, an `initialScroll` prop, a second scroll container inside the time grid, JavaScript scrollbar-width constants, inter-block `z-index` or any page-level stacking band, focusable nodes inside the hidden read-only grid, a scroll that re-runs on data refresh or theme change, a month chip painted outside its week row, a month event neither painted nor counted, a month week row that grows, a "+N more" that is not a native button or opens nothing, a second month popover, a month `grid` role, `aria-readonly`, or arrow-key promise, and a caller option for month overflow. |
-| Governing rules | `spec:AST-002` FR1–FR4, FR10 (admission and independently correct states); `spec:AST-025` FR2, FR12, FR14, FR15, FR18 (one explicit owner, keyboard access, chaining, native scrollbars, deterministic nesting); `spec:AST-027` FR1–FR6 (local stacking inside an isolation owner); `component:Popover` (the dialog surface, its padding, dismissal, and focus behaviour). |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | One additive option on the time-grid view factories: `renderPopover?: (event: CalendarEvent) => ReactNode` on `createScheduleWeeklyView` and `createScheduleDayView`. `Schedule` props, `ScheduleContextValue`, and the month and list view options gain nothing; the month view's overflow control and day popover are view-owned and take no option. |
+| Behavior | In the week and day views one viewport owns both scroll axes; the day header, all-day row, and hour gutter are sticky items of the same grid as the day columns (FR1–FR3). A range that contains today opens once, one hour before now, and never moves the person's own scroll afterwards (FR4–FR6). Simultaneous events share the column side by side in a deterministic, isolated layout; nothing is covered or dropped (FR7–FR10). With `renderPopover`, each painted event with content is a native button the view renders, and the view opens one popover it owns with that content; without it, the views stay read-only (FR11–FR14). In the month view a week row paints at most three levels of chips; a busy day trades its third level for a "+N more" button that opens the view's one popover listing the whole day, so no event is dropped or painted outside its row (FR15–FR17). Month chips lead with the title (FR18). |
+| End-user impact | Pointer users open an event's details from the event itself; keyboard users reach and scroll the grid, open an event with Enter or Space, read its details in a dialog, and return to the event on Escape; screen-reader users get named event buttons in day groups that announce their popup, expanded state, and controlled dialog; people with classic scrollbars or narrow windows see one aligned header, gutter, and body; a week opened in the afternoon shows the afternoon; a busy month day shows how many events it hides and lists them all on press, and month chips name the event before its time. |
+| Builder impact | Optional: build the week or day view with `renderPopover` and return the details content for an event. No migration; read-only callers change nothing. |
+| Compatibility/readiness | Additive within the experimental `@astryxdesign/lab` surface. Read-only markup is preserved apart from the keyboard-reachable viewport that `spec:AST-025` already requires, the month view's table structure, and its "+N more" button on a busy day. |
+| Review checks | Reject an activation prop or callback on `Schedule` or in the context value, trigger props or open state exposed to the caller, a Popover prop passed through the view option (padding, placement, width, controlled state, dismissal), a close or controls argument to `renderPopover`, a popover instance per event, a button that opens nothing, a render prop that replaces the event's painted content, a rank/priority/`isShared` field, an `initialScroll` prop, a second scroll container inside the time grid, JavaScript scrollbar-width constants, inter-block `z-index` or any page-level stacking band, focusable nodes inside the hidden read-only grid, a scroll that re-runs on data refresh or theme change, a month chip painted outside its week row, a month event neither painted nor counted, a month week row that grows, a "+N more" that is not a native button or opens nothing, a second month popover, a month `grid` role, `aria-readonly`, or arrow-key promise, a month chip whose time precedes or truncates its title, and a caller option for month overflow. |
+| Governing rules | `spec:AST-002` FR1–FR4, FR10 (admission and independently correct states); `spec:AST-025` FR2, FR12, FR14, FR15, FR18 (one explicit owner, keyboard access, chaining, native scrollbars, deterministic nesting); `spec:AST-027` FR1–FR6 (local stacking inside an isolation owner); `component:Popover` (the dialog surface, its padding, dismissal, and focus behaviour). |
This table is a review projection; the body below is authoritative.
@@ -80,9 +81,10 @@ event. Interaction is a property of a view, not of Schedule.
in three ways that no caller can observe through API: initial scroll
position when the range contains today, side-by-side placement of
simultaneous events, and one scroll owner with sticky header, all-day row,
- and gutter. The month view's default changes in two ways: its accessible
- structure is a table rather than a read-only grid, and a day with more
- events than three levels shows two chips and a "+N more" button.
+ and gutter. The month view's default changes in three ways: its accessible
+ structure is a table rather than a read-only grid, a day with more
+ events than three levels shows two chips and a "+N more" button, and a
+ chip shows its title before its time.
- Controlled/uncontrolled behavior: unchanged. `date` stays fully controlled
through `onChangeDate`; Schedule holds no selection state.
- Migration decision: none required (DEC-1 through DEC-6 are additive or
@@ -184,6 +186,7 @@ intentional decision.
| FR15 | The month view paints each event as one chip per week it covers, spanning its days in that week. Chips in a week row take levels: events are ordered by first day ascending, then all-day and multi-day events before single-day timed events, then events covering more days first, then earlier start, then title, then `id`, so a busy day keeps its earliest events; in each week it covers, an event takes the lowest level that is free on every day it covers there. The result MUST be identical for any input order of the same events. A week row paints at most three levels, keeps its height, and MUST NOT paint a chip outside its row. The month surface is an `isolation: isolate` owner; chips and a focused "+N more" rise with a local positive `z-index` inside it only. | DEC-6; `spec:AST-027` FR1–FR6 | settled |
| FR16 | Every event of a day MUST be either painted as a chip on that day or counted by that day's "+N more"; no event is dropped. When any event covering a day sits at level four or higher, that day's third level holds "+N more" instead of a chip, and N is the number of that day's events at level three or higher. A chip whose span crosses such a day is painted on its other days and counted on that one. | DEC-6 | settled |
| FR17 | "+N more" is a native `<button type="button">` inside its day's cell. Click, tap, Enter, and Space toggle the month view's one popover for that day, rendered through `component:Popover` with that component's defaults and named by the day's full date. The popover lists every event of that day in start order, each with its time range or "All day" and its title, marked with its category colour and muted once past; those events are read-only. At most one day is open at a time; activating another day's "+N more" closes the first and opens the second in the same gesture. The popover closes when it is dismissed and when its "+N more" is no longer rendered — the day no longer needs more than three levels, the range is paged, or the view is swapped — and `aria-expanded` reflects the open day and no other. | DEC-6; `component:Popover` | settled |
+| FR18 | A month chip shows the event's title first. A timed event's start time follows the title on the same line only when the whole title and the time fit in the chip; otherwise the chip shows the title alone, ellipsized. An all-day chip shows its title only. | DD5 | settled |
### Allowed variation
@@ -203,6 +206,9 @@ intentional decision.
and show the focus ring inside its column; themes vary the ring through the
shared focus tokens. The open event's button carries `aria-expanded="true"`,
so a theme may style the open state from the rendered attribute.
+- **AV6 — Month chip time.** Whether a month chip's time fits beside its whole
+ title follows the rendered text, so it varies with locale, the theme's type
+ scale, and column width.
### Representative states
@@ -231,6 +237,8 @@ intentional decision.
| Month, a day with five events, one of them a three-day event on level three | two chips and "+3 more" on that day; the three-day chip paints on its other days | which events take levels one and two |
| Month, "+N more" activated by keyboard | a dialog named by the full date lists all five events; Escape closes it and focus returns to the "+N more" button | none |
| Month, a day open, a refresh leaves that day three events | the popover closes, focus moves to that day's cell, and no dialog remains | none |
+| Month chip, long title in a 112px column | the title alone, ellipsized; no time | column width |
+| Month chip, short title in a wide column | the title, then the start time | locale |
### Transformation and precedence order
@@ -266,6 +274,8 @@ intentional decision.
- **PR4 — Pure month layout.** Level assignment and the "+N more" counts are a
pure function of the range's events and days, with no DOM reads, and run
during render.
+- **PR5 — Chip fit in CSS.** Whether a month chip's time fits beside its title
+ is decided by layout, never measured in script.
## Accessibility contract
@@ -334,7 +344,7 @@ intentional decision.
| Event block | Shows title and time in the category color; shares the column with concurrent events; with `renderPopover` it is the button that opens the event popover. | prescribed | prominent | FR7–FR12, AR2–AR3 |
| Event popover | Shows the caller's content for one event on Popover's standard surface and padding, anchored to the event's button. | prescribed | prominent | FR11–FR12, AR3 |
| Now-line | Marks the current minute on today's column, above blocks, inside the column. | prescribed | supporting | FR4, FR9 |
-| Month chip | Spans its days within a week on its level, in the category colour. | prescribed | prominent | FR15, FR16 |
+| Month chip | Shows the title first, then the start time when both fit; spans its days within a week on its level, in the category colour. | prescribed | prominent | FR15, FR16, FR18 |
| "+N more" | Stands in for a busy day's third chip, counts that day's unpainted events, and opens the day popover. | prescribed | supporting | FR16, FR17, AR7 |
| Day popover | Lists every event of one day on Popover's standard surface and padding, anchored to the day's "+N more". | prescribed | supporting | FR17, AR7 |
@@ -352,6 +362,7 @@ agent invent the answer.
| DD2 | Equal cluster columns with rightward expansion | Concurrent events read as concurrent; width is the only axis that changes and every event stays fully perceivable. | week, day | expansion into free columns |
| DD3 | Time line collapses before the title does | The title identifies the event; the time is already implied by the block's vertical position. | narrow blocks | the container-query threshold |
| DD4 | The popover keeps Popover's standard padding | Event details read as one of the system's popovers; content is semantic and never wraps itself to supply padding. | event popover | none in this record |
+| DD5 | Month chips put the title first | The title identifies the event; in a month cell the time is the detail a narrow chip drops first. | month chips | whether the time fits |
| DD6 | A busy day trades its third chip for a count | Weeks keep one height so the month still reads as a grid; the count says how much is hidden and opens the whole day. | month view | none |
## Family and system relationships
@@ -391,6 +402,7 @@ agent invent the answer.
| FR17, AR7 | `Schedule.test.tsx` month suite; `ScheduleMonthOverflow.a11y.chromium.spec.ts` | open by click and by keyboard, Escape, light dismiss, switch days, page away; LTR and RTL; light and dark | A control that is not a button, a name without the count or the date, two dialogs, a stale `aria-expanded`, focus not returning, a clipped focus ring, or a dialog left open after paging fails. | `audit:Schedule/accessibility` |
| AR7 structure | `Schedule.test.tsx` month table suite; `ScheduleMonthOverflow.a11y.chromium.spec.ts` accessibility-tree and Tab-order readings | quiet and busy months; Tab from the pager through the scroll container to each "+N more" in reading order; screen-reader names of headers, cells, and buttons; the Sunday cell's column header read as Sunday | A `grid` role or `aria-readonly`, a missing column, row, or corner header, a cell whose column header is not its weekday, a cell named without its full date, or a "+N more" outside the Tab order fails. | `audit:Schedule/accessibility` |
| FR17 close rule | `Schedule.test.tsx` month suite; `ScheduleMonthOverflow.a11y.chromium.spec.ts` refresh case | a day opened by keyboard, then a refresh leaves it three events; a day open, then the range paged | A dialog left open, a stale `aria-expanded`, focus left on the page body while the day's cell is still rendered, a cell in the Tab order, or a focused cell without the shared focus ring fails. | `audit:Schedule/behavior` |
+| FR18 | `ScheduleMonthChip.a11y.chromium.spec.ts` | long title at 800px, short title at 1280px, all-day chip, RTL | A time painted before the title, a time that truncates the title, or a time on an all-day chip fails. | `audit:Schedule/layout` |
## Decision log