@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/entity-picker.md

@@ -0,0 +1,365 @@
+<!-- index: ./index.md -->
+# entity-picker
+
+`data-ui="entity-picker"` · Searches and picks remote records like people.
+
+## Import
+
+```ts
+import { SlEntityPicker, SlEntityPickerChip, SlEntityPickerOption, provideEntityPickerDefaults } from '@slotted/angular/entity-picker';
+```
+
+Selector: `sl-entity-picker, ng-template[slEntityPickerOption], ng-template[slEntityPickerChip]` · exportAs: `slEntityPicker`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker
+  aria-label="Owner"
+  [source]="directory"
+  [(value)]="owner"
+  (valueChangeRequest)="log($event)"
+/>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-entity-picker | yes |
+| `scope` | div around an sl-select | no |
+| `control` | div | yes |
+| `selection` | span around an slAvatar | no |
+| `values` | div | no |
+| `chips` | div | no |
+| `field` | span | no |
+| `input` | input | yes |
+| `clear` | button | no |
+| `trigger` | button | yes |
+| `arrow` | span | no |
+| `busy` | span, the spinner family | no |
+| `positioner` | div, portalled | yes |
+| `content` | div | yes |
+| `group` | div | no |
+| `group-label` | div | no |
+| `item` | div | no |
+| `media` | span around an slAvatar | no |
+| `label` | span | no |
+| `match` | mark, from slHighlight | no |
+| `description` | span | no |
+| `meta` | span | no |
+| `indicator` | span | no |
+| `error` | div | no |
+| `empty` | div | no |
+| `placeholder` | div | no |
+| `more` | div | no |
+| `status` | div | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `selectionMode` | `'single' \| 'multiple'` | single | sl-entity-picker | One id or an array of ids |
+| `source` | `EntitySource` | — | sl-entity-picker | search(request, { signal }) and resolve(ids, { signal }) |
+| `items` | `readonly Entity[]` | — | sl-entity-picker | A list the application holds, filtered locally |
+| `entities` | `readonly Entity[]` | [] | sl-entity-picker | Records the application already knows |
+| `favorites` | `readonly Entity[]` | [] | sl-entity-picker | The first section on an empty query |
+| `recent` | `readonly Entity[]` | [] | sl-entity-picker | The section after favorites |
+| `scopes` | `readonly { id; label }[]` | [] | sl-entity-picker | Draws an sl-select in front of the field |
+| `value` | `model<string \| null \| readonly string[]>` | null | sl-entity-picker | Two-way ids |
+| `defaultValue` | `string \| readonly string[]` | — | sl-entity-picker | The uncontrolled start, read once |
+| `inputValue` | `model<string>` | '' | sl-entity-picker | Two-way text |
+| `open` | `model<boolean>` | false | sl-entity-picker | Two-way popup |
+| `highlightedValue` | `model<string \| null>` | null | sl-entity-picker | Two-way highlight |
+| `scope` | `model<string \| null>` | null | sl-entity-picker | Two-way scope |
+| `createEntity` | `(query) => Entity \| Promise<Entity \| null>` | — | sl-entity-picker | Draws the offer to create |
+| `max` | `number` | null | sl-entity-picker | multiple: the most records chosen |
+| `searchDelay` | `number` | 250 | sl-entity-picker | Milliseconds after the last keystroke |
+| `minQueryLength` | `number` | 0 | sl-entity-picker | Below it nothing is asked |
+| `media` | `'avatar' \| 'none'` | avatar | sl-entity-picker | Faces in rows, chips and the field |
+| `overflow` | `'collapse' \| 'wrap'` | collapse | sl-entity-picker | multiple: one line with +N, or three lines |
+| `openOn` | `'input' \| 'focus' \| 'manual'` | input | sl-entity-picker | input: typing or a press opens; focus: every focus too; manual: only the trigger and the arrows |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-entity-picker | The control step; a field sets it |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | sl-entity-picker | plain gives the box to a cell |
+| `side` | `'bottom' \| 'top'` | bottom | sl-entity-picker | Where the popup opens |
+| `width` | `'anchor' \| 'content'` | content | sl-entity-picker | The popup at least as wide as the frame and as wide as its longest row (content), or pinned to the width of the frame (anchor) |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | sl-entity-picker | fixed inside a clipped ancestor |
+| `clearable` | `boolean` | true | sl-entity-picker | Draws the clear button |
+| `loop` | `boolean` | false | sl-entity-picker | The arrows wrap |
+| `highlightMatch` | `boolean` | true | sl-entity-picker | Marks the span the query found |
+| `portal` | `boolean` | true | sl-entity-picker | false keeps the layer in place |
+| `fullWidth` | `boolean` | true | sl-entity-picker | false sizes the root to its content |
+| `disabled` | `boolean` | false | sl-entity-picker | Also from a field or a form control |
+| `readOnly` | `boolean` | false | sl-entity-picker | Keeps the text, withholds the popup |
+| `required` | `boolean` | false | sl-entity-picker | Reported by the Validator |
+| `invalid` | `boolean` | false | sl-entity-picker | Also from a field |
+| `locale` | `string` | — | sl-entity-picker | BCP 47. The language in force when absent |
+| `messages` | `Partial<EntityPickerMessages>` | — | sl-entity-picker | Words laid over the language in force, key by key; {count}, {query}, {label}, {id} and {max} are slots |
+| `aria-label` | `string` | — | sl-entity-picker | The name when no field labels it |
+| `slEntityPickerOption` | `ng-template, context { $implicit, query, selected, current, disabled }` | — | option content | The content of an option |
+| `slEntityPickerChip` | `ng-template, context { $implicit }` | — | chip words | The words of a chip |
+| `provideEntityPickerDefaults` | `(defaults) => Provider` | — | an injector | The decisions an application takes once |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChangeRequest` | `ChangeRequest<string \| null \| readonly string[]> & { entities: readonly Entity[] }` | Before the choice moves: a press (pointer), Enter (keyboard), a removal (remove), clear (clear), a created record (submit). cancel() refuses it; otherwise value and a form control follow. |
+| `valueChange` | `string \| null \| readonly string[]` | The model half of [(value)], after a request nobody cancelled. |
+| `inputValueChangeRequest / inputValueChange` | `ChangeRequest<string> / string` | The text: typing (keyboard), a choice (select), clear (clear), leaving text that chose nothing (blur). |
+| `openChangeRequest / openChange` | `ChangeRequest<boolean> / boolean` | The popup: focus and keys (keyboard), a press on the input or the trigger (pointer), escape, outsidePress, select, blur. |
+| `highlightedValueChangeRequest / highlightedValueChange` | `ChangeRequest<string \| null> / string \| null` | The highlight: arrows (keyboard), hovering (pointer). |
+| `scopeChangeRequest / scopeChange` | `ChangeRequest<string \| null> / string \| null` | The scope, from the sl-select in front of the field (pointer, keyboard). |
+| `create` | `{ query: string; reason }` | The offer to create is taken; [createEntity] makes the record, which is then chosen. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `selectionMode` | `single`, `multiple` | `single` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `media` | `avatar`, `none` | `avatar` |
+| `overflow` | `collapse`, `wrap` | `collapse` |
+| `openOn` | `input`, `focus`, `manual` | `input` |
+| `side` | `bottom`, `top` | `bottom` |
+| `width` | `anchor`, `content` | `content` |
+| `strategy` | `absolute`, `fixed` | `absolute` |
+| `clearable` | `true`, `false` | `true` |
+| `loop` | `true`, `false` | `false` |
+| `highlightMatch` | `true`, `false` | `true` |
+| `portal` | `true`, `false` | `true` |
+| `fullWidth` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+| `readOnly` | `true`, `false` | `false` |
+| `required` | `true`, `false` | `false` |
+| `invalid` | `true`, `false` | `false` |
+
+## Rules
+
+- The input is a combobox with a listbox popup, as the APG Combobox Pattern writes it: DOM focus never leaves the input, aria-activedescendant names the highlighted record, and aria-autocomplete is list.
+- Each option and each chip is named by the name and the identifier, so two people called Ana Souza are two things to a screen reader; an id without a record is named Unavailable with the id.
+- In multiple the chips are one row of a grid with one tab stop: the arrows move between chips, Delete removes, and focus after a removal goes to the chip that took the index, then the previous one, then the input.
+- The Validator reports required and unresolved to a Reactive Form, so a value that holds a deleted record is invalid without the application checking it.
+- The failure and every chip added or removed are said once through the shared polite announcer; the skeletons are hidden from assistive technology.
+
+## Tokens
+
+`--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-avatar-size-xs`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-entity-picker-action-active-background`, `--slotted-entity-picker-action-color`, `--slotted-entity-picker-action-hover-background`, `--slotted-entity-picker-action-size`, `--slotted-entity-picker-autofill-background`, `--slotted-entity-picker-background`, `--slotted-entity-picker-border-color`, `--slotted-entity-picker-color`, `--slotted-entity-picker-content-border-color`, `--slotted-entity-picker-content-radius`, `--slotted-entity-picker-content-shadow`, `--slotted-entity-picker-content-text`, `--slotted-entity-picker-content-text-muted`, `--slotted-entity-picker-disabled-background`, `--slotted-entity-picker-disabled-border-color`, `--slotted-entity-picker-disabled-color`, `--slotted-entity-picker-error-color`, `--slotted-entity-picker-field-basis`, `--slotted-entity-picker-field-min`, `--slotted-entity-picker-highlight`, `--slotted-entity-picker-highlight-active`, `--slotted-entity-picker-highlight-ring`, `--slotted-entity-picker-hover-border-color`, `--slotted-entity-picker-icon-size-min`, `--slotted-entity-picker-invalid-border-color`, `--slotted-entity-picker-invalid-edge-width`, `--slotted-entity-picker-invalid-focus-ring-color`, `--slotted-entity-picker-item-radius`, `--slotted-entity-picker-measure`, `--slotted-entity-picker-meta-measure`, `--slotted-entity-picker-offer-color`, `--slotted-entity-picker-open-border-color`, `--slotted-entity-picker-placeholder-color`, `--slotted-entity-picker-plain-hover-background`, `--slotted-entity-picker-radius`, `--slotted-entity-picker-readonly-background`, `--slotted-entity-picker-scope-inline-size`, `--slotted-entity-picker-selected-color`, `--slotted-entity-picker-shadow`, `--slotted-entity-picker-subtle-background`, `--slotted-entity-picker-subtle-border-color`, `--slotted-entity-picker-subtle-hover-background`, `--slotted-entity-picker-surface`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+### One record
+
+The chosen name is the text of the field and the face stands before it. Typing searches; leaving text that chose nothing puts the name back.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Account owner</label>
+  <sl-entity-picker defaultValue="usr_bruno" [source]="directory" />
+</div>
+```
+
+### Several records
+
+Reviewers as chips with faces. Choosing keeps the popup open and empties the query; the field stays one line, and what does not fit is counted by +N.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker
+  aria-label="Reviewers"
+  selectionMode="multiple"
+  [defaultValue]="['usr_ana', 'usr_bruno', 'usr_carla']"
+  [source]="directory"
+/>
+```
+
+### A record, not a string
+
+The face, the name, the identifier under it and a short fact on its line. Two people called Ana Souza are told apart by their address, in the list and in what a screen reader hears.
+
+Excerpt — not a complete module
+
+```ts
+const record: Entity = {
+  id: 'usr_ana',
+  label: 'Ana Souza',
+  description: 'ana.souza@northwind.io',
+  meta: 'Admin',
+};
+```
+
+### Favorites and recent
+
+Press the empty field: favorites, then recent, then what the empty query returned, with no id twice. rememberRecent keeps the application’s list.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker
+  aria-label="Assignee"
+  [favorites]="pinned"
+  [recent]="recent()"
+  [source]="directory"
+  (valueChangeRequest)="remember($event)"
+/>
+```
+
+### Searching in a scope
+
+An sl-select joined to the front of the field chooses what the search runs over; the scope rides on every request.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Related record" [scopes]="scopes" [(scope)]="scope" [source]="crm" />
+```
+
+### Waiting for the source
+
+The first page waits as three skeleton records; a new query dims the rows already shown; the next page arrives under a skeleton row at the end. Nothing is drawn for an answer faster than 200ms.
+
+Excerpt — not a complete module
+
+```ts
+const directory: EntitySource = {
+  search: async ({ query, cursor }, { signal }) => {
+    const page = await api.people({ query, cursor, signal });
+    return { items: page.people, hasMore: page.next !== null, cursor: page.next };
+  },
+};
+```
+
+### Creating what is not there
+
+Type a company the source does not hold: the last option offers to create it, and the record createEntity returns is chosen with reason submit.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Account" [createEntity]="createAccount" [source]="accounts" />
+```
+
+### When the source fails
+
+The sentence names what failed and the option under it searches again — ArrowDown reaches it and Enter takes it. Chips already chosen stay.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Owner" [source]="offline" />
+```
+
+### Ids without records
+
+A value that arrives as ids: each chip waits as a skeleton while resolve runs, and an id the source never returns reads Unavailable and stays removable.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker
+  aria-label="Watchers"
+  selectionMode="multiple"
+  [defaultValue]="['usr_marta', 'usr_deleted']"
+  [source]="directory"
+/>
+```
+
+### A limit
+
+At three approvers every other record goes aria-disabled and the field says it is complete; removing one opens the list again.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Approvers" max="3" selectionMode="multiple" [source]="directory" />
+```
+
+### Sizes
+
+sm, md and lg beside a text field of the same step: the frame, the face and the chips follow the control scale.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Owner" size="sm" [source]="directory" />
+```
+
+### Variants
+
+outline in a form, subtle on a sunken panel, plain inside a table cell whose row is the box — square, no lift, the ring drawn inward.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Owner" variant="plain" [source]="directory" />
+```
+
+### States
+
+Disabled drops the remove buttons and fades the faces; read-only keeps the name copyable and withholds the popup; invalid retargets the edge and the ring.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Owner" disabled [source]="directory" />
+<sl-entity-picker aria-label="Owner" readOnly [source]="directory" />
+<sl-entity-picker aria-label="Owner" invalid required [source]="directory" />
+```
+
+### Content the family did not choose
+
+A nine-word name clamps to two lines, a long address to one with an ellipsis, an Arabic name reads right to left, and a token with no spaces breaks.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Watchers" selectionMode="multiple" [source]="international" />
+```
+
+### Every key
+
+ArrowDown opens and moves, PageDown jumps ten, Enter chooses, Escape closes then reverts; in multiple, Backspace from an empty field goes to the last chip and a second press removes it.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Reviewers" selectionMode="multiple" [source]="directory" />
+```
+
+### In a form
+
+A deal form with Reactive Forms: the owner and the reviewers are form controls, required, and stand at the height of the fields beside them.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker
+  aria-label="Reviewers"
+  required
+  selectionMode="multiple"
+  [formControl]="reviewers"
+  [source]="directory"
+/>
+```
+
+### Composition
+
+An option template adds the team after the address; a chip template adds the role; provideSlotted says every sentence in Portuguese once.
+
+Excerpt — not a complete module
+
+```html
+<sl-entity-picker aria-label="Reviewers" selectionMode="multiple" [source]="directory">
+  <ng-template slEntityPickerOption let-person>
+    <span data-part="label">{{ person.label }}</span>
+    <span data-part="description">{{ person.description }} · Northwind</span>
+  </ng-template>
+  <ng-template slEntityPickerChip let-person>{{ person.label }} · {{ person.meta }}</ng-template>
+</sl-entity-picker>
+```

package/docs/event-calendar.examples.md

@@ -0,0 +1,308 @@
+<!-- index: ./index.md -->
+# event-calendar
+
+`data-ui="event-calendar"` · Month, week, day and list views of events.
+
+## Examples
+
+### Which views, in what order
+
+[views] sets the switcher and its order; the first is the one an unbound calendar opens on. A booking page that only lists and a planner without a list are the same family.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" [views]="['week', 'day', 'month']"></div>
+```
+
+### The month
+
+All-day and multi-day events are bars; a meeting of one day is a dot, a time and a title. A bar running into next week stops in its cell with a chevron; the week number, the outside days and the continuous run of chosen days all show here.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" fixedWeeks weekNumbers></div>
+```
+
+### The week
+
+Blocks stand off the rules and off each other. The all-day lane holds bars across days, today’s column carries the now line, and the hours open on scrollTime. Hide the weekend for a working week.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slEventCalendar
+  [events]="events"
+  [dayHours]="[8, 20]"
+  defaultView="week"
+  weekends="hidden"
+></div>
+```
+
+### The day
+
+One column with room for the location under each title. The previous and next buttons step one day, and skip Saturday and Sunday when the weekend is hidden.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" defaultView="day" [slotDuration]="15"></div>
+```
+
+### The list
+
+A heading per day that holds an event and nothing for the days that hold none. Every event is in the tab order; the time has a column of its own so the titles align down the page.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" defaultView="list" listRange="month"></div>
+```
+
+### All-day, multi-day and past midnight
+
+A start without a time is a whole day, and its end is the last day, inclusive. The release window runs from 10 PM to 2 AM: one block per day in the week, one bar in the month labelled with its start.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="[conference, releaseWindow]" defaultView="week"></div>
+```
+
+### Overlapping events
+
+Events that overlap share the day in columns, each spanning the free columns to its right; no text is covered. Five hiring panels at the same hour draw two columns and a +3 that opens the day.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" defaultView="week" [maxColumns]="4"></div>
+```
+
+### Recurrence, exceptions and a moved occurrence
+
+The standup repeats every weekday and skips Labor Day; planning repeats every other Monday, and the one on the 21st was moved to Tuesday afternoon. A rule outside the subset degrades to a single occurrence.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="[standup, movedPlanning]" defaultView="week"></div>
+```
+
+### Time zones and the day the clocks change
+
+The calendar draws wall-clock time. The application converts its instants once with wallClockIn; timeZone decides today, the now line and the gutter’s label. On 1 November in New York the header says the clocks go back at 2 AM and the column marks the minute.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="shifts" [timeZone]="zone" defaultView="day"></div>
+```
+
+### Calendars and their colours
+
+Each calendar takes a slot of the data palette in order and never cycles. The filter is a menu of checkboxes; a predicate composes a search on top. Colour is identity only: the calendar is also in every event’s name.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slEventCalendar
+  [calendars]="calendars"
+  [events]="events"
+  [(visibleCalendars)]="visible"
+  [filter]="matches"
+>
+  <div slTextField slEventCalendarActions size="sm">
+    <input slTextFieldInput type="search" aria-label="Search events" (input)="search($event)" />
+  </div>
+</div>
+```
+
+### Working hours
+
+The hours outside workingHours are shaded, and a day no entry names is shaded whole. Shading informs and does not refuse: whether a slot outside hours can be booked is the application’s rule.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="appointments" [workingHours]="shifts" defaultView="week"></div>
+```
+
+### What a domain writes on a day
+
+An ng-template with slEventCalendarDayContent writes into every day header: who is on call here, a nightly price on a booking page, free slots in a clinic. It sits at the end of the header line in the month and under the date in the week.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events">
+  <ng-template slEventCalendarDayContent let-date>{{ onCall(date) }}</ng-template>
+</div>
+```
+
+### Opening an event
+
+With an ng-template carrying slEventCalendarDetail the family opens a popover anchored to the event and gives it back focus on close. Without one, (openEventRequest) asks and the application opens its own drawer; the open event keeps aria-expanded either way.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events">
+  <ng-template slEventCalendarDetail let-occurrence let-close="close">
+    <app-event-summary [occurrence]="occurrence" (edit)="close()" />
+  </ng-template>
+</div>
+```
+
+### Commands on a right click
+
+With an ng-template carrying slEventCalendarContextMenu a secondary click, a long press or Shift+F10 opens the context-menu family on what was pointed at: an event, the selection when the pointer is inside it, one step of the hours, or a day. The event is drawn solid and a stretch as the selection being made; slEventCalendarContextMenuFor leaves the browser’s own menu on the targets it refuses.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events">
+  <ng-template slEventCalendarContextMenu let-target>
+    @if (target.kind === 'event') {
+      <button slMenuItem (select)="duplicate(target.occurrence)">Duplicate</button>
+      <hr slMenuSeparator />
+      <button slMenuItem tone="danger" (select)="remove(target.occurrence)">Delete</button>
+    } @else {
+      <button slMenuItem (select)="openCreateDialog(target.slot)">New event</button>
+    }
+  </ng-template>
+</div>
+```
+
+### Choosing a stretch to create an event
+
+Drag across empty hours or days, or press Space on a day and extend with Shift and the arrows. The calendar asks with the stretch and a reason; the application opens its form and clears the selection when done.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slEventCalendar
+  [events]="events"
+  selectionMode="range"
+  [(selection)]="selection"
+  (selectionRequest)="create($event)"
+></div>
+```
+
+### Moving and resizing
+
+With editable, a press that travels four pixels picks an event up and lays it out where it would land; its end pulls to resize. Release asks with eventChangeRequest; Escape puts it back. Alt with the arrows does the same from the keyboard. A series asks with the occurrence’s own date. canDrop is asked about every destination with the same change: a refused one is drawn with a dashed danger edge, letting go there asks nothing, and Alt with an arrow passes over it to the next allowed one.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slEventCalendar
+  editable
+  [canDrop]="notAtWeekends"
+  [events]="events()"
+  (eventChangeRequest)="move($event.value)"
+></div>
+```
+
+### Loading a new range
+
+The grid is structure the date decides, so it stays painted; one bar on its top edge says events are coming, after loadingDelay, and holds for loadingMinDuration. Events already drawn stay until the new ones arrive.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slEventCalendar
+  [events]="events()"
+  [loading]="fetching()"
+  (rangeChange)="range.set($event)"
+></div>
+```
+
+### Nothing this week
+
+The list says so in a sentence and carries the application’s next step. The grid needs no sentence: an empty month is visibly empty.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="[]" defaultView="list">
+  <button slButton slEventCalendarEmpty type="button">New event</button>
+</div>
+```
+
+### A range that failed
+
+The error sits above the grid with the application’s retry; paging, the views and the filter keep working, because the failure is the data’s, not the calendar’s.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events">
+  <div slAlert slEventCalendarError tone="danger">The events could not be loaded.</div>
+</div>
+```
+
+### On a phone
+
+Below 600 pixels the month and the week draw as a list of the same days and the view does not change. With compact="keep" the grid stays: events become marks of colour, the day is the target, and each keeps its name. At that width the “+N” panel and the detail are sheets from the bottom edge rather than popovers.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" compact="keep"></div>
+```
+
+### Drawing the inside of an event
+
+An ng-template with slEventCalendarEvent replaces what an event shows and keeps the element, its name, its focus and its geometry. The context says where it is drawn — lane, bar, block or list — and the time the family would write.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events" defaultView="day">
+  <ng-template slEventCalendarEvent let-occurrence let-time="time">
+    <span data-part="event-title">{{ occurrence.event.title }}</span>
+    <span data-part="event-time">{{ time }}</span>
+    <span data-part="event-location">{{ occurrence.event.owner }}</span>
+  </ng-template>
+</div>
+```
+
+### Locale, clock and direction
+
+Portuguese starts the week on Sunday and writes a 24-hour clock; Hebrew mirrors the grid, the chevrons and the bars, and an English title on a Hebrew page keeps its own direction.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar [events]="events"></div>
+```
+
+### Density
+
+An hour is two small controls tall — 60, 52 and 48 pixels — and a lane is the inside of one, so dense shrinks the grid the way it shrinks the controls around it. Switch the toolbar to compare.
+
+Excerpt — not a complete module
+
+```html
+<div data-slotted-density="dense">
+  <div slEventCalendar [events]="events" defaultView="week"></div>
+</div>
+```
+
+### Keyboard
+
+Tab reaches one day. Arrows move the day, Page Up and Down the period, Home and End the week; in the week Up and Down move between the header, all-day and hours rows. Enter goes into a day, Up and Down walk its events, Escape comes back.
+
+Excerpt — not a complete module
+
+```html
+<div slEventCalendar #calendar="slEventCalendar" [events]="events"></div>
+<button type="button" (click)="calendar.focusDate(firstOfOctober)">Focus 1 October</button>
+```