@nxgt/material 3.92.0 → 3.93.0

package/docs/components/rich-widgets.md

@@ -309,15 +309,18 @@ To edit and delete in your own dialog instead of the built-in inline fields:
 | `onEventClick` | `(event: CalendarEvent) => void` | — | an event was clicked; it runs even with `onSlotClick` set (an event click never reports a slot) |
 | `eventPreview` | `boolean` | `true` | `false` skips the preview popover, so `onEventClick` alone handles the click |
 | `previewFields` | `EventCalendarPreviewField[]` | all three | the fields the preview edits in place (`'title' \| 'color' \| 'description'`); `[]` keeps the time range and the actions |
-| `onEventEdit` | `(event: CalendarEvent) => void` | — | adds an Edit button to the preview; the app opens its own editor; hidden when the calendar or the event is `disabled` |
-| `onEventDelete` | `(event: CalendarEvent) => void` | — | the preview's delete button calls this instead of the built-in confirmation and removal; the app confirms and deletes; hidden when the calendar or the event is `disabled`, so it never runs for those |
+| `readOnlyEvents` | `boolean` | `false` | no event can be dragged, resized, moved with the keys, edited or deleted; events stay focusable, clickable and at full strength, `onSlotClick` still fires, see [Read-only events](#eventcalendar-read-only-events) |
+| `spans` | `EventCalendarSpan[]` | — | stretches of time shaded behind the events (a closure, a term, a half day off); they never block a slot, see the [guide](../guides/event-calendar.md#spans) |
+| `dayBadges` / `weekBadges` | `EventCalendarBadges` | — | a `{ label, tone? }` badge on a day, or on a week (keyed by its first day per `weekStartsOn`), see the [guide](../guides/event-calendar.md#day-and-week-badges) |
+| `onEventEdit` | `(event: CalendarEvent) => void` | — | adds an Edit button to the preview; the app opens its own editor; hidden when the calendar or the event is `disabled`, and with `readOnlyEvents` |
+| `onEventDelete` | `(event: CalendarEvent) => void` | — | the preview's delete button calls this instead of the built-in confirmation and removal; the app confirms and deletes; hidden when the calendar or the event is `disabled`, so it never runs for those, nor with `readOnlyEvents` |
 | `view` / `defaultView` | `'month' \| 'week' \| 'workweek' \| 'day' \| 'agenda'` | `'month'` | the visible view |
 | `date` / `defaultDate` | `string` | today | the date the view is centred on |
 | `startHour` / `endHour` | `number` | `0` / `24` | hours shown in the time grids |
 | `slotDurationMinutes` | `number` | `60` | grid step for creation and snapping |
 | `toolbar` | `ReactNode` | built-in | replace (or `null` to hide) the toolbar |
 | `views` | `EventCalendarView[]` | all five | the views the switcher offers, in order |
-| `weekStartsOn` | `0`–`6` | the locale's | the first day of the week |
+| `weekStartsOn` | `0`–`6` | the locale's | the first day of the week; the week view starts on it and `weekBadges` are keyed by it ([guide](../guides/event-calendar.md#weekstartson)) |
 | `density` | `'comfortable' \| 'compact'` | `'comfortable'` | compact: 40px hours, shorter month cells |
 | `eventVariant` | `'soft' \| 'solid' \| 'outline'` | `'soft'` | how events are drawn ([EventChip](data-display.md#eventchip)) |
 | `sidebar` | `boolean` | `false` | the side panel from 1024px: mini month and the day's events |
@@ -339,12 +342,40 @@ trade-off: each event stays reachable by keyboard (Tab and the arrow keys move
 through the events), and the agenda view lists every event in full, which is the
 accessible route.
 
+### EventCalendar read-only events
+
+A schedule to read and click, not to rearrange: set `readOnlyEvents`. No event
+can be dragged, resized or moved with Ctrl or Cmd and the arrow keys, and the
+preview offers no edit or delete. Each event keeps its look, its tab stop and
+`onEventClick`, empty slots still call `onSlotClick`, and no drag instruction
+is announced: the calendar is named "Event calendar" in both cases, and only a
+draggable one describes itself with "Drag event". Because `readOnlyEvents` leaves
+no edit path, it also hides the Edit button of `onEventEdit`.
+
+```tsx
+<EventCalendar
+	defaultView="day"
+	defaultDate="2026-03-12"
+	readOnlyEvents
+	onEventClick={(event) => open(event.id)}
+	onSlotClick={(slot) => book(slot.start)}
+	events={events}
+/>
+```
+
+It is not `disabled`, which locks the whole calendar (no slot click, no
+navigation), nor `CalendarEvent.disabled`, which dims one event and makes its
+button inert. Both keep their meaning; `readOnlyEvents` is React only for now
+(the Vue twin is tracked in #2526).
+
 ### EventCalendar event badge
 
 An event takes an optional `badge` (`CalendarEventBadge`: `{ label, tone? }`): a
 small tinted label that marks it, such as a category or a follow-up. `tone` is a
 tone of the library or one your app declared (neutral when omitted). The same
-prop is on [`EventChip`](data-display.md).
+prop is on [`EventChip`](data-display.md). An event also takes `tone` (its colour)
+and `status: 'cancelled'` (struck through, announced as cancelled); see
+[the EventCalendar guide](../guides/event-calendar.md#event-tone-badges-and-cancelled-events).
 
 ```tsx
 import { EventCalendar, type CalendarEvent } from '@nxgt/material/components';
@@ -372,6 +403,28 @@ const events: CalendarEvent[] = [
   in the event's accessible name. The agenda view wraps a long description
   instead of cutting it.
 
+For a status and a priority together, add `badges` (`CalendarEventBadge[]`):
+further badges drawn after `badge`, in the same places and order, all part of
+the event's accessible name (`Visit, Follow-up, Urgent, 2/3`). Each becomes its
+own tone dot where the box is narrow or short. `badges` works with or without
+`badge`.
+
+```tsx
+const events: CalendarEvent[] = [
+	{
+		id: '2',
+		title: 'Operation',
+		start: '2026-03-12T11:00:00Z',
+		end: '2026-03-12T13:00:00Z',
+		badge: { label: 'Scheduled', tone: 'info' },
+		badges: [
+			{ label: 'Urgent', tone: 'warning' },
+			{ label: '2/3', tone: 'success' },
+		],
+	},
+];
+```
+
 ### EventCalendar resources
 
 `resources` splits the **day view** into one column per room, person or team
@@ -547,7 +600,7 @@ zone's wall clock. Without it, nothing changes: the machine's clock.
 <EventCalendar view="day" date="2026-03-12" timeZone="Asia/Tokyo" events={events} />
 ```
 
-**Storybook:** `Rich widgets/EventCalendar`, `Rich widgets/EventCalendar/Layouts`, `Rich widgets/EventCalendar/Resources`, `Rich widgets/EventCalendar/Resources on a phone`, `Rich widgets/EventCalendar/Resources a11y`, `Rich widgets/EventCalendar/Time zone`, `Rich widgets/EventCalendar/Back to back`, `Rich widgets/EventCalendar/Resource tone`, `Rich widgets/EventCalendar/Hydration`, `Rich widgets/EventCalendar/Template week` · **Vue:** `EventCalendar` (the new props and layouts, `resources`, `timeZone` and `mode="template"`: React only for now, #892, #1780 and #2458)
+**Storybook:** `Rich widgets/EventCalendar`, `Rich widgets/EventCalendar/Layouts`, `Rich widgets/EventCalendar/Resources`, `Rich widgets/EventCalendar/Resources on a phone`, `Rich widgets/EventCalendar/Resources a11y`, `Rich widgets/EventCalendar/Time zone`, `Rich widgets/EventCalendar/Back to back`, `Rich widgets/EventCalendar/Resource tone`, `Rich widgets/EventCalendar/Hydration`, `Rich widgets/EventCalendar/Template week`, `Rich widgets/EventCalendar/Spans`, `Rich widgets/EventCalendar/Day and week badges`, `Rich widgets/EventCalendar/Event badge`, `Rich widgets/EventCalendar/Event tone and cancelled`, `Rich widgets/EventCalendar/Read-only events` · **Vue:** `EventCalendar` (the new props and layouts, `resources`, `timeZone` and `mode="template"`: React only for now, #892, #1780 and #2458)
 
 ---
 

package/docs/guides/event-calendar.md

@@ -0,0 +1,163 @@
+# EventCalendar: spans, badges, tones and cancelled events
+
+`EventCalendar` (`@nxgt/material/components`) shows more than events. It can
+shade what the days themselves are (a closure, a term, a half day off), put a
+short label on a day or a week, draw an event in a tone, mark one as cancelled,
+and lock the whole schedule to reading and clicking.
+
+- [Spans](#spans)
+- [Day and week badges](#day-and-week-badges)
+- [Event tone, badges and cancelled events](#event-tone-badges-and-cancelled-events)
+- [Read-only events](#read-only-events)
+- [In each view](#in-each-view)
+- [weekStartsOn](#weekstartson)
+- [Translations](#translations)
+- [Exports](#exports)
+
+## Spans
+
+`spans` shades stretches of time behind the events. A span never blocks a slot:
+events can still be made and dropped over it.
+
+```tsx
+import { EventCalendar, type EventCalendarSpan } from '@nxgt/material/components';
+
+const spans: EventCalendarSpan[] = [
+	// Whole days: date-only values, `end` is exclusive (this is 24 December only).
+	{ id: 'closed', start: '2026-12-24', end: '2026-12-25', label: 'Closed', tone: 'warning' },
+	// A range of days.
+	{ id: 'term', start: '2026-12-28', end: '2027-01-04', label: 'Break', tone: 'info' },
+	// A half day: a value with a time is an instant.
+	{ id: 'half', start: '2026-12-23T12:00:00', end: '2026-12-24', label: 'Half day' },
+];
+
+<EventCalendar defaultEvents={events} spans={spans} timeZone="Europe/Paris" />;
+```
+
+- A date-only `start` / `end` means whole days, read in the calendar's
+  `timeZone`. `end` is always exclusive.
+- `tone` is a tone of the library (default `'neutral'`).
+- With `resources`, a span with a `resourceId` shades only its column; one with
+  none shades every column; one with an unknown id shades none.
+- The shading is a thin hatch drawn with CSS classes (no inline gradient). It is
+  `aria-hidden`, takes no pointer event and no tab stop; its label is read in
+  the name of the day or column it falls on.
+- `spans` is not a prop of `mode="template"`, which has no dates.
+
+## Day and week badges
+
+`dayBadges` and `weekBadges` are records of `{ label, tone? }` keyed by a
+`YYYY-MM-DD` date.
+
+```tsx
+<EventCalendar
+	defaultEvents={events}
+	weekStartsOn={1}
+	dayBadges={{
+		'2026-12-24': { label: 'Eve', tone: 'info' },
+		'2026-12-25': { label: 'Holiday', tone: 'warning' },
+	}}
+	weekBadges={{
+		// The key is the first day of the week, per `weekStartsOn` (a Monday here).
+		'2026-12-21': { label: 'Week 52', tone: 'neutral' },
+	}}
+/>
+```
+
+A day badge is read in the name of its day (the day header, or the month cell); a
+week badge in the name of the week's first day. Where the
+room is short (a phone's week column or month cell), a badge becomes a small
+tone bar, distinct from the event dots. Neither prop exists in `mode="template"`.
+
+## Event tone, badges and cancelled events
+
+A `CalendarEvent` takes a `tone`, several `badges` and a `status`.
+
+```tsx
+const events: CalendarEvent[] = [
+	{
+		id: 'a',
+		title: 'Planning',
+		start: '2026-12-22T09:00:00',
+		end: '2026-12-22T10:00:00',
+		tone: 'success', // a `color` still wins, then the tone, then the resource's
+		badge: { label: 'Team', tone: 'info' },
+		badges: [{ label: '2/5', tone: 'neutral' }],
+	},
+	{
+		id: 'b',
+		title: 'Review',
+		start: '2026-12-22T11:00:00',
+		end: '2026-12-22T12:00:00',
+		status: 'cancelled', // struck through, muted, dashed outline; still draggable
+	},
+];
+```
+
+A cancelled event strikes its title (`<del>`) and adds "Cancelled" to its
+accessible name, so the state is never carried by style alone. The preview
+shows such an event's title struck and named the same way (and read-only, since
+its title is not an input then). `tone` and
+`badges` work in every view and in `mode="template"`. `EventChip` takes the same
+`tone`, `badges` and `cancelled`.
+
+## Read-only events
+
+`readOnlyEvents` forbids dragging, resizing, key moves, and edits or deletes
+from the preview, for every event. Events stay focusable, clickable
+(`onEventClick`) and at full strength, and `onSlotClick` still fires.
+
+```tsx
+<EventCalendar events={events} readOnlyEvents onEventClick={(event) => open(event.id)} />
+```
+
+No drag instruction is announced. The calendar is always named "Event calendar"
+(`material.event-calendar.label`); a calendar whose events can be dragged adds
+"Drag event" (`material.event-calendar.drag`) as its description, which a
+read-only one leaves out. The preview shows no Edit or Delete button, so
+`onEventEdit` and `onEventDelete` are not offered either.
+
+## In each view
+
+| View | Spans | Day badge | Week badge | Event tone and cancelled |
+| --- | --- | --- | --- | --- |
+| Month | shades the cell, or its half for a half day; the label shows from 7rem of cell width, with a dot under it | next to the day number | on the first cell of the row, with room below its events | chip tone; struck title, dashed outline |
+| Week / workweek | hatched band under the hours with its label, and a bar in the all-day strip (a half day only the band) | in the day's header | in the gutter corner | block tone; struck title, dashed outline |
+| Day | the same as the week; with `resources`, a span shades its own column | in the day's header | in the gutter corner | the same |
+| Agenda, phone day list | a plain, non-clickable row | in the day's heading | in the week's heading | tone dot; struck title, "Cancelled" in words |
+
+## weekStartsOn
+
+`weekStartsOn` (`0` Sunday to `6`) sets the first day of the week. Besides the
+month grid, the week view starts its days on it, and a week badge's key is that
+first day: with `weekStartsOn={1}`, the Monday.
+
+This is a change: the week view used to start on the locale's first day whatever
+`weekStartsOn` said. An app that set a `weekStartsOn` unlike its locale sees its
+week view shift.
+
+## Translations
+
+| Key | English | Used for |
+| --- | --- | --- |
+| `material.event-calendar.cancelled` | Cancelled | a cancelled event's accessible name |
+| `material.event-chip.cancelled` | Cancelled | the hidden word after a cancelled `EventChip`'s title, and in the preview and the agenda row |
+| `material.event-calendar.drag` | Drag event | the description of a calendar whose events can be dragged |
+| `material.event-calendar.week-badge` | Week: {label} | a week badge, read in the name of the week's first day |
+| `material.event-calendar.title` | Title | the placeholder of the preview's title field |
+| `material.event-calendar.label` | Event calendar | the calendar's accessible name |
+
+English and French ship. Override them through the `I18nProvider`
+([i18n guide](i18n.md)).
+
+## Exports
+
+From `@nxgt/material/components`:
+
+- `EventCalendarSpan`: the shape of one entry of `spans`.
+- `EventCalendarBadges`: `Record<string, { label: string; tone?: Tone }>`, the
+  type of `dayBadges` and `weekBadges`.
+- `EventCalendarDayMarksProps`: the props `spans`, `dayBadges` and `weekBadges`,
+  for a wrapper that forwards them.
+- `CalendarEventStatus`: `'scheduled' | 'cancelled'`, the type of an event's
+  `status`.

package/docs/guides/forms.md

@@ -644,7 +644,8 @@ export function SupplierForm({ onSave }: { onSave: (values: Values) => void }) {
   a `reset()` or `setValue()`), so `defaultValues` is only the fallback while
   the form value is empty (`undefined`, `null` or `{}`). Its fields fill the row, and `hideLabel` keeps
   `label` as the group's accessible name without drawing it, under a
-  `FormSection` that already has the title.
+  `FormSection` that already has the title. `control` and `name` are typed from your
+  form (see [Attributes](../components/form-fields.md#attributes)).
 
 ### Rows a user adds and removes
 

package/docs/guides/i18n.md

@@ -227,6 +227,8 @@ The package's own strings live under one top-level namespace per language,
 either side are kept, and where both define the same leaf, **your value
 wins**.
 
+`EventCalendar`'s strings (`material.event-calendar.*`) and `EventChip`'s hidden "Cancelled" (`material.event-chip.cancelled`) are listed in the [EventCalendar guide](event-calendar.md#translations).
+
 The copy components render on their own comes from this namespace: empty
 states, dialogs, pickers, the rich-text editor's toolbar, menus, node dialogs,
 slash menu, font names and table-caption alignment

package/docs/roadmap.md

@@ -389,6 +389,18 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **EventCalendar background spans, badges, tones and cancelled events** —
+  `EventCalendar` shows what the days themselves are: `spans` draw closures,
+  half days and other labelled, toned stretches behind the events in every
+  view (a hatched band in the time views, a shaded cell or half cell in the
+  month, a non-clickable row in the agenda and phone list), `dayBadges` and
+  `weekBadges` put a short toned label on a day or a week, each event takes a
+  `tone` and several `badges` (a status, a priority, a progress count), and a
+  `status: 'cancelled'` event is struck through, muted and
+  announced as cancelled in words, and `readOnlyEvents` makes every event
+  undraggable and unresizable while it stays clickable and in full colour
+  ([guide](guides/event-calendar.md), [#2372](https://github.com/softistx/nxgt-material/issues/2372)).
+
 - **Cells driven by their value** — in `DataTable`, `ServerTable` and
   `DataGrid`, `meta.cellClassName(value, row)` computes a class per cell from
   its value; `meta.tone(value, row)` colours a cell as coloured text after a

package/lib/components/components.css

@@ -216,5 +216,6 @@
 @import "./background-shared.css";
 @import "./ui/layout/app-search/app-search.css"; /* AppSearchBar, SearchView */
 @import "./ui/widgets/drawing/drawing.css"; /* @nxgt/material/draw: role colours, focus ring */
+@import "./ui/widgets/event-calendar/event-calendar-backdrop.css"; /* EventCalendar spans: the hatch and its label */
 @import "./ui/widgets/drawing/drawing-animate.css";
 @import "./ui/widgets/barcode/barcode.css"; /* @nxgt/material/barcode: symbol colours, label sheet */

package/lib/components/ui/widgets/event-calendar/event-calendar-backdrop.css

@@ -0,0 +1,43 @@
+/* EventCalendar spans (holidays, terms, closures): the thin hatch of direction
+ * A Refined, as CSS classes (no inline gradient, so the CSP holds). The
+ * shading is decoration under the events; the label sits on an opaque pill in
+ * the tone's text colour, which keeps it AA on the hatch. The tone comes from
+ * the nearest `data-tone`. */
+@layer components {
+	.nxgt-ec-backdrop {
+		background-image: repeating-linear-gradient(
+			135deg,
+			color-mix(in oklab, var(--nxgt-tone) 42%, transparent) 0 1px,
+			transparent 1px 7px
+		);
+	}
+	.nxgt-ec-backdrop-bar {
+		box-shadow: inset 0 0 0 1px
+			color-mix(in oklab, var(--nxgt-tone) 28%, transparent);
+	}
+	.nxgt-ec-backdrop-label {
+		display: block;
+		width: fit-content;
+		max-width: 100%;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		padding: 2px 6px;
+		border-radius: 4px;
+		border: 1px solid var(--border);
+		background: var(--card);
+		color: var(--nxgt-tone-text);
+		font-size: 11px;
+		font-weight: 500;
+		line-height: 1.2;
+	}
+	.nxgt-ec-backdrop-label-css::before {
+		content: attr(data-label);
+	}
+	.nxgt-ec-backdrop-dot {
+		width: 0.375rem;
+		height: 0.375rem;
+		border-radius: 9999px;
+		background: var(--nxgt-tone);
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.92.0",
+	"version": "3.93.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"