@blackcube/aurelia-kit 1.0.0-rc1 → 1.0.0-rc10

package/README.md

@@ -12,7 +12,7 @@ widgets, styled with Tailwind classes written in the PHP markup. The HTTP layer
 npm install @blackcube/aurelia-kit @blackcube/aurelia-api
 ```
 
-Peer dependencies: `aurelia` `^2.0.0-rc.2`, `@blackcube/aurelia-api` `^1.0.0`.
+Peer dependencies: `aurelia` `^2.0.0-rc.2`, `@blackcube/aurelia-api` `^1.0.0-rc1`.
 
 The package is ESM only (`dist/index.es.js`, built by Vite in library mode); the application bundler resolves it.
 
@@ -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
 
@@ -101,6 +129,7 @@ sends. Its template holds no markup of its own:
     <au-slot name="loader" if.bind="loading"><progress></progress></au-slot>
     <template else>
         <au-compose if.bind="contentView" template.bind="contentView"></au-compose>
+        <au-slot else></au-slot>
     </template>
 </dialog>
 ```
@@ -140,18 +169,22 @@ Behavior:
 - `content` is the whole HTML of the dialog (frame, header, body, footer), rendered by the server; it becomes the
   view of the `au-compose`, so the `bleet-*` attributes it holds work. A response without `content` keeps the
   current view.
+- `Open` (or `Toggle` when closed) with a `content` and no `url`: that HTML is shown as the server's would be, without
+  request (the same view, its `bleet-*` attributes, its forms posted by the element) — a page that already holds the
+  HTML (a confirmation, a `<template>` of the page).
 - A `<form>` submitted inside the dialog is posted by the element (multipart, method from `_method` or the form,
   POST by default, with the clicked submit button `name` / `value`); its `IDialogResponse` is applied the same way.
 - A `<form>` marked `data-dialog="native"` is not intercepted: the browser submits it (download, plain post).
 - A click on an element inside `[data-dialog="close"]`, the Escape key, or a click on the overlay closes the dialog
   with the hide transition; closing empties the view. A `cancel` coming from an `<input type="file">` (file chooser
   dismissed) does not close it. An `Open` received while the dialog is closing cancels the closing.
+- Escape while a menu of the dialog is open (`[aria-expanded="true"]`: `bleet-dropdown`, `bleet-profile`) closes
+  that menu, not the dialog.
 - Statuses `Opening`, `Opened`, `Closing`, `Closed` (with the `id`) on `Channels.ModalStatus`.
 
 ```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
@@ -161,7 +194,45 @@ 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 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
+<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' });
+```
+
+| `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.
+- `Open` on a dialog already open only renews its `title`: the page shown in it changed (a creation turned into its
+  edition), the dialog stays.
+- 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
 
@@ -216,7 +287,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"
@@ -242,24 +313,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.',
@@ -276,7 +347,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
@@ -290,20 +361,57 @@ 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`, `level`, `icon`, `title`, `content`, `duration`.
+
+### `AbstractToaster` (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.
+
+```typescript
+@customElement('app-toaster')
+export class AppToaster extends AbstractToaster {}
 ```
 
-Options: `id`, `color`, `icon`, `title`, `content`, `duration`.
+```html
+<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">
+        … ${toast.title} … <div innerhtml.bind="toast.content"></div> …
+        <button type="button" click.trigger="onClickClose($event, toast.id)">…</button>
+    </div>
+</template>
+```
+
+| `AbstractToaster` | Meaning |
+|---|---|
+| `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 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 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.
 
 ## Alerts
 
@@ -390,7 +498,13 @@ Behavior:
 
 - Listens on `Channels.Menu`: `MenuAction.Open` applies the show classes and opens the overlay, `MenuAction.Close`
   applies the hide classes and closes the overlay, `MenuAction.Toggle` does one or the other. `aria-hidden` follows.
-- A click on `[data-menu=close]` closes the menu; the menu closes too when the overlay closes.
+- A click on `[data-menu=close]` closes the menu; the menu closes too when the overlay closes, on `Escape` and on a
+  click on a link of the menu (the link is followed).
+- Open, the focus is trapped in the menu (`ITrapFocusService`), on `[data-menu=close]` first; once closed, it goes back
+  to what opened the menu (the burger).
+- The page follows: `<body>` takes the classes of the menu's `data-menu-page-show` while it is open and of its
+  `data-menu-page-hide` once closed — `data-menu-page-show="overflow-hidden"` keeps the page from scrolling under it.
+  Without these attributes, the page is left as is.
 - Publishes `MenuStatus.Opening`, `Opened`, `Closing`, `Closed` on `Channels.MenuStatus`.
 - `[data-menu=toggle-button-ID]` shows or hides `[data-menu=toggle-list-ID]` (`hidden` attribute), sets the
   data-menu-show / data-menu-hide classes of its `svg[data-menu=icon]` and its `aria-expanded`. Accordion: opening a
@@ -459,6 +573,43 @@ Behavior:
   select to `N`.
 - Changing the select clicks the matching button.
 
+### `AbstractPager` (SPA)
+
+The pagination of a list in a SPA — 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`
@@ -538,6 +689,88 @@ 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. A list
+  computed again with the same content (a new array, the same options) is not a new set: the rows stay too, and so
+  does the one that has the focus.
+- 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
+loaded by ajaxify):
+
+```html
+<input bleet-focus …>
+```
+
+When attached, the element is focused on the next frame; the browser brings it into view.
+
+### `bleet-first-error`
+
+A form whose first field in error takes the focus when the page says « refused » (a SPA validating its form before
+posting it):
+
+```html
+<form bleet-first-error="account" submit.trigger="onSubmit($event)" novalidate>
+    <input aria-invalid.bind="…" …>
+</form>
+```
+
+`Channels.Form` carries `IForm` (`{ action: FormAction.FirstError, id?: string }`): the form whose `id` is given,
+every form without id, focuses its first `[aria-invalid=true]` on the next frame — once the invalid marks of the fields
+are rendered. A form without a field in error does nothing.
+
+```typescript
+resolve(IEventAggregator).publish(Channels.Form, <IForm>{ action: FormAction.FirstError, id: 'account' });
+```
+
 ## Upload channel
 
 `Channels.Upload` carries `IUpload` (`{ action: UploadAction.Reset, id?: string }`) for the upload bridges
@@ -550,7 +783,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`.