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

package/docs/notification-center.md

@@ -0,0 +1,372 @@
+<!-- index: ./index.md -->
+# notification-center
+
+`data-ui="notification-center"` · Read and unread notifications with actions.
+
+## Import
+
+```ts
+import { SlNotificationCenter, SlNotificationItem, SlNotificationVisual, SlNotificationActions, SlNotificationCenterActions, SlNotificationCenterFooter, SlNotificationCenterEmpty, provideNotificationCenterDefaults } from '@slotted/angular/notification-center';
+```
+
+Selector: `section[slNotificationCenter], ng-template[slNotificationItem], ng-template[slNotificationVisual], ng-template[slNotificationActions], [slNotificationCenterActions], [slNotificationCenterFooter], [slNotificationCenterEmpty]` · exportAs: `slNotificationCenter`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<section
+  slNotificationCenter
+  [items]="items()"
+  [now]="now"
+  (readRequest)="markRead($event.keys, $event.read)"
+  (removeRequest)="remove($event.key)"
+></section>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section[slNotificationCenter] | yes |
+| `header` | div | yes |
+| `title` | h2, h3 or h4 per level; on an item, a or span | yes |
+| `count` | span | no |
+| `mark-all` | span around a Button | yes |
+| `actions` | div | no |
+| `views` | div around a Tabs list | no |
+| `fresh` | button | no |
+| `feed` | div | yes |
+| `group` | div | no |
+| `group-label` | h3, h4 or h5 — one rank below the title | no |
+| `item` | article | no |
+| `visual` | span | no |
+| `content` | div | no |
+| `description` | p | no |
+| `time` | time | no |
+| `controls` | div | no |
+| `read-toggle` | button | no |
+| `dismiss` | button | no |
+| `more` | button, or div | no |
+| `empty` | div | no |
+| `footer` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `readonly NotificationItem[]` | — | SlNotificationCenter | The consumer’s array: key, title, description, time (a PlainDateTime or an ISO instant), read, href, tone, data. Required. The family holds none of its facts |
+| `view` | `string \| undefined` | all | SlNotificationCenter | The current view, as a model: [(view)] for two-way, [view] alone to read. all shows every shown item; unread the ones whose read is false; any other value what the consumer gave |
+| `defaultView` | `string` | — | SlNotificationCenter | The view an unbound centre starts on, read once. With neither, the first entry of views |
+| `views` | `readonly { value, label, count? }[]` | all, unread | SlNotificationCenter | The strip’s entries. Unstated, the built-in All and Unread with the unread count; one entry draws no strip |
+| `size` | `'sm' \| 'md'` | md | SlNotificationCenter, provideNotificationCenterDefaults | sm for the popover: the small type steps, tighter insets, the small inner-control box, a floor width of 22rem. md for the page |
+| `level` | `'2' \| '3' \| '4'` | 2 | SlNotificationCenter, provideNotificationCenterDefaults | The rank of the header’s heading; group labels take the rank below |
+| `growing` | `'none' \| 'button' \| 'scroll'` | none | SlNotificationCenter, provideNotificationCenterDefaults | How more is loaded: never, on a button, or when the sentinel under the feed enters the scrollport |
+| `arrivals` | `'hold' \| 'show'` | hold | SlNotificationCenter, provideNotificationCenterDefaults | Whether a key that arrives while focus is in the feed or the feed’s scroller is past its start waits behind fresh. show holds nothing |
+| `timeFormat` | `'relative' \| 'absolute'` | relative | SlNotificationCenter, provideNotificationCenterDefaults | How time is written: há 2 horas with the absolute reading in title, or the absolute reading alone |
+| `controls` | `'both' \| 'read' \| 'dismiss' \| 'none'` | both | SlNotificationCenter, provideNotificationCenterDefaults | Which of the family’s two item controls are drawn |
+| `loading` | `boolean` | false | SlNotificationCenter | aria-busy on the feed and data-loading on the host; skeleton rows while nothing is loaded, the waiting row under the feed otherwise |
+| `count` | `number` | — | SlNotificationCenter | How many items exist in all, for aria-setsize. Unstated, the loaded number under growing="none" and -1 while more may come |
+| `groupBy` | `(item) => string` | — | SlNotificationCenter | Files each item under a label, in the order the labels first appear; each group gets a heading one rank below the title |
+| `locale, timeZone, now` | `string, string, number` | the language in force, the runtime’s | SlNotificationCenter, provideNotificationCenterDefaults (timeZone) | What the time is formatted with. State now for a stable server render of a relative time |
+| `messages` | `PartialMessages<NotificationCenterMessages>` | — | SlNotificationCenter | Words laid over the language in force, key by key: title, markAll, markRead, markUnread, dismiss, fresh {count}, unread {count}, loadMore, loading, empty, caughtUp, all, unreadView, views |
+| `[slNotificationCenterActions], [slNotificationCenterFooter], [slNotificationCenterEmpty]` | `projected elements` | — | inside the host | The consumer’s controls in the header after mark-all; the link from the popover to the page; the result-state in place of the family’s empty words |
+| `ng-template[slNotificationItem], [slNotificationVisual], [slNotificationActions]` | `templates with NotificationItemContext` | — | inside the host | The item’s content, its visual, its actions. The context carries the item as $implicit, the position, the resolved tone, the formatted time and the ids for the title and the description; the article, its wiring and its controls stay the family’s |
+| `exportAs slNotificationCenter` | `SlNotificationCenter` | — | a template reference | focus(), which lands on fresh when arrivals are held and on the first article otherwise; reveal(); markAllRead(); selectView(value, reason) — the last three with the reason programmatic when unstated |
+| `provideNotificationCenterDefaults` | `{ size, level, growing, arrivals, timeFormat, controls, timeZone }` | — | an injector | The decisions an application takes once. A centre that states any of them itself still wins |
+| `host attributes` | `section[slNotificationCenter]` | — | SlNotificationCenter | aria-*, data-*, class, style and listeners reach the section; a consumer’s aria-label or aria-labelledby written on the element replaces the title wiring |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `viewRequest` | `ChangeRequest<string \| undefined>` | Before the view moves. The request carries the new value, the value it replaces, the reason — pointer or keyboard from the strip, programmatic from selectView() — the originating event as source, and cancel(), which refuses the move before the model is written. |
+| `viewChange` | `string \| undefined` | After the view moved: the model’s own output, for [(view)]. |
+| `readRequest` | `{ keys, read, reason, event?, cancelled, cancel() }` | When the reader presses a read-toggle (one key), mark-all (every unread shown key) or the instance’s markAllRead() — reasons pointer, keyboard, programmatic. The family marks nothing itself: the store answers by changing items. |
+| `removeRequest` | `{ key, reason, event?, cancelled, cancel() }` | When the reader presses dismiss, or Delete on an article — reasons pointer, keyboard. Cancelling a keyboard removal keeps focus where it is; otherwise focus moves to the next article, the previous, or the first control of the region. |
+| `openRequest` | `{ key, reason, event?, cancelled, cancel() }` | Before a title link navigates — reasons pointer, keyboard. cancel() prevents the navigation. |
+| `revealRequest` | `{ count, reason, event?, cancelled, cancel() }` | Before held arrivals are shown: a press of fresh (pointer, keyboard) or the instance’s reveal() (programmatic). A keyboard reveal moves focus to the first revealed article. |
+| `loadMoreRequest` | `{ reason, event?, cancelled, cancel() }` | When the reader presses more (pointer, keyboard) or the sentinel enters the scrollport (scroll). The consumer loads the page and appends to items. |
+| `unreadChange` | `number` | A fact, not a request: on the first render and whenever the unread count among items changes, for the bell in the top navigation. |
+| `(keydown), (click), (focus) on the host` | `the element’s own events` | Whenever the section fires them. The feed keys are handled on the feed, and a defaultPrevented keydown is left alone. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md` | `md` |
+| `level` | `2`, `3`, `4` | `2` |
+| `growing` | `none`, `button`, `scroll` | `none` |
+| `arrivals` | `hold`, `show` | `hold` |
+| `timeFormat` | `relative`, `absolute` | `relative` |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | — |
+| `controls` | `both`, `read`, `dismiss`, `none` | `both` |
+
+## Rules
+
+- The governing pattern is the WAI-ARIA Authoring Practices Feed (w3.org/WAI/ARIA/apg/patterns/feed/): the feed is role="feed" named by the title, every item is an article with tabindex="0", aria-labelledby its title, aria-describedby its description, aria-posinset its position and aria-setsize the consumer’s count, the loaded number under growing="none", or -1 while more may come. PageDown and PageUp move between articles, Control+End and Control+Home leave the feed on either side, and the feed is aria-busy while a page is on its way. The keys are @slotted/core/timeline’s, shared with the timeline family.
+- The root is a section — a region — named by aria-labelledby its own heading, Notifications in English, so a reader finds it in the landmark list under the words it shows; a consumer’s aria-label or aria-labelledby written on the element wins. The strip is the tabs family’s list with the feed as its one panel: every tab carries aria-controls naming the feed, and ArrowLeft, ArrowRight, Home and End are the tabs family’s.
+- Read is said three ways and none of them is colour alone: the wash under the row, the semibold title, and the read-toggle’s name — Mark as read while unread, Mark as unread once read — so a reader hears the state on the control that changes it. The family’s tone glyphs are all circles; a triangle is refused in this library.
+- Held arrivals are announced politely once per change of their count, and the unread count once per change after the first, through the shared live announcer. A keyboard reveal moves focus to the first revealed article; a keyboard removal moves it to the next article, the previous, or the first control of the region, so focus never lands on a row that left.
+- While loading with nothing loaded, the three skeleton rows are aria-hidden and the feed is busy; the tabs stay, because the views are known before the items are. The article’s focus ring is drawn inward because the rows touch, and every control’s ring outward; the controls are muted at rest and take the text ink on the row under the pointer or holding focus, so they are visible before they are needed and legible when they are.
+
+## Tokens
+
+`--slotted-avatar-size-sm`, `--slotted-avatar-size-xs`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-gap-sm`, `--slotted-control-height-sm`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-line-height`, `--slotted-control-padding-inline-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-highlight-tint-opacity`, `--slotted-line-height-lg`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-notification-center-background`, `--slotted-notification-center-border`, `--slotted-notification-center-description-clamp`, `--slotted-notification-center-gap-md`, `--slotted-notification-center-gap-sm`, `--slotted-notification-center-inset-block-md`, `--slotted-notification-center-inset-block-sm`, `--slotted-notification-center-inset-inline-md`, `--slotted-notification-center-inset-inline-sm`, `--slotted-notification-center-min-inline-size-sm`, `--slotted-notification-center-scrollbar-thumb-color`, `--slotted-notification-center-scrollbar-track-color`, `--slotted-notification-center-title-clamp`, `--slotted-notification-center-title-size-md`, `--slotted-notification-center-title-size-sm`, `--slotted-radius-full`, `--slotted-space-1`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+
+## Examples
+
+### Every part, written out
+
+The header with the title, its count and a preferences link; the strip with three views; the feed grouped under Hoje and Ontem with an avatar, a family visual and no visual; a button for more; a footer link. Every part the contract names, in one box.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter growing="button" [items]="items()" [views]="views" [groupBy]="dayOf">
+  <div slNotificationCenterActions><a slLink href="/preferencias">Preferências</a></div>
+  <ng-template slNotificationVisual let-item>
+    <span slAvatar decorative [name]="item.data.name" shape="circle" size="sm"></span>
+  </ng-template>
+  <div slNotificationCenterFooter>
+    <a slLink href="/notificacoes">Ver todas as notificações</a>
+  </div>
+</section>
+```
+
+### Read is the store’s fact
+
+Press the check on an unread row: the family asks readRequest with the key and true, and the row changes only when the store answers. The count in the title and the tab follow the items; mark-all asks for every unread shown key at once and is disabled at zero.
+
+Excerpt — not a complete module
+
+```ts
+class Inbox {
+  readonly items = signal<NotificationItem[]>([]);
+
+  markRead(keys: readonly string[], read: boolean) {
+    this.items.update((items) =>
+      items.map((item) => (keys.includes(item.key) ? { ...item, read } : item)),
+    );
+  }
+}
+```
+
+### Views
+
+The built-in strip: All and Unread, the second with its count; the family filters the unread view itself. Below, the consumer’s own views — the family shows what it is given for each — and a view that refuses to leave All.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slNotificationCenter
+  [items]="view() === 'mentions' ? mentions() : items()"
+  [views]="views()"
+  [(view)]="view"
+  (viewRequest)="$event.value === 'archived' ? $event.cancel() : null"
+></section>
+```
+
+### Arrivals are held while the reader reads
+
+Focus an article, then press Chegam duas: the list stays where it is and a pill counts what arrived. Press the pill — or PageUp from the first article, then Enter — and the two show at the top with focus on the first. Press Chegam duas without focus in the feed and they show at once. Under arrivals="show" nothing is ever held.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slNotificationCenter
+  arrivals="hold"
+  [items]="items()"
+  (revealRequest)="track('notifications.reveal', $event.count, $event.reason)"
+></section>
+```
+
+### Groups
+
+groupBy files each item under a label — the day here — in the order the items give; the label is a heading one rank below the title and the positions run across the groups.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter [items]="items()" [groupBy]="dayOf"></section>
+```
+
+### Growing
+
+growing="button" draws Load more; press it, the waiting row says Loading notifications and two older items arrive. growing="scroll" replaces the button with a sentinel that asks with the reason scroll when it enters the scrollport. aria-setsize is -1 while more may come and the consumer’s count when stated.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slNotificationCenter
+  growing="scroll"
+  [count]="total()"
+  [items]="items()"
+  [loading]="loading()"
+  (loadMoreRequest)="loadPage($event.reason)"
+></section>
+```
+
+### Actions and controls
+
+Two slots for the consumer: the header’s actions after mark-all, and an item’s actions under its time. The family’s own two controls are the controls axis: both, read alone, dismiss alone, or none for a feed whose store has no per-item read or removal.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter controls="dismiss" [items]="items()">
+  <div slNotificationCenterActions><a slLink href="/preferencias">Preferências</a></div>
+  <ng-template slNotificationActions let-item>
+    @if (item.data.shipment) {
+      <button slButton size="sm" type="button">Ver expedição</button>
+    }
+  </ng-template>
+</section>
+```
+
+### Hosts
+
+The bell is a popover trigger with the store’s unread count — the centre reports the same through unreadChange while it is mounted; inside, the centre at size="sm" with a footer to the page. Open it, press PageDown through the articles, press Escape. The page host is the same family at size="md" with groups.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slPopover side="bottom" align="end" size="lg">
+  <button
+    slButton
+    slPopoverTrigger
+    type="button"
+    [attr.aria-label]="'Notificações, ' + unread() + ' não lidas'"
+  >
+    <ng-icon name="lucideBell"></ng-icon>
+  </button>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent aria-label="Notificações">
+      <section slNotificationCenter size="sm" level="3" [items]="items()">
+        <div slNotificationCenterFooter>
+          <a slLink href="/notificacoes">Ver todas as notificações</a>
+        </div>
+      </section>
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+### Loading
+
+With nothing loaded, three skeleton rows stand in the item’s inset — a circle for the visual, two lines for the words — hidden from assistive technology, and the feed is busy. With items loaded and more on the way, the waiting row under the feed says so politely.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter loading [items]="[]"></section>
+```
+
+### Empty
+
+A feed with nothing shows messages.empty; the unread view with nothing unread shows messages.caughtUp — All caught up. A [slNotificationCenterEmpty] element replaces both with a result-state of the consumer’s own.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter [items]="[]">
+  <section slNotificationCenterEmpty slResultState status="success" reach="inline" live="off">
+    <div slResultStateContent>
+      <div slResultStateTitle>Tudo lido</div>
+      <p slResultStateDescription>Nada aguarda a sua atenção.</p>
+    </div>
+  </section>
+</section>
+```
+
+### Sizes and ranks
+
+size="sm" for a popover — the small type steps, tighter insets, the small inner-control box, a 24-pixel family visual and a floor width of 22rem — and "md" for a page. level sets the heading rank: 2 on a page, 3 in a popover under a page’s h2, 4 deeper; group labels take the rank below.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter size="sm" level="3" [items]="items()"></section>
+```
+
+### Extreme content
+
+A title of thirty words clamps at two lines, a description at three, and the whole text stays in the DOM; a reference with no spaces breaks at any character. Below 320 pixels the controls drop under the content instead of squeezing it; the phone room shows the header wrapping.
+
+Excerpt — not a complete module
+
+```css
+[data-ui='notification-center'] {
+  --slotted-notification-center-title-clamp: 1;
+  --slotted-notification-center-description-clamp: 2;
+}
+```
+
+### Composition
+
+The families a centre is made of: Avatar in the visual template, Button in the item’s actions and in mark-all, Tabs in the strip, Skeleton while loading, ResultState when empty, Link in the header and the footer. The slNotificationItem template substitutes the content of a row — a Badge with the tone here — while the article, its wiring and its controls stay the family’s.
+
+Excerpt — not a complete module
+
+```html
+<section slNotificationCenter [items]="items()">
+  <ng-template slNotificationItem let-item let-time="time" let-tone="tone" let-ids="ids">
+    <span data-part="title" [id]="ids.title">{{ item.title }}</span>
+    <span slBadge size="sm" variant="soft" [tone]="tone">{{ item.data.category }}</span>
+    <time data-part="time" [attr.datetime]="time.dateTime">{{ time.text }}</time>
+  </ng-template>
+</section>
+```
+
+### Defaults and the instance
+
+Two centres under one provider: neither states a size or a growing mode, and both read small and paged by button; the second states its own controls and wins. The instance, reached through exportAs, focuses the first article, reveals held arrivals and marks every shown item read with the reason programmatic.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideNotificationCenterDefaults({
+      growing: 'button',
+      size: 'sm',
+      timeZone: 'Europe/Lisbon',
+    }),
+  ],
+});
+```
+
+### Keyboard
+
+Tab reaches mark-all, the selected tab, fresh, then each article and the two controls inside it, then more and the footer. On an article: PageDown and PageUp move between articles, PageUp on the first reaches fresh, Control+End and Control+Home leave the feed, Delete asks to remove with the reason keyboard and moves focus to the neighbour. Enter on the title asks openRequest before the link navigates.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slNotificationCenter
+  [items]="items()"
+  (openRequest)="canOpen($event.key) || $event.cancel()"
+  (removeRequest)="
+    $event.reason === 'keyboard' && !confirmed($event.key) ? $event.cancel() : remove($event.key)
+  "
+></section>
+```
+
+### Accessibility
+
+The region is named by its heading, the feed by the same, every article by its title and described by its body; the tabs name the feed. Held arrivals and the unread count are announced politely once per change. Read the ring on an article — inward, because the rows touch — and on a control — outward.
+
+Excerpt — not a complete module
+
+```html
+<section
+  slNotificationCenter
+  aria-label="Caixa de entrada da equipa de vendas"
+  [items]="items()"
+></section>
+```