@blackcube/aurelia-kit 1.0.0-rc4 → 1.0.0-rc6

package/README.md

@@ -61,7 +61,35 @@ An element that must leave the layout when hidden also carries the HTML `hidden`
 (Tailwind's preflight turns it into `display: none`); the attribute toggles it, never a class.
 
 Attribute options use the Aurelia multi-binding syntax, as written by the PHP widgets:
-`bleet-toaster-trigger="color: success; title: Saved; content: Done; duration: 3000"`.
+`bleet-toaster-trigger="level: success; title: Saved; content: Done; duration: 3000"`.
+
+## Abstract components
+
+For a SPA, where the application renders its own markup, the kit gives the behavior of a component as an abstract
+class, without markup: the application's element extends it and gives its template — its markup, its classes, its
+texts, its icons. The abstract classes are not registered; the element that extends them is, by the application.
+
+```typescript
+import { customElement } from 'aurelia';
+import { AbstractDialog } from '@blackcube/aurelia-kit';
+
+@customElement('app-drawer')
+export class AppDrawer extends AbstractDialog {}
+```
+
+- The bindables and the lifecycle of the abstract class are inherited: Aurelia reads the bindables along the prototype
+  chain. An element that overrides `attached()` or `detaching()` calls `super`.
+- The template binds the members of the instance directly (`${title}`, `toast of toasts`) and gives the refs the names
+  the class reads (`ref="dialogElement"`).
+- The state classes of the host (`data-<name>-show`, `data-<name>-hide`) and its attributes (`popover`) go on the root
+  `<template>` of the template: Aurelia carries them to the host.
+
+| Class | Component |
+|---|---|
+| `AbstractDialog` | a dialog: modal, drawer — see [Dialogs](#dialogs) |
+| `AbstractDropdown` | a dropdown: searchable, multiple — see [`AbstractDropdown`](#abstractdropdown-spa) |
+| `AbstractPager` | the pagination of a list — see [`AbstractPager`](#abstractpager-spa) |
+| `AbstractToaster` | the toaster — see [Toasts](#toasts) |
 
 ## Overlay
 
@@ -157,7 +185,6 @@ Behavior:
 ```typescript
 interface IDialogResponse {
     content?: string;         // the whole HTML of the dialog
-    color?: UiColor;          // not used by the element: the server HTML carries its own colors
     icon?: string | null;     // not used by the element: the server HTML carries its own icon
     action?: DialogAction;    // Close closes the dialog, RefreshAndClose closes it and reloads the page
     toast?: IToast;           // published on Channels.Toaster
@@ -167,30 +194,43 @@ interface IDialogResponse {
 }
 ```
 
-PHP side, `AureliaCommunication::dialogContent($content, $color)` builds the `content` / `color` part of it.
+PHP side, `AureliaCommunication::dialogContent($content)` builds the `content` part of it: the look of the dialog is
+in its HTML.
 
-**In a SPA**, the content is the application's: its frame and its view go in the default slot of `<bleet-dialog>`,
-written once in the shell, and the dialog is opened without `url`:
+**In a SPA**, the frame is the application's: its element extends `AbstractDialog` (see
+[Abstract components](#abstract-components)), its template holds the `<dialog ref="dialogElement">`, and the dialog is
+opened without `url`:
+
+```typescript
+@customElement('app-drawer')
+export class AppDrawer extends AbstractDialog {}
+```
 
 ```html
-<bleet-dialog id="drawer"
-              data-dialog-class="… translate-x-full"
-              data-dialog-show="translate-x-0"
-              data-dialog-hide="translate-x-full">
-    <header …>${$host.title} <button type="button" data-dialog="close">…</button></header>
-    <au-viewport name="drawer"></au-viewport>
-</bleet-dialog>
+<template data-dialog-show="translate-x-0" data-dialog-hide="translate-x-full">
+    <dialog ref="dialogElement" class="… translate-x-full" aria-label.bind="title || null">
+        <header …>${title} <button type="button" data-dialog="close">…</button></header>
+        <au-slot></au-slot>
+    </dialog>
+</template>
 ```
 
 ```typescript
-resolve(IEventAggregator).publish(Channels.Modal, <IModal>{ action: ModalAction.Open, id: 'drawer', title: 'Edit user', color: UiColor.Primary });
+resolve(IEventAggregator).publish(Channels.Modal, <IModal>{ action: ModalAction.Open, id: 'drawer', title: 'Edit user' });
 ```
 
-- `Open` (or `Toggle` when closed) with neither `url` nor `content` opens the dialog on its default slot; its `title`
-  and `color` are kept on the element for the frame (`$host.title`, `$host.color`) until it is closed. The `title` is
-  also the accessible name of the `<dialog>` (`aria-label`).
-- A form of the default slot is not posted by the element: it belongs to the page that projects it.
+| `AbstractDialog` | Meaning |
+|---|---|
+| `id` (bindable) | the id of the dialog on `Channels.Modal` |
+| `title` | the one of the opening, kept until the dialog is closed |
+| `dialogElement` | the `<dialog>` of the template (`ref`) |
+| `show(data)`, `close()`, `clear()` | protected, to extend: an opening, a closing, what to clear once closed |
+
+- `Open` (or `Toggle` when closed) opens the dialog; Escape, any `[data-dialog="close"]`, `Close` and `Toggle` close it
+  through the hide transition — a menu open inside (`aria-expanded`) is closed first.
+- What the slot holds belongs to the page that projects it, its forms included.
 - `ModalStatus.Closed` with the `id` tells the page the dialog is closed (its route can be left).
+- `<bleet-dialog>` itself extends `AbstractDialog`, with the server HTML on top of it.
 
 ## Ajaxify
 
@@ -245,7 +285,7 @@ Markup it expects:
 <div bleet-toaster popover="manual"
      class="fixed inset-auto top-4 right-0 z-70 m-0 p-0 pr-4 border-0 bg-transparent overflow-visible flex flex-col gap-4 pointer-events-none">
 
-    <!-- one template per UiColor: primary, secondary, success, danger, warning, info, accent -->
+    <!-- one template per UiLevel: info, success, warning, danger -->
     <template data-toaster="success">
         <div class="… translate-x-full opacity-0 transition-all duration-500"
              data-toaster-show="translate-x-0 opacity-100"
@@ -271,24 +311,24 @@ box of a popover (`inset`, `margin`, `padding`, `border`, `background`, `overflo
 
 Behavior:
 
-- `ToasterAction.Add`: clones `template[data-toaster=<color>]`, puts the icon of
+- `ToasterAction.Add`: clones `template[data-toaster=<level>]`, puts the icon of
   `template[data-toaster=icon-<icon>]` in the `icon` slot, fills `title` and `content`, appends the card to the
   container, then swaps its hide classes for its show classes. With `duration` > 0 the toast closes itself after
   `duration` ms; `0` keeps it until it is closed.
 - `ToasterAction.Remove` (or a click on `close`): swaps the show classes for the hide classes, waits for the end
   of the transition, removes the card.
-- A toast whose `id` is already displayed is ignored. A color without template is logged and ignored.
+- A toast whose `id` is already displayed is ignored. A level without template is logged and ignored.
 
 Publishing a toast from TypeScript:
 
 ```typescript
 import { resolve, IEventAggregator } from 'aurelia';
-import { Channels, IToaster, ToasterAction, UiColor, UiToastIcon } from '@blackcube/aurelia-kit';
+import { Channels, IToaster, ToasterAction, UiLevel, UiToastIcon } from '@blackcube/aurelia-kit';
 
 resolve(IEventAggregator).publish(Channels.Toaster, <IToaster>{
     action: ToasterAction.Add,
     toast: {
-        color: UiColor.Success,
+        level: UiLevel.Success,
         icon: UiToastIcon.Success,
         title: 'Saved',
         content: 'The page has been saved.',
@@ -305,7 +345,7 @@ interface IToaster {
 
 interface IToast {
     id?: string;             // generated when absent
-    color: UiColor;          // default Info
+    level: UiLevel;          // default Info
     icon?: UiToastIcon;      // default Info
     title?: string;
     content: string;         // HTML
@@ -319,51 +359,55 @@ Publishes one toast when the page loads (after `DOMContentLoaded`). Rendered by
 as a hidden element:
 
 ```html
-<div hidden bleet-toast="color: success; icon: check-circle; title: Saved; content: Done; duration: 3000"></div>
+<div hidden bleet-toast="level: success; icon: check-circle; title: Saved; content: Done; duration: 3000"></div>
 ```
 
-Options: `id`, `color`, `icon`, `title`, `content`, `duration` (same meaning as `IToast`).
+Options: `id`, `level`, `icon`, `title`, `content`, `duration` (same meaning as `IToast`).
 
 ### `bleet-toaster-trigger`
 
 Publishes one toast on click. Rendered by `Bleet::toast()->…->trigger()` as attributes of another element:
 
 ```html
-<button bleet-toaster-trigger="color: success; content: Saved!">Save</button>
+<button bleet-toaster-trigger="level: success; content: Saved!">Save</button>
 ```
 
-Options: `id`, `color`, `icon`, `title`, `content`, `duration`.
+Options: `id`, `level`, `icon`, `title`, `content`, `duration`.
+
+### `AbstractToaster` (SPA)
 
-### `<bleet-toaster>` (SPA)
+The toaster of a SPA, where the application renders the markup: the same channel, the same payload and the same state
+classes as the `bleet-toaster` attribute, each toast rendered by the template of the application's element, which
+extends `AbstractToaster` (see [Abstract components](#abstract-components)). The host is the stack.
 
-The toaster of a SPA, where the application's templates render the markup: the same channel, the same payload and the
-same state classes as the `bleet-toaster` attribute, but each toast is rendered by Aurelia from the markup the
-application projects into the element. The element holds no markup and no class of its own: its template only repeats
-its default slot, once per toast, the toast exposed as `$host`.
+```typescript
+@customElement('app-toaster')
+export class AppToaster extends AbstractToaster {}
+```
 
 ```html
-<bleet-toaster popover="manual" class="fixed inset-auto top-4 right-0 … flex flex-col gap-4 pointer-events-none">
-    <div data-toaster-id.bind="$host.id"
+<template popover="manual" class="fixed inset-auto top-4 right-0 … flex flex-col gap-4 pointer-events-none">
+    <div repeat.for="toast of toasts" data-toaster-id.bind="toast.id"
          class="… translate-x-full opacity-0 transition-all duration-500"
          data-toaster-show="translate-x-0 opacity-100"
          data-toaster-hide="translate-x-full opacity-0">
-        … ${$host.title} … <div innerhtml.bind="$host.content"></div> …
-        <button type="button" click.trigger="$host.close($event)">…</button>
+        … ${toast.title} … <div innerhtml.bind="toast.content"></div> …
+        <button type="button" click.trigger="onClickClose($event, toast.id)">…</button>
     </div>
-</bleet-toaster>
+</template>
 ```
 
-| `$host` (`IToastView`) | Meaning |
+| `AbstractToaster` | Meaning |
 |---|---|
-| `id`, `color`, `icon`, `title`, `content`, `duration` | the published toast, with the defaults of the attribute |
-| `close(event)` | closes the toast (its button) |
+| `toasts` | the toasts shown: `id`, `level`, `icon`, `title`, `content`, `duration`, with the defaults of the attribute |
+| `onClickClose(event, id)` | closes the toast (its button) |
 
 Behavior:
 
-- The root of the projected toast carries `data-toaster-id="${$host.id}"`: once rendered, its hide classes are
-  swapped for its show classes; `close()`, `ToasterAction.Remove` or the end of its `duration` swap them back, then the
+- The root of each rendered toast carries `data-toaster-id="${toast.id}"`: once rendered, its hide classes are
+  swapped for its show classes; its button, `ToasterAction.Remove` or the end of its `duration` swap them back, then the
   toast leaves the list once the transition ends.
-- With `popover="manual"` on the element, it is shown again on each toast and hidden once the last one is gone, as the
+- With `popover="manual"` on the host, it is shown again on each toast and hidden once the last one is gone, as the
   attribute's container.
 - The texts, the icons and the classes are the application's: its i18n, its icon component, its theme.
 
@@ -521,6 +565,43 @@ Behavior:
   select to `N`.
 - Changing the select clicks the matching button.
 
+### `AbstractPager` (SPA)
+
+The pagination of a list in a SPA — yii-bleet's `Pager` widget with buttons instead of links: the application's element
+extends `AbstractPager` (see [Abstract components](#abstract-components)) and renders the window of numbers around the
+current page. The pagination is `@blackcube/aurelia-api`'s (`IPagination`), given as it is by the page; a page chosen is
+announced on the host (`PagerEvent.Change`, `bleet-page`, its `detail` an `IPagerDetail`): the page writes it in its URL
+and reloads its list, whose new pagination comes back.
+
+```typescript
+@customElement('app-pager')
+export class AppPager extends AbstractPager {}
+```
+
+```html
+<template>
+    <nav if.bind="pagination.totalPages > 1">
+        <button if.bind="page > 1" type="button" click.trigger="onClickPage($event, page - 1)">…</button>
+        <button repeat.for="number of numbers" type="button" aria-current.bind="number === page ? 'page' : null"
+                click.trigger="onClickPage($event, number)">${number}</button>
+        <button if.bind="page < pagination.totalPages" type="button" click.trigger="onClickPage($event, page + 1)">…</button>
+    </nav>
+</template>
+```
+
+```html
+<app-pager pagination.bind="pagination" bleet-page.trigger="onChangePage($event)"></app-pager>
+```
+
+| `AbstractPager` | Meaning |
+|---|---|
+| `pagination` | `IPagination`: `limit`, `currentPage`, `totalPages`, `totalCount` |
+| `maxButtonCount` | how many numbers at most (10) |
+| `page`, `numbers`, `begin`, `end` | the page shown, the window of numbers around it, the range of the items shown |
+| `selectedPage` | two-way with a dropdown of the pages (a narrow screen): a choice in it goes to that page |
+| `onClickPage(event, number)` | a number, previous, next |
+| `refreshed()` | protected, to extend: what the element adds once the pages are computed again |
+
 ## Forms
 
 ### `bleet-password`
@@ -600,6 +681,56 @@ Behavior:
   is selected, the `count` template text beyond.
 - The panel does not open while the native select is disabled.
 
+### `AbstractDropdown` (SPA)
+
+The dropdown of a SPA, driven by its data rather than by a native select: the application's element extends
+`AbstractDropdown` (see [Abstract components](#abstract-components)) and renders its rows; the values are typed — an
+id, an enum — and bound both ways.
+
+```typescript
+@customElement('app-select')
+export class AppSelect<T> extends AbstractDropdown<T> {}
+```
+
+```html
+<template>
+    <button ref="button" type="button" aria-expanded.bind="open ? 'true' : 'false'" click.trigger="onClickToggle($event)">
+        ${selection.length > 0 ? selection[0].label : placeholder}
+    </button>
+    <div ref="panel" hidden.bind="open === false" role="listbox">
+        <input ref="search" value.bind="query">
+        <template repeat.for="group of groups">
+            <div if.bind="group.label">${group.label}</div>
+            <button repeat.for="row of group.rows" type="button" role="option" aria-selected.bind="row.selected ? 'true' : 'false'"
+                    disabled.bind="row.disabled" click.trigger="onClickItem($event, row)">${row.label}</button>
+        </template>
+        <div if.bind="empty">…</div>
+    </div>
+</template>
+```
+
+```html
+<app-select options.bind="schools" value.two-way="model.schoolId" placeholder="Choose"></app-select>
+<app-select multiple.bind="true" options.bind="roles" values.two-way="model.roles"></app-select>
+```
+
+| `AbstractDropdown` | Meaning |
+|---|---|
+| `options` | `IDropdownOption[]`: `value`, `label`, `group`, `disabled` |
+| `value`, `values` | two-way: the choice, or the choices with `multiple` |
+| `multiple`, `disabled`, `placeholder` | bindables |
+| `open`, `query`, `empty` | the panel is open; the text searched (the search field binds it); nothing matches |
+| `groups`, `selection` | the rows matching the query by group (`IDropdownRow`: `value`, `label`, `disabled`, `selected`); the rows chosen |
+| `button`, `panel`, `search` | the button, the panel and the optional search field of the template (`ref`) |
+| `onClickToggle(event)`, `onClickItem(event, row)`, `onClickRemove(event, row)` | the button, a row, the remove control of a tag |
+
+- A single choice sets `value` and closes the panel; with a `placeholder`, a first row sets it back to `null`. A
+  multiple one toggles in `values`, the panel staying open.
+- The rows are built once per set of options; a choice changes their state in place, the rendered rows stay.
+- Open, the focus is trapped in the panel (`ITrapFocusService`): Tab loops, the arrows move, Escape and a click outside
+  close it. It opens on the search field, else on its selection, scrolled into view.
+- A remove control inside the button is not a `<button>`: the HTML parser closes a button at the next one.
+
 ### `bleet-focus`
 
 An element that takes the focus as it appears — a field or a message shown later (a condition of the page, a fragment
@@ -623,7 +754,8 @@ resolve(IEventAggregator).publish(Channels.Upload, <IUpload>{ action: UploadActi
 ## Exports
 
 Attributes: `BleetToasterCustomAttribute`, `BleetToastCustomAttribute`, `BleetToasterTriggerCustomAttribute`,
-and the attributes of the other widgets. Enums: `Channels`, `ToasterAction`, `ToasterStatus`, `UiColor`,
+and the attributes of the other widgets. Abstract components: `AbstractDialog`, `AbstractDropdown`, `AbstractPager` (its `PagerEvent`, `IPagerDetail`),
+`AbstractToaster`. Enums: `Channels`, `ToasterAction`, `ToasterStatus`, `UiLevel`,
 `UiToastIcon`, `UiIcon`, and the actions and statuses of the other channels. Interfaces: `IToaster`, `IToast`,
 and the payloads of the other channels. Services: `IStorageService`, `ITransitionService`, `ITrapFocusService`.