chuijs 4.0.2 → 4.0.4

package/framework/components/chui_backtop/backtop.js

@@ -1,6 +1,6 @@
-const {setStyles, optionOr, scrollParent} = require('../../modules/chui_functions');
-const {Icon, Icons} = require('../chui_icons/icons');
-const {I18n} = require('../../modules/chui_i18n/chui_i18n');
+const { setStyles, optionOr, scrollParent } = require("../../modules/chui_functions");
+const { Icon, Icons } = require("../chui_icons/icons");
+const { I18n } = require("../../modules/chui_i18n/chui_i18n");
 
 /**
  * Кнопка «наверх»: появляется, когда контейнер прокручен дальше порога, и возвращает его к началу.
@@ -32,7 +32,7 @@ const {I18n} = require('../../modules/chui_i18n/chui_i18n');
 class Backtop {
     static POSITION = {
         FIXED: "fixed",
-        STICKY: "sticky"
+        STICKY: "sticky",
     };
     static #counter = 0;
     static #DEFAULT_THRESHOLD = 200;
@@ -50,11 +50,19 @@ class Backtop {
     #visible = false;
     #destroyed = false;
 
-    constructor(options = {
-        id: String(), target: undefined, threshold: Number(),
-        position: String(), bottom: String(), inlineEnd: String(),
-        title: String(), icon: undefined, smooth: Boolean()
-    }) {
+    constructor(
+        options = {
+            id: String(),
+            target: undefined,
+            threshold: Number(),
+            position: String(),
+            bottom: String(),
+            inlineEnd: String(),
+            title: String(),
+            icon: undefined,
+            smooth: Boolean(),
+        }
+    ) {
         setStyles(__dirname + "/styles.css", "chUiJS_Backtop");
         Backtop.#counter += 1;
         this.#id = optionOr(options.id, `chui_backtop_${Backtop.#counter}`);
@@ -74,7 +82,7 @@ class Backtop {
         this.setTitle(options.title);
         this.setIcon(options.icon);
         this.setSmooth(options.smooth !== false);
-        window.addEventListener("scroll", this.#onScroll, {capture: true, passive: true});
+        window.addEventListener("scroll", this.#onScroll, { capture: true, passive: true });
     }
 
     // GET
@@ -150,9 +158,14 @@ class Backtop {
 
     /** Свой значок (имя из `Icons`, `Icon`, узел или компонент); `undefined` — стрелка вверх */
     setIcon(icon = undefined) {
-        const node = icon === undefined || icon === null || icon === ""
-            ? new Icon(Icons.NAVIGATION.ARROW_UPWARD, "18px").set()
-            : (typeof icon === "string" ? new Icon(icon, "18px").set() : (typeof icon.set === "function" ? icon.set() : icon));
+        const node =
+            icon === undefined || icon === null || icon === ""
+                ? new Icon(Icons.NAVIGATION.ARROW_UPWARD, "18px").set()
+                : typeof icon === "string"
+                  ? new Icon(icon, "18px").set()
+                  : typeof icon.set === "function"
+                    ? icon.set()
+                    : icon;
         this.#icon.innerHTML = "";
         this.#icon.appendChild(node);
         return this;
@@ -175,8 +188,8 @@ class Backtop {
         const container = this.#resolveTarget();
         if (container === undefined) return this;
         const behavior = this.#smooth && Backtop.#reducedMotion() === false ? "smooth" : "auto";
-        if (container === document.scrollingElement) window.scrollTo({top: 0, behavior: behavior});
-        else container.scrollTo({top: 0, behavior: behavior});
+        if (container === document.scrollingElement) window.scrollTo({ top: 0, behavior: behavior });
+        else container.scrollTo({ top: 0, behavior: behavior });
         return this;
     }
 
@@ -184,7 +197,8 @@ class Backtop {
     destroy() {
         if (this.#destroyed) return this;
         this.#destroyed = true;
-        window.removeEventListener("scroll", this.#onScroll, {capture: true});
+        window.removeEventListener("scroll", this.#onScroll, { capture: true });
+        this.#root.removeEventListener("transitionend", this.#onHideEnd);
         this.#root.remove();
         return this;
     }
@@ -196,8 +210,11 @@ class Backtop {
 
     // === ВНУТРЕННЕЕ ===
     static #reducedMotion() {
-        return typeof window !== "undefined" && typeof window.matchMedia === "function" &&
-            window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+        return (
+            typeof window !== "undefined" &&
+            typeof window.matchMedia === "function" &&
+            window.matchMedia("(prefers-reduced-motion: reduce)").matches
+        );
     }
 
     /** Контейнер прокрутки: свой `target`, иначе ближайший прокручиваемый предок кнопки */
@@ -222,9 +239,31 @@ class Backtop {
         const visible = top > this.#threshold;
         if (visible === this.#visible) return;
         this.#visible = visible;
-        this.#root.hidden = visible === false;
-        this.#root.classList.toggle("backtop_visible", visible);
+        this.#show(visible);
+    }
+
+    /**
+     * Показ и уход идут движением (переход в styles.css). Узел встаёт в раскладку до класса —
+     * иначе перехода не было бы вовсе, — а `hidden` возвращается по концу ухода: в закреплённом
+     * положении он держит место в раскладке панели, и снять его до ухода значило бы оборвать его.
+     */
+    #show(visible) {
+        if (visible) {
+            this.#root.hidden = false;
+            requestAnimationFrame(() => {
+                if (this.#visible === true) this.#root.classList.add("backtop_visible");
+            });
+            return;
+        }
+        this.#root.classList.remove("backtop_visible");
+        this.#root.addEventListener("transitionend", this.#onHideEnd);
     }
+
+    #onHideEnd = (event) => {
+        if (event.target !== this.#root || event.propertyName !== "opacity") return;
+        this.#root.removeEventListener("transitionend", this.#onHideEnd);
+        if (this.#visible === false) this.#root.hidden = true;
+    };
 }
 
-exports.Backtop = Backtop
+exports.Backtop = Backtop;

package/framework/components/chui_backtop/styles.css

@@ -6,6 +6,27 @@ chui_backtop {
     --backtop_inline_end: 24px;
     width: max-content;
     height: max-content;
+    opacity: 1;
+    transform: none;
+    /* Появление и уход — движение, а не снятие узла: кнопка поднимается на месте и гаснет.
+       `hidden` включает JS по концу ухода: в закреплённом положении он держит место
+       в раскладке панели, поэтому снимать его заранее нельзя */
+    transition:
+        opacity var(--motion_base) var(--motion_ease),
+        transform var(--motion_base) var(--motion_ease),
+        visibility var(--motion_none) linear;
+}
+
+/* Скрытая кнопка не ловит курсор и не попадает в обход Tab: `visibility` переключается
+   сразу при показе и только в конце ухода */
+chui_backtop:not(.backtop_visible) {
+    opacity: 0;
+    transform: translateY(8px);
+    visibility: hidden;
+    transition:
+        opacity var(--motion_fast) var(--motion_ease),
+        transform var(--motion_fast) var(--motion_ease),
+        visibility var(--motion_none) linear var(--motion_fast);
 }
 
 chui_backtop[hidden] {

package/framework/components/chui_badge/badge.js

@@ -1,61 +1,63 @@
-const {setStyles, markdownToHtml, htmlToMarkdown, optionOr} = require("../../modules/chui_functions");
+const { setStyles, markdownToHtml, htmlToMarkdown, optionOr } = require("../../modules/chui_functions");
 
 class Badge {
-    #chui_badge = document.createElement(`chui_badge`);
-    constructor(options = {
-        id: String(),
-        text: String(),
-        markdownText: String(),
-        style: undefined
-    }) {
-        setStyles(__dirname + "/styles.css", 'chUiJS_Badge');
-        if (options.id !== undefined) this.#chui_badge.id = options.id;
+    #chuiBadge = document.createElement(`chui_badge`);
+    constructor(
+        options = {
+            id: String(),
+            text: String(),
+            markdownText: String(),
+            style: undefined,
+        }
+    ) {
+        setStyles(__dirname + "/styles.css", "chUiJS_Badge");
+        if (options.id !== undefined) this.#chuiBadge.id = options.id;
         const style = optionOr(options.style, undefined);
-        if (style !== undefined) this.#chui_badge.classList.add(style);
+        if (style !== undefined) this.#chuiBadge.classList.add(style);
         // Стили текста баджей: пустая заготовка опции равносильна отсутствующей
         const text = optionOr(options.text, undefined);
-        const markdown_text = optionOr(options.markdownText, undefined);
-        if (text !== undefined && markdown_text !== undefined) {
+        const markdownText = optionOr(options.markdownText, undefined);
+        if (text !== undefined && markdownText !== undefined) {
             throw new Error("Должна быть установлена одна опция text или markdownText");
         } else {
-            if (text !== undefined) this.#chui_badge.innerText = text;
-            if (markdown_text !== undefined) this.#chui_badge.innerHTML = markdownToHtml(markdown_text);
+            if (text !== undefined) this.#chuiBadge.innerText = text;
+            if (markdownText !== undefined) this.#chuiBadge.innerHTML = markdownToHtml(markdownText);
         }
     }
     // GET
     getId() {
-        return this.#chui_badge.id;
+        return this.#chuiBadge.id;
     }
     getText() {
-        return this.#chui_badge.innerText;
+        return this.#chuiBadge.innerText;
     }
     getMarkdownText() {
-        return htmlToMarkdown(this.#chui_badge.innerHTML);
+        return htmlToMarkdown(this.#chuiBadge.innerHTML);
     }
     // SET
     setText(text = String()) {
-        this.#chui_badge.innerText = text;
+        this.#chuiBadge.innerText = text;
     }
     setMarkdownText(text = String()) {
-        this.#chui_badge.innerHTML = markdownToHtml(text);
+        this.#chuiBadge.innerHTML = markdownToHtml(text);
     }
     setId(id = String()) {
-        this.#chui_badge.id = id;
+        this.#chuiBadge.id = id;
     }
     setStyle(style = String()) {
         // Пустая строка — «не задана»: `classList.add("")` бросает исключение
         const known = optionOr(style, undefined);
-        if (known !== undefined) this.#chui_badge.classList.add(known);
+        if (known !== undefined) this.#chuiBadge.classList.add(known);
     }
     // RENDER
     set() {
-        return this.#chui_badge;
+        return this.#chuiBadge;
     }
     static STYLE = {
-        ERROR: 'badge_error',
-        SUCCESS: 'badge_success',
-        WARNING: 'badge_warning'
-    }
+        ERROR: "badge_error",
+        SUCCESS: "badge_success",
+        WARNING: "badge_warning",
+    };
 }
 
-exports.Badge = Badge
+exports.Badge = Badge;

package/framework/components/chui_badge/styles.css

@@ -12,9 +12,9 @@ chui_badge {
     height: max-content;
     width: max-content;
     padding: 2px 8px;
-    margin: var(--margin);
+    margin: var(--block_margin);
     border-radius: var(--radius_pill);
-    background: var(--badge_cancel_back);
+    background: var(--badge_cancel_background);
     color: var(--badge_cancel_text);
     font-size: var(--font_labels_size);
     font-weight: 500;
@@ -41,20 +41,20 @@ chui_badge strong {
 
 /* Код в метке — тем же моношрифтом, что в остальных местах с разметкой */
 chui_badge code {
-    font-family: var(--code_font, monospace);
+    font-family: var(--font_mono);
 }
 
 .badge_error {
-    background: var(--badge_error_back);
+    background: var(--badge_error_background);
     color: var(--badge_error_text);
 }
 
 .badge_success {
-    background: var(--badge_success_back);
+    background: var(--badge_success_background);
     color: var(--badge_success_text);
 }
 
 .badge_warning {
-    background: var(--badge_warning_back);
+    background: var(--badge_warning_background);
     color: var(--badge_warning_text);
 }

package/framework/components/chui_banner/banner.js

@@ -0,0 +1,222 @@
+const { setStyles, optionOr, markdownToHtml } = require("../../modules/chui_functions");
+const { Icon } = require("../chui_icons/icons");
+const { I18n } = require("../../modules/chui_i18n/chui_i18n");
+const { makeKeyboardButton } = require("../../modules/chui_a11y/chui_a11y");
+const { tokenTime } = require("../../modules/chui_animations/motion");
+
+/**
+ * Баннер — карточка-объявление: картинка или значок, заголовок с подзаголовком, действия
+ * и закрытие.
+ *
+ * Баннер стоит в потоке страницы, а не всплывает слоем: для модального сообщения есть
+ * `Popup`, для сообщения о состоянии — `Alert`, для всплывающего — `Toast`. От `Alert` он
+ * отличается задачей: там состояние (ошибка, предупреждение), здесь предложение — «попробуйте
+ * новое», «настройте», «посмотрите» — поэтому у баннера крупный материал, картинка и действия
+ * кнопками.
+ *
+ * Два вида (`mode`) и два размера (`size`):
+ *   - `tint` — значок в цветной плашке, `image` — фотография; фото занимает кромку карточки
+ *     целиком и не затемняется: текст лежит рядом, а не поверх снимка, поэтому подпись читается
+ *     при любом кадре (всплывающие подписи поверх фото требуют затемнения на глаз — в тёмной
+ *     и светлой схеме оно даёт разный результат);
+ *   - `s` — строка: плашка слева, заголовок и подзаголовок рядом, действия справа;
+ *   - `m` — карточка: картинка сверху во всю ширину, под ней заголовок, подзаголовок, текст
+ *     и действия.
+ *
+ * Опции: `id`, `title`, `subtitle`, `text`, `markdownText`, `icon`, `image`, `mode`, `size`,
+ * `actions`, `closable`, `onClose`, `onClick`.
+ *
+ * Методы: `setTitle(text)`, `setSubtitle(text)`, `setText(text)`, `setMarkdownText(md)`,
+ * `setIcon(glyph)`, `setImage(src)`, `setMode(mode)`, `setSize(size)`, `addActions(...actions)`,
+ * `setClosable(bool)`, `close()`, `isClosed()`, `set()`, `destroy()`.
+ */
+class Banner {
+    static MODE = { TINT: "tint", IMAGE: "image" };
+    static SIZE = { S: "s", M: "m" };
+
+    #root = document.createElement("chui_banner");
+    #media = document.createElement("banner_media");
+    #content = document.createElement("banner_content");
+    #title = undefined;
+    #subtitle = undefined;
+    #text = undefined;
+    #actions = document.createElement("banner_actions");
+    #close = undefined;
+    #image = undefined;
+    #onClose = undefined;
+    #onClick = undefined;
+    #closed = false;
+    #removed = false;
+
+    constructor(options = {}) {
+        setStyles(__dirname + "/styles.css", "chUiJS_Banner");
+        if (options.id !== undefined) this.#root.id = options.id;
+        this.setSize(optionOr(options.size, Banner.SIZE.M));
+        this.setMode(optionOr(options.mode, Banner.MODE.TINT));
+        this.#onClose = typeof options.onClose === "function" ? options.onClose : undefined;
+        this.#onClick = typeof options.onClick === "function" ? options.onClick : undefined;
+        this.#root.append(this.#media, this.#content, this.#actions);
+        if (options.title !== undefined) this.setTitle(options.title);
+        if (options.subtitle !== undefined) this.setSubtitle(options.subtitle);
+        if (options.markdownText !== undefined) this.setMarkdownText(options.markdownText);
+        else if (options.text !== undefined) this.setText(options.text);
+        if (options.icon !== undefined) this.setIcon(options.icon);
+        if (options.image !== undefined) this.setImage(options.image);
+        if (Array.isArray(options.actions)) this.addActions(...options.actions);
+        if (options.closable === true) this.setClosable(true);
+        if (this.#onClick !== undefined) this.#makeClickable();
+        this.#syncName();
+    }
+
+    // GET
+    isClosed() {
+        return this.#closed;
+    }
+
+    // SET
+    setTitle(text = String()) {
+        this.#title = this.#writeText(this.#title, "banner_title", text, "title");
+        this.#syncName();
+        return this;
+    }
+    setSubtitle(text = String()) {
+        this.#subtitle = this.#writeText(this.#subtitle, "banner_subtitle", text, "subtitle");
+        return this;
+    }
+    setText(text = String()) {
+        this.#text = this.#writeText(this.#text, "banner_text", text, "text");
+        return this;
+    }
+    /** Разметка в теле баннера: тот же приём, что у `Alert` — текст приходит готовым HTML */
+    setMarkdownText(markdown = String()) {
+        if (this.#text === undefined) this.#text = this.#insertText("banner_text", "text");
+        this.#text.innerHTML = markdownToHtml(String(markdown));
+        return this;
+    }
+    /** Значок в плашке: состояние `tint`. Прежняя картинка при этом уходит */
+    setIcon(glyph = String()) {
+        const icon = new Icon(String(glyph), "22px").set();
+        this.#media.replaceChildren(icon);
+        this.#root.dataset.mode = Banner.MODE.TINT;
+        this.#image = undefined;
+        return this;
+    }
+    /** Фотография на кромке карточки: состояние `image` */
+    setImage(src = String()) {
+        if (this.#image === undefined) {
+            this.#image = document.createElement("img");
+            // Картинка здесь украшение: смысл несёт заголовок, поэтому подпись пуста
+            this.#image.alt = "";
+            this.#image.loading = "lazy";
+        }
+        this.#image.src = String(src);
+        this.#media.replaceChildren(this.#image);
+        this.#root.dataset.mode = Banner.MODE.IMAGE;
+        return this;
+    }
+    setMode(mode = String()) {
+        this.#root.dataset.mode = mode === Banner.MODE.IMAGE ? Banner.MODE.IMAGE : Banner.MODE.TINT;
+        return this;
+    }
+    setSize(size = String()) {
+        this.#root.dataset.size = size === Banner.SIZE.S ? Banner.SIZE.S : Banner.SIZE.M;
+        return this;
+    }
+    /** Действия баннера: компоненты фреймворка (у них есть `set()`) или готовые узлы */
+    addActions(...actions) {
+        for (const action of actions) {
+            if (action === undefined || action === null) continue;
+            this.#actions.appendChild(typeof action.set === "function" ? action.set() : action);
+        }
+        return this;
+    }
+    /**
+     * Кнопка закрытия — настоящий `<button>`: у неё есть мышь, клавиатура и имя
+     * для скринридера (подписи в баннере нет, имя даёт словарь).
+     */
+    setClosable(boolean = Boolean()) {
+        if (boolean !== true) {
+            if (this.#close !== undefined) this.#close.remove();
+            this.#close = undefined;
+            return this;
+        }
+        if (this.#close === undefined) {
+            this.#close = document.createElement("button");
+            this.#close.type = "button";
+            this.#close.className = "banner_close";
+            this.#close.innerHTML = new Icon("close", "16px").getHTML();
+            this.#close.setAttribute("aria-label", I18n.t("a11y.closeMessage"));
+            this.#close.setAttribute("title", I18n.t("common.close"));
+            this.#close.addEventListener("click", () => this.close());
+            this.#root.appendChild(this.#close);
+        }
+        return this;
+    }
+
+    /**
+     * Закрытие: баннер гаснет и сходит общим кадром ухода, а узел убирается по его концу.
+     * Слушатель одноразовый (проверка цели): иначе он поймал бы любой конец кадра на узле.
+     * Срок из токена страхует случай, когда кадр не проиграется вовсе — у скрытого узла
+     * `animationend` не приходит.
+     */
+    close() {
+        if (this.#closed === true) return this;
+        this.#closed = true;
+        if (this.#onClose !== undefined) this.#onClose(this);
+        const finish = () => {
+            if (this.#removed === true) return;
+            this.#removed = true;
+            this.#root.removeEventListener("animationend", finish);
+            this.#root.remove();
+        };
+        this.#root.addEventListener("animationend", finish);
+        this.#root.classList.add("banner_leaving");
+        setTimeout(finish, tokenTime("--motion_fast"));
+        return this;
+    }
+
+    set() {
+        return this.#root;
+    }
+    /** Узлы баннера уходят из документа вместе со своими слушателями; работа снимается явно */
+    destroy() {
+        this.#onClick = undefined;
+        this.#onClose = undefined;
+        this.#removed = true;
+        this.#root.remove();
+    }
+
+    // === ВНУТРЕННЕЕ ===
+    #writeText(node = undefined, className = String(), text = String(), key = String()) {
+        const target = node === undefined ? this.#insertText(className, key) : node;
+        target.innerText = String(text);
+        return target;
+    }
+    #insertText(className = String(), key = String()) {
+        const node = document.createElement(`banner_${key}`);
+        node.className = className;
+        this.#content.appendChild(node);
+        return node;
+    }
+    /** Клик по всей карточке: роль кнопки, обход клавиатурой и активация Enter/Space */
+    #makeClickable() {
+        makeKeyboardButton(this.#root);
+        this.#root.addEventListener("click", () => {
+            if (this.#onClick !== undefined) this.#onClick(this);
+        });
+    }
+    /**
+     * Имя баннера для скринридера: заголовок, а без него — общая подпись из словаря.
+     * У кликабельного баннера имя обязательно: без него роль кнопки читается как «кнопка».
+     */
+    #syncName() {
+        const title = this.#title === undefined ? "" : this.#title.innerText.trim();
+        const name = title === "" ? I18n.t("feedback.banner") : title;
+        if (this.#onClick === undefined && this.#root.getAttribute("role") === null) {
+            this.#root.setAttribute("role", "region");
+        }
+        this.#root.setAttribute("aria-label", name);
+    }
+}
+
+exports.Banner = Banner;