chuijs 4.0.3 → 4.0.4

package/framework/components/chui_stepper/stepper.js

@@ -1,24 +1,40 @@
 const { setStyles, optionOr } = require("../../modules/chui_functions");
 const { Icon, Icons } = require("../chui_icons/icons");
 const { I18n } = require("../../modules/chui_i18n/chui_i18n");
+const { Animation } = require("../../modules/chui_animations/animations");
+const { Spinner } = require("../chui_spinner/spinner");
 
 /**
- * Шаги процесса: пройденные, текущий и предстоящие.
+ * Шаги процесса: пройденные, текущий и предстоящие — и их состояния.
  *
  * Разметка — настоящий `<ol>` со `<li>`, поэтому скринридер читает «список из N шагов», имя
  * списка задаёт опция `label` (по умолчанию «Шаги»). Линии между маркерами — по две полулинии
  * у каждого шага (до и после маркера): так они сходятся без дыр, растягиваются на любую ширину
  * и остаются внутри `<li>` — список не ломается посторонними узлами.
  *
+ * **Состояние шага.** Обычно оно идёт по месту: пройденный, текущий, предстоящий. Но шаг
+ * может нести и своё — `status` у шага или `setStatus(index, status)`: `Stepper.STATUS.DONE`
+ * (зелёная подсветка и галочка), `Stepper.STATUS.ERROR` (красная подсветка и крест)
+ * и `Stepper.STATUS.PENDING` (спиннер: шаг выполняется). `undefined` возвращает шаг
+ * к состоянию по месту. Состояния сообщаются слушателям — `addStatusListener` и опция
+ * `onStatus`: по ним приложение возвращает человека на шаг, где что-то пошло не так,
+ * а сам `setStatus` переход не делает.
+ *
+ * **Переходы идут движением.** Состояние применяется на месте, не пересборкой: узлы те же,
+ * поэтому смена цвета маркера и рост заливки линии читаются переходом, знак состояния
+ * появляется кадром, а фокус и прокрутка остаются на месте.
+ *
  * Доступность: текущий шаг помечен `aria-current="step"`, маркер имеет имя «Шаг 2 из 4.
  * Текущий шаг», а у кликабельного шага маркер — настоящий `<button>` (Tab и Enter/Space родные)
- * с тем же именем и названием шага. Смена шага объявляется скрытым `role="status"`.
+ * с тем же именем и названием шага. Смена шага и состояния объявляется скрытым `role="status"`.
  *
  * ```javascript
  * const steps = new Stepper({steps: [{title: 'Корзина'}, {title: 'Доставка'}, {title: 'Оплата'}],
  *     active: 1, clickable: true, onChange: (index) => wizard.go(index)});
  * steps.setActive(2);          // программный переход (уведомляет)
  * steps.setActive(2, true);    // тихий: только вид, без уведомления
+ * steps.setStatus(2, Stepper.STATUS.PENDING);
+ * steps.setStatus(2, Stepper.STATUS.ERROR);    // уведомляет слушателей состояния
  * ```
  *
  * Слушателей и таймеров вне своих узлов нет, поэтому `destroy()` не нужен.
@@ -32,6 +48,12 @@ class Stepper {
         SMALL: "small",
         DEFAULT: "default",
     };
+    /** Состояния шага: пройден, ошибка и ожидание выполнения */
+    static STATUS = {
+        DONE: "done",
+        ERROR: "error",
+        PENDING: "pending",
+    };
     static #counter = 0;
 
     #root = document.createElement("chui_stepper");
@@ -39,11 +61,14 @@ class Stepper {
     #status = document.createElement("stepper_status");
     #id = undefined;
     #items = [];
+    #nodes = [];
     #markers = [];
     #active = 0;
     #clickable = false;
     #listeners = [];
-    #on_change = undefined;
+    #statusListeners = [];
+    #onChange = undefined;
+    #onStatus = undefined;
 
     constructor(
         options = {
@@ -56,6 +81,8 @@ class Stepper {
             label: String(),
             onChange: undefined,
             changeEvent: undefined,
+            onStatus: undefined,
+            statusEvent: undefined,
         }
     ) {
         setStyles(__dirname + "/styles.css", "chUiJS_Stepper");
@@ -67,8 +94,10 @@ class Stepper {
         this.#status.classList.add("chui_visually_hidden");
         this.#status.setAttribute("role", "status");
         this.#status.setAttribute("aria-live", "polite");
-        this.#on_change = options.onChange;
+        this.#onChange = options.onChange;
         if (options.changeEvent !== undefined) this.addChangeListener(options.changeEvent);
+        this.#onStatus = options.onStatus;
+        if (options.statusEvent !== undefined) this.addStatusListener(options.statusEvent);
         this.setOrientation(options.orientation === undefined ? Stepper.ORIENTATION.HORIZONTAL : options.orientation);
         this.setSize(options.size === undefined ? Stepper.SIZE.DEFAULT : options.size);
         this.setClickable(options.clickable === true);
@@ -104,6 +133,20 @@ class Stepper {
         return item === undefined ? undefined : item.title;
     }
 
+    /**
+     * Состояние шага: `done`, `error`, `pending`, `current` или `todo`; `undefined`,
+     * если шага нет. Состояние по месту (`current`, `todo`) и заданное шагом (`done`,
+     * `error`, `pending`) приходят сюда одинаково
+     */
+    getStatus(index = Number()) {
+        return this.#items[index] === undefined ? undefined : this.#state(index);
+    }
+
+    /** Состояния всех шагов: годится для сводки «3 из 4 готовы» */
+    getStatuses() {
+        return this.#items.map((item, index) => this.#state(index));
+    }
+
     getOrientation() {
         return this.#root.dataset.orientation;
     }
@@ -119,7 +162,7 @@ class Stepper {
         return this;
     }
 
-    /** Шаги: `[{title, description, icon, disabled}]` */
+    /** Шаги: `[{title, description, icon, disabled, status}]` */
     setSteps(steps = Array()) {
         this.#items = Array.isArray(steps) ? steps.map((item) => Object.assign({}, item)) : [];
         this.#active = Stepper.#clamp(this.#active, this.#items.length);
@@ -142,13 +185,37 @@ class Stepper {
         const next = Stepper.#clamp(index, this.#items.length);
         const changed = next !== this.#active;
         this.#active = next;
-        this.#render();
+        // Состояние применяется на месте: узлы те же, поэтому переход читается движением,
+        // а фокус и прокрутка остаются на месте
+        this.#refresh();
         if (silent || !changed) return this;
         this.#announce();
         this.#notify();
         return this;
     }
 
+    /**
+     * Состояние шага: `Stepper.STATUS.{DONE, ERROR, PENDING}`; `undefined` возвращает шаг
+     * к состоянию по месту — пройден, текущий или предстоящий.
+     *
+     * Слушатели состояния (`addStatusListener`, `onStatus`) получают номер шага и его
+     * состояние. Сам `setStatus` на шаг не переходит: переход делает приложение — по событию
+     * оно возвращает человека туда, где что-то пошло не так.
+     */
+    setStatus(index = Number(), status = undefined) {
+        const item = this.#items[index];
+        if (item === undefined) return this;
+        const before = this.#state(index);
+        if (status === undefined || status === null) delete item.status;
+        else item.status = status;
+        const state = this.#state(index);
+        this.#refresh();
+        if (state === before) return this;
+        this.#announceStatus(index);
+        this.#notifyStatus(index, state);
+        return this;
+    }
+
     /** Направление шагов: `Stepper.ORIENTATION.{HORIZONTAL, VERTICAL}` */
     setOrientation(orientation = String()) {
         this.#root.dataset.orientation =
@@ -184,13 +251,28 @@ class Stepper {
         return this;
     }
 
+    /** Слушатель состояния шага: `(index, status, stepper) => {}` */
+    addStatusListener(listener = () => {}) {
+        this.#statusListeners.push(listener);
+        return this;
+    }
+
     // RENDER
     set() {
         return this.#root;
     }
 
     // === ВНУТРЕННЕЕ ===
+    /**
+     * Состояние шага. Своё состояние шага сильнее состояния по месту: шаг с ошибкой остаётся
+     * с ошибкой, даже когда человек ушёл дальше, — иначе знак ошибки пропадал бы со сменой шага
+     */
     #state(index = Number()) {
+        const item = this.#items[index];
+        const status = item === undefined ? undefined : item.status;
+        if (status === Stepper.STATUS.DONE || status === Stepper.STATUS.ERROR || status === Stepper.STATUS.PENDING) {
+            return status;
+        }
         if (index < this.#active) return "done";
         if (index === this.#active) return "current";
         return "todo";
@@ -198,7 +280,9 @@ class Stepper {
 
     #stateWord(index = Number()) {
         const state = this.#state(index);
-        if (state === "done") return I18n.t("navigation.stepDone");
+        if (state === Stepper.STATUS.DONE) return I18n.t("navigation.stepDone");
+        if (state === Stepper.STATUS.ERROR) return I18n.t("navigation.stepError");
+        if (state === Stepper.STATUS.PENDING) return I18n.t("navigation.stepPending");
         if (state === "current") return I18n.t("navigation.stepCurrent");
         return I18n.t("navigation.stepTodo");
     }
@@ -217,34 +301,70 @@ class Stepper {
         const focused = this.#markers.indexOf(document.activeElement);
         this.#list.innerHTML = "";
         this.#markers = [];
-        this.#items.forEach((item, index) => this.#list.appendChild(this.#item(item, index)));
+        this.#nodes = [];
+        this.#items.forEach((item, index) => {
+            const node = this.#item(item, index);
+            this.#nodes.push(node);
+            this.#list.appendChild(node);
+        });
         if (focused !== -1 && this.#markers[focused] !== undefined) this.#markers[focused].focus();
     }
 
+    /**
+     * Применить состояния заново — на тех же узлах (смена шага и состояния шага). Пересборка
+     * здесь была бы видна как вспышка: новый узел не помнит прошлого состояния, поэтому и цвет
+     * маркера, и заливка линии менялись бы рывком, а фокус терялся бы вовсе
+     */
+    #refresh() {
+        this.#items.forEach((item, index) => {
+            const node = this.#nodes[index];
+            if (node !== undefined) this.#apply(node, item, index);
+        });
+    }
+
+    /** Состояние одного шага: вид, роли и подписи */
+    #apply(node = undefined, item = Object(), index = Number()) {
+        const state = this.#state(index);
+        for (const name of ["done", "error", "pending", "current", "todo"]) {
+            node.classList.toggle(`stepper_item_${name}`, state === name);
+        }
+        node.dataset.state = state;
+        // Текущий шаг — тот, где мы стоим, и он остаётся им даже со своим состоянием:
+        // по нему идёт `aria-current`, а вид может быть занят ошибкой или спиннером
+        node.dataset.active = index === this.#active ? "true" : "false";
+        node.classList.toggle("stepper_item_clickable", this.#clickable && item.disabled !== true);
+        if (index === this.#active) node.setAttribute("aria-current", "step");
+        else node.removeAttribute("aria-current");
+        // Линия заполняется по шагу, от которого идёт: до маркера — предыдущим, после — им самим
+        node.querySelector(".stepper_line_before").classList.toggle(
+            "stepper_line_done",
+            index > 0 && this.#state(index - 1) === Stepper.STATUS.DONE
+        );
+        node.querySelector(".stepper_line_after").classList.toggle("stepper_line_done", state === Stepper.STATUS.DONE);
+        const marker = node.querySelector(".stepper_marker");
+        marker.setAttribute("aria-label", this.#markerLabel(index));
+        if (item.disabled === true) marker.setAttribute("aria-disabled", "true");
+        else marker.removeAttribute("aria-disabled");
+        this.#glyph(marker, item, index, state);
+    }
+
     #item(item = Object(), index = Number()) {
         const node = document.createElement("li");
         node.className = "stepper_item";
         node.dataset.index = String(index);
-        if (this.#state(index) === "current") {
-            node.setAttribute("aria-current", "step");
-            node.classList.add("stepper_item_current");
-        }
-        if (this.#state(index) === "done") node.classList.add("stepper_item_done");
-        if (this.#state(index) === "todo") node.classList.add("stepper_item_todo");
-        if (this.#clickable) node.classList.add("stepper_item_clickable");
-        node.appendChild(this.#line("before", index - 1));
+        node.appendChild(this.#line("before"));
         node.appendChild(this.#marker(item, index));
-        node.appendChild(this.#line("after", index));
+        node.appendChild(this.#line("after"));
         node.appendChild(this.#text(item));
+        this.#apply(node, item, index);
         return node;
     }
 
     // Полулиния соединителя: слева от маркера идёт шаг до него, справа — после
-    #line(position = String(), stateIndex = Number()) {
+    #line(position = String()) {
         const line = document.createElement("stepper_line");
         line.className = `stepper_line stepper_line_${position}`;
         line.setAttribute("aria-hidden", "true");
-        if (stateIndex >= 0 && stateIndex < this.#active) line.classList.add("stepper_line_done");
         return line;
     }
 
@@ -255,26 +375,62 @@ class Stepper {
         marker.dataset.index = String(index);
         if (clickable) {
             marker.type = "button";
-            // Кнопка означает «шаг можно выбрать», поэтому у неё есть и название шага
-            marker.setAttribute("aria-label", this.#markerLabel(index));
             marker.addEventListener("click", () => this.setActive(index));
         } else {
             // Маркер без действия — картинка со своим именем: номер и состояние не дублируются
             marker.setAttribute("role", "img");
-            marker.setAttribute("aria-label", this.#markerLabel(index));
-            if (item.disabled === true) marker.setAttribute("aria-disabled", "true");
-        }
-        const glyph = this.#state(index) === "done" && item.icon === undefined ? Icons.NAVIGATION.CHECK : item.icon;
-        if (glyph === undefined) marker.innerText = String(index + 1);
-        else {
-            const icon = new Icon(glyph, this.#iconSize()).set();
-            icon.setAttribute("aria-hidden", "true");
-            marker.appendChild(icon);
         }
         this.#markers.push(marker);
         return marker;
     }
 
+    /**
+     * Знак маркера по состоянию: галочка у пройденного, крест у ошибки, спиннер у шага,
+     * который выполняется, а в остальных случаях — свой значок шага или его номер.
+     *
+     * Знак пересобирается только когда он и впрямь сменился (`data-glyph` помнит прошлый):
+     * иначе кадр появления перезапускался бы при каждом переходе и все знаки мигали бы
+     */
+    #glyph(marker = undefined, item = Object(), index = Number(), state = String()) {
+        const key = this.#glyphKey(item, state);
+        if (marker.dataset.glyph === key) return;
+        marker.dataset.glyph = key;
+        marker.innerHTML = "";
+        if (state === Stepper.STATUS.PENDING) {
+            marker.classList.add("stepper_marker_spinner");
+            const spinner = new Spinner(this.#spinnerSize(), "0", "").set();
+            // Маркер назван сам («… — ожидает выполнения»): здесь спиннер — картинка,
+            // а не отдельный живой регион, иначе загрузка объявлялась бы на каждом переходе
+            spinner.setAttribute("aria-hidden", "true");
+            marker.appendChild(spinner);
+            return;
+        }
+        marker.classList.remove("stepper_marker_spinner");
+        const glyph = this.#glyphName(item, state);
+        if (glyph === undefined) {
+            marker.innerText = String(index + 1);
+            return;
+        }
+        const icon = new Icon(glyph, this.#iconSize()).set();
+        icon.setAttribute("aria-hidden", "true");
+        marker.appendChild(icon);
+        // Знак состояния приходит кадром: смена номера на галочку иначе читается вспышкой
+        new Animation(icon).scaleIn();
+    }
+
+    #glyphKey(item = Object(), state = String()) {
+        if (state === Stepper.STATUS.DONE) return "done";
+        if (state === Stepper.STATUS.ERROR) return "error";
+        if (state === Stepper.STATUS.PENDING) return "pending";
+        return item.icon === undefined ? "number" : `icon:${item.icon}`;
+    }
+
+    #glyphName(item = Object(), state = String()) {
+        if (state === Stepper.STATUS.DONE) return Icons.NAVIGATION.CHECK;
+        if (state === Stepper.STATUS.ERROR) return Icons.NAVIGATION.CLOSE;
+        return item.icon;
+    }
+
     #text(item = Object()) {
         const text = document.createElement("stepper_text");
         text.className = "stepper_text";
@@ -295,15 +451,30 @@ class Stepper {
         return this.#root.dataset.size === Stepper.SIZE.SMALL ? Stepper.SMALL_ICON_SIZE : Stepper.ICON_SIZE;
     }
 
+    // Спиннер шага — по размеру знака: размеры те же, что у значков маркера
+    #spinnerSize() {
+        return this.#root.dataset.size === Stepper.SIZE.SMALL ? { SIZE: 14, BORDER: 2 } : { SIZE: 18, BORDER: 2 };
+    }
+
     #announce() {
         const title = this.#items[this.#active] === undefined ? undefined : this.#items[this.#active].title;
         const head = I18n.t("navigation.stepOf", { index: this.#active + 1, total: this.#items.length });
         this.#status.innerText = title === undefined ? head : `${head}: ${title}`;
     }
 
+    // О смене состояния сообщается тем же именем, что у маркера: шаг, название и состояние
+    #announceStatus(index = Number()) {
+        this.#status.innerText = this.#markerLabel(index);
+    }
+
     #notify() {
         for (const listener of [...this.#listeners]) listener(this.#active, this);
-        if (this.#on_change !== undefined) this.#on_change(this.#active, this);
+        if (this.#onChange !== undefined) this.#onChange(this.#active, this);
+    }
+
+    #notifyStatus(index = Number(), status = String()) {
+        for (const listener of [...this.#statusListeners]) listener(index, status, this);
+        if (this.#onStatus !== undefined) this.#onStatus(index, status, this);
     }
 
     static #clamp(value = Number(), count = Number()) {

package/framework/components/chui_stepper/styles.css

@@ -2,7 +2,7 @@
 chui_stepper {
     display: block;
     width: -webkit-fill-available;
-    margin: var(--margin);
+    margin: var(--block_margin);
     color: var(--text_color);
     font-size: var(--font_default_size);
 }
@@ -33,7 +33,12 @@ chui_stepper[data-size="small"] {
     min-width: 0;
 }
 
+/* Полулиния соединителя: приглушённая дорожка и слой заливки поверх неё. Заливка растёт
+   переходом по токену движения — путь шагов читается пройденным, а не загорается сразу.
+   Полулинии у краёв списка не рисуются, но место остаётся, иначе крайние маркеры уехали бы
+   к краям карточки */
 .stepper_line {
+    position: relative;
     height: 2px;
     min-width: 12px;
     align-self: center;
@@ -42,6 +47,18 @@ chui_stepper[data-size="small"] {
     border-radius: var(--radius_pill);
 }
 
+/* Заливка идёт от того края, где стоит маркер-предшественник: так видно, что шаг пройден */
+.stepper_line::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: var(--green_prime_background);
+    border-radius: inherit;
+    transform: scaleX(0);
+    transform-origin: left center;
+    transition: transform var(--motion_base) var(--motion_ease);
+}
+
 .stepper_line_before {
     grid-column: 1;
     grid-row: 1;
@@ -52,6 +69,10 @@ chui_stepper[data-size="small"] {
     grid-row: 1;
 }
 
+.stepper_line_done::after {
+    transform: scaleX(1);
+}
+
 /* Края списка никуда не ведут: полулинии у них не рисуются, но место остаётся,
    иначе крайние маркеры уехали бы к краям карточки */
 .stepper_item:first-child .stepper_line_before,
@@ -59,10 +80,6 @@ chui_stepper[data-size="small"] {
     visibility: hidden;
 }
 
-.stepper_line_done {
-    background: var(--blue_prime_background);
-}
-
 .stepper_marker {
     grid-column: 2;
     grid-row: 1;
@@ -81,6 +98,11 @@ chui_stepper[data-size="small"] {
     font-size: var(--font_default_size);
     font-weight: 500;
     line-height: 1;
+    /* Цвета маркера ведёт переход: смена шага и состояния читается движением, а не вспышкой */
+    transition:
+        background-color var(--motion_base) var(--motion_ease),
+        border-color var(--motion_base) var(--motion_ease),
+        color var(--motion_base) var(--motion_ease);
 }
 
 .stepper_marker chui_icon {
@@ -93,10 +115,34 @@ chui_stepper[data-size="small"] .stepper_marker {
     font-size: var(--font_labels_size);
 }
 
-/* Пройденный шаг: тонировка акцента — видно, что галочка «своя», а не текущая */
+/* Пройденный шаг: зелёная подсветка и галочка — готовность, а не текущее место */
 .stepper_item_done .stepper_marker {
-    border-color: var(--blue_prime_background);
-    background: var(--blue_prime_background_tint);
+    border-color: var(--green_prime_background);
+    background: color-mix(in srgb, var(--green_prime_background) 16%, transparent);
+    color: var(--green_prime_background);
+}
+
+/* Ошибка: красная подсветка и крест — тот же цвет у знака и у строки шага */
+.stepper_item_error .stepper_marker {
+    border-color: var(--red_prime_background);
+    background: color-mix(in srgb, var(--red_prime_background) 16%, transparent);
+    color: var(--red_prime_background);
+}
+
+/* Шаг выполняется — в маркере спиннер: кольцо берёт цвет маркера (`currentColor`) */
+.stepper_item_pending .stepper_marker {
+    border-color: var(--border_color);
+    background: var(--element_background_2);
+    color: var(--blue_prime_background);
+}
+
+.stepper_marker spinner {
+    margin: 0;
+}
+
+/* Ошибка видна и строкой шага: цвет знака и подписи — один на всю строку */
+.stepper_item_error .stepper_title {
+    color: var(--red_prime_background);
 }
 
 /* Текущий шаг — единственный залитый акцентом: он и есть место, где мы находимся */
@@ -106,6 +152,12 @@ chui_stepper[data-size="small"] .stepper_marker {
     color: var(--text_color_hover);
 }
 
+/* Шаг, на котором мы стоим, виден и тогда, когда маркер занят своим состоянием
+   (ошибкой или спиннером): его выдаёт акцентное кольцо вокруг маркера */
+.stepper_item[data-active="true"]:not(.stepper_item_current) .stepper_marker {
+    box-shadow: 0 0 0 2px var(--blue_prime_background_tint);
+}
+
 .stepper_item_todo .stepper_marker {
     color: var(--text_color_disabled);
 }
@@ -124,7 +176,7 @@ chui_stepper[data-size="small"] .stepper_marker {
     outline-offset: var(--focus_outline_offset);
 }
 
-.stepper_marker:disabled {
+.stepper_marker[aria-disabled="true"] {
     cursor: not-allowed;
     color: var(--text_color_disabled);
     background: var(--element_background_disabled);
@@ -143,11 +195,8 @@ chui_stepper[data-size="small"] .stepper_marker {
     font-weight: 500;
     overflow: hidden;
     text-overflow: ellipsis;
-}
-
-.stepper_item_todo .stepper_title {
-    color: var(--text_color_disabled);
-    font-weight: 400;
+    /* Цвет подписи и пояснения тоже ведёт переход: ошибка и выбор шага не мигают */
+    transition: color var(--motion_base) var(--motion_ease);
 }
 
 .stepper_description {
@@ -155,6 +204,12 @@ chui_stepper[data-size="small"] .stepper_marker {
     margin-top: 2px;
     color: var(--text_color_disabled);
     font-size: var(--font_labels_size);
+    transition: color var(--motion_base) var(--motion_ease);
+}
+
+.stepper_item_todo .stepper_title {
+    color: var(--text_color_disabled);
+    font-weight: 400;
 }
 
 .stepper_description[hidden] {
@@ -167,6 +222,16 @@ chui_stepper[data-orientation="vertical"] .stepper_list {
     grid-auto-columns: auto;
 }
 
+/* Заливка в столбце растёт сверху вниз — от маркера-предшественника к следующему */
+chui_stepper[data-orientation="vertical"] .stepper_line::after {
+    transform: scaleY(0);
+    transform-origin: center top;
+}
+
+chui_stepper[data-orientation="vertical"] .stepper_line_done::after {
+    transform: scaleY(1);
+}
+
 chui_stepper[data-orientation="vertical"] .stepper_item {
     grid-template-columns: auto 1fr;
     grid-template-rows: 1fr auto 1fr;