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

package/dist/docs/notification-center.md

@@ -0,0 +1,371 @@
+<!-- index: ./index.md -->
+# notification-center
+
+`data-ui="notification-center"` · Read and unread notifications with actions.
+
+## Import
+
+```tsx
+import { NotificationCenter, NotificationCenterDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<NotificationCenter
+  items={items}
+  now={now}
+  onReadChange={({ keys, read }) => markRead(keys, read)}
+  onRemove={(key) => remove(key)}
+/>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section, or the element render returns | 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[]` | — | NotificationCenter | The consumer’s array: key, title, description, time (a PlainDateTime or an ISO instant), read, href, tone, visual, actions. The family holds none of its facts |
+| `view` | `string` | all | NotificationCenter | Present means the consumer owns the view, for the life of the component. all shows every shown item; unread the ones whose read is false; any other value what the consumer gave |
+| `defaultView` | `string` | — | NotificationCenter | The view an uncontrolled centre starts on, read once. With neither, the first entry of views |
+| `views` | `readonly { value, label, count? }[]` | all, unread | NotificationCenter | The strip’s entries. Unstated, the built-in All and Unread with the unread count; one entry draws no strip |
+| `size` | `'sm' \| 'md'` | md | NotificationCenter, NotificationCenterDefaultsProvider | sm for the popover: the small type steps, tighter insets, the small inner-control box. md for the page |
+| `level` | `'2' \| '3' \| '4'` | 2 | NotificationCenter, NotificationCenterDefaultsProvider | The rank of the header’s heading; group labels take the rank below |
+| `growing` | `'none' \| 'button' \| 'scroll'` | none | NotificationCenter, NotificationCenterDefaultsProvider | How more is loaded: never, on a button, or when the sentinel under the feed enters the scrollport |
+| `arrivals` | `'hold' \| 'show'` | hold | NotificationCenter, NotificationCenterDefaultsProvider | 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 | NotificationCenter, NotificationCenterDefaultsProvider | How time is written: há 2 horas with the absolute reading in title, or the absolute reading alone |
+| `controls` | `'both' \| 'read' \| 'dismiss' \| 'none'` | both | NotificationCenter, NotificationCenterDefaultsProvider | Which of the family’s two item controls are drawn |
+| `loading` | `boolean` | false | NotificationCenter | aria-busy on the feed and data-loading on the root; skeleton rows while nothing is loaded, the waiting row under the feed otherwise |
+| `count` | `number` | — | NotificationCenter | How many items exist in all, for aria-setsize. Unstated, the loaded number under growing="none" and -1 while more may come |
+| `groupBy` | `(item) => ReactNode` | — | NotificationCenter | 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 | NotificationCenter, NotificationCenterDefaultsProvider (timeZone) | What the time is formatted with. State now for a stable server render of a relative time |
+| `messages` | `PartialMessages<NotificationCenterMessages>` | — | NotificationCenter | 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 |
+| `actions, footer, empty` | `ReactNode` | — | NotificationCenter | The consumer’s controls in the header after mark-all; the link from the popover to the page; the ResultState in place of the family’s empty words |
+| `renderItem` | `(item, state) => ReactNode` | — | NotificationCenter | Substitutes an item’s content. state carries 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 |
+| `render` | `(props) => ReactNode` | — | NotificationCenter | Substitutes the root element and hands it every attribute, the ref callback included |
+| `ref` | `Ref<NotificationCenterHandle>` | — | NotificationCenter | The element; focus(), which lands on fresh when arrivals are held and on the first article otherwise; reveal(); markAllRead() — the last two with the reason programmatic |
+| `NotificationCenterDefaultsProvider` | `{ size, level, growing, arrivals, timeFormat, controls, timeZone }` | — | a subtree | The decisions an application takes once. A centre that states any of them itself still wins |
+| `native props` | `ComponentPropsWithRef<"section">` | — | NotificationCenter | aria-*, data-*, className, style and handlers reach the section; a consumer’s aria-label or aria-labelledby replaces the title wiring |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onViewChange` | `(view: string, request: ChangeRequest<string>)` | Before the view moves. The request carries the new value, the value it replaces, the reason — pointer or keyboard from the strip, programmatic from the consumer — the originating event, and cancel(), which refuses the move before anything commits. |
+| `onReadChange` | `({ keys, read }, request: { reason, source, cancelled, cancel() })` | When the reader presses a read-toggle (one key), mark-all (every unread shown key) or the handle’s markAllRead() — reasons pointer, keyboard, programmatic. The family marks nothing itself: the store answers by changing items. |
+| `onRemove` | `(key: string, request: { reason, source, 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. |
+| `onOpen` | `(key: string, request: { reason, source, cancelled, cancel() })` | Before a title link navigates — reasons pointer, keyboard. cancel() prevents the navigation. |
+| `onReveal` | `(count: number, request: { reason, source, cancelled, cancel() })` | Before held arrivals are shown: a press of fresh (pointer, keyboard) or the handle’s reveal() (programmatic). A keyboard reveal moves focus to the first revealed article. |
+| `onLoadMore` | `(request: { reason, source, 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. |
+| `onUnreadChange` | `(count: number)` | A fact, not a request: on mount and whenever the unread count among items changes, for the bell in the top navigation. |
+| `onKeyDown, onClick, onFocus on the root` | `the element’s own events` | Whenever the section fires them. The consumer’s onKeyDown runs before the feed keys, and a defaultPrevented event stops them. |
+
+## 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 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
+
+```tsx
+<NotificationCenter
+  actions={<Link href="/preferencias">Preferências</Link>}
+  footer={<Link href="/notificacoes">Ver todas as notificações</Link>}
+  groupBy={dayOf}
+  growing="button"
+  items={items}
+  views={views}
+/>;
+```
+
+### Read is the store’s fact
+
+Press the check on an unread row: the family asks onReadChange 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
+
+```tsx
+const onReadChange = ({ keys, read }: NotificationCenterReadChange) =>
+  setItems((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 controlled view that refuses to leave All.
+
+Excerpt — not a complete module
+
+```tsx
+<NotificationCenter
+  items={view === 'mentions' ? mentions : items}
+  onViewChange={(next, request) => {
+    if (next === 'archived') request.cancel();
+    else setView(next);
+  }}
+  view={view}
+  views={[
+    { value: 'all', label: 'Todas' },
+    { value: 'mentions', label: 'Menções', count: mentions.length },
+    { value: 'archived', label: 'Arquivadas' },
+  ]}
+/>;
+```
+
+### 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
+
+```tsx
+<NotificationCenter
+  arrivals="hold"
+  items={items}
+  onReveal={(count, request) =>
+    analytics.track('notifications.reveal', { count, reason: request.reason })
+  }
+/>;
+```
+
+### 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
+
+```tsx
+<NotificationCenter groupBy={(item) => (isToday(item.time) ? 'Hoje' : 'Ontem')} items={items} />;
+```
+
+### 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
+
+```tsx
+<NotificationCenter
+  count={total}
+  growing="scroll"
+  items={items}
+  loading={loading}
+  onLoadMore={(request) => loadPage(request.reason)}
+/>;
+```
+
+### 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
+
+```tsx
+<NotificationCenter
+  actions={<Link href="/preferencias">Preferências</Link>}
+  controls="dismiss"
+  items={items.map((item) => ({
+    ...item,
+    actions: item.shipment ? <Button size="sm">Ver expedição</Button> : undefined,
+  }))}
+/>;
+```
+
+### Hosts
+
+The bell is a Popover trigger with the unread count the family reports through onUnreadChange; 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
+
+```tsx
+<Popover>
+  <PopoverTrigger
+    render={(props) => (
+      <Button {...props} aria-label={`Notificações, ${unread} não lidas`}>
+        <BellIcon />
+      </Button>
+    )}
+  />
+  <PopoverLayer>
+    <PopoverContent aria-label="Notificações">
+      <NotificationCenter
+        footer={<Link href="/notificacoes">Ver todas as notificações</Link>}
+        items={items}
+        onUnreadChange={setUnread}
+        size="sm"
+      />
+    </PopoverContent>
+  </PopoverLayer>
+</Popover>;
+```
+
+### 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
+
+```tsx
+<NotificationCenter items={[]} loading />;
+```
+
+### Empty
+
+A feed with nothing shows messages.empty; the unread view with nothing unread shows messages.caughtUp — All caught up. The empty prop replaces both with a ResultState of the consumer’s own.
+
+Excerpt — not a complete module
+
+```tsx
+<NotificationCenter
+  empty={
+    <ResultState reach="inline" status="success">
+      <ResultStateContent>
+        <ResultStateTitle>Tudo lido</ResultStateTitle>
+        <ResultStateDescription>Nada aguarda a sua atenção.</ResultStateDescription>
+      </ResultStateContent>
+    </ResultState>
+  }
+  items={[]}
+/>;
+```
+
+### 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 "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
+
+```tsx
+<NotificationCenter items={items} level="3" size="sm" />;
+```
+
+### 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, 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. renderItem substitutes the content of a row — a Text and a Badge here — while the article, its wiring and its controls stay the family’s.
+
+Excerpt — not a complete module
+
+```tsx
+<NotificationCenter
+  items={items}
+  renderItem={(item, state) => (
+    <>
+      <span data-part="title" id={state.ids.title}>
+        {item.title}
+      </span>
+      <Badge size="sm" tone={state.tone} variant="soft">
+        {item.category}
+      </Badge>
+      <time data-part="time" dateTime={state.time.dateTime}>
+        {state.time.text}
+      </time>
+    </>
+  )}
+/>;
+```
+
+### Defaults and the handle
+
+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 handle focuses the first article, reveals held arrivals and marks every shown item read with the reason programmatic.
+
+Excerpt — not a complete module
+
+```tsx
+<NotificationCenterDefaultsProvider growing="button" size="sm" timeZone="Europe/Lisbon">
+  <App />
+</NotificationCenterDefaultsProvider>;
+```
+
+### 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 onOpen before the link navigates.
+
+Excerpt — not a complete module
+
+```tsx
+<NotificationCenter
+  items={items}
+  onOpen={(key, request) => {
+    if (!canOpen(key)) request.cancel();
+  }}
+  onRemove={(key, request) => {
+    if (request.reason === 'keyboard' && !confirmed(key)) request.cancel();
+    else remove(key);
+  }}
+/>;
+```
+
+### 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
+
+```tsx
+<NotificationCenter aria-label="Caixa de entrada da equipa de vendas" items={items} />;
+```