chuijs 4.0.0 → 4.0.1

package/framework/components/chui_spinner/styles.css

@@ -2,10 +2,12 @@ chui_spiner {
     width: max-content;
     height: max-content;
     display: flex;
+    /* Цвет дуги: по умолчанию акцент, меняется через `style.color` на самом индикаторе */
+    color: var(--blue_prime_background);
     /* Вращается коробка, и её повёрнутый AABB больше стороны квадрата (90 → до 127 px):
        без обрезки этот «инк» уходил в прокрутку предков и раздувал scrollWidth карточки.
-       Краска кольца остаётся внутри окружности, вписанной в коробку, поэтому обрезка
-       ничего не теряет; 1px запаса сохраняет сглаженные касательные точки окружности. */
+       Кольцо остаётся внутри вписанной окружности, поэтому обрезка ничего не теряет;
+       1px запаса сохраняет сглаженную внешнюю кромку кольца. */
     overflow: clip;
     overflow-clip-margin: 1px;
 }
@@ -13,38 +15,35 @@ chui_spiner {
 spinner {
     /* Толщину кольца задаёт компонент (в JS — по размеру индикатора) */
     --spinner_border: 3px;
-    position: relative;
-    /* Кольцо — окружность: без border-box верхняя граница прибавлялась к высоте
-       (например 60x64) и скругление 50% рисовало овал */
-    box-sizing: border-box;
-    border-radius: 50%;
-    animation: spinner 2s linear infinite;
-    display: flex;
-    justify-content: center;
-    align-items: center;
+    display: block;
+    animation: spinner_rotate 1s linear infinite;
+}
+
+spinner svg {
+    display: block;
+    width: 100%;
+    height: 100%;
 }
 
-/* Дуга — конический градиент, обрезанный маской до полосы кольца: у рамки одного
-   сегмента (`border-top`) концы дуги сходятся клином, и на кольце 3–5px они читались
-   рваными. Маска стоит на псевдоэлементе: на самом `spinner` она срезала бы
-   вложенные кольца индикатора. */
-spinner::before {
-    content: "";
-    position: absolute;
-    inset: 0;
-    border-radius: 50%;
-    background: conic-gradient(var(--blue_prime_background) 0deg 90deg, transparent 90deg 360deg);
-    -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - var(--spinner_border)), #000 calc(100% - var(--spinner_border)));
-    mask: radial-gradient(farthest-side, transparent calc(100% - var(--spinner_border)), #000 calc(100% - var(--spinner_border)));
+/* Дорожка — целое приглушённое кольцо под дугой: дуга читается и на светлом, и на тёмном
+   фоне, а в покое кольцо остаётся кругом, без «обрубка» */
+spinner .spinner_track {
+    fill: none;
+    stroke: var(--text_color);
+    stroke-opacity: 0.12;
+    stroke-width: var(--spinner_border);
 }
 
-/* Крутится только внешнее кольцо: у вложенных поворот складывался с родительским
-   (1×/2×/3×), и дуги расходились по кругу — три рваных штриха вместо индикатора */
-spinner spinner {
-    animation: none;
+/* Дуга — часть кольца со скруглёнными концами: длину полосы задаёт компонент
+   (`stroke-dasharray`), толщину — переменная, цвет — `currentColor` */
+spinner .spinner_arc {
+    fill: none;
+    stroke: currentColor;
+    stroke-width: var(--spinner_border);
+    stroke-linecap: round;
 }
 
-@keyframes spinner {
+@keyframes spinner_rotate {
     from {
         transform: rotate(0deg);
     }
@@ -53,3 +52,10 @@ spinner spinner {
     }
 }
 
+/* Кому вращение мешает — оно остаётся, но медленнее: индикатор не «замирает» */
+@media (prefers-reduced-motion: reduce) {
+    spinner {
+        animation-duration: 2.5s;
+    }
+}
+

package/framework/components/chui_sticky_bar/sticky_bar.js

@@ -0,0 +1,230 @@
+const {setStyles, optionOr, scrollParent} = require('../../modules/chui_functions');
+
+/**
+ * Прилипающая полоса: остаётся у верха области прокрутки, пока её содержимое не кончилось.
+ *
+ * Полоса задаётся `add()`:
+ *
+ * ```javascript
+ * const bar = new StickyBar({
+ *     onChange: (stuck) => Log.info('закреплена: ' + stuck)
+ * });
+ * bar.add(new Button({title: 'Раздел «А'}));
+ * content.appendChild(bar.set());
+ * ```
+ *
+ * Закрепление делает CSS (`position: sticky` у корня), поэтому полоса сохраняет место в потоке
+ * и не требует подпорки-заглушки. Компонент добавляет к этому состояние: пока полоса в своей
+ * позиции, у корня `data-stuck="false"`, после — `data-stuck="true"` и класс `sticky_bar_stuck`,
+ * о чём сообщает `onChange(stuck)`. Вид «в покое» и «закреплено» задаёт CSS — обычно материал и
+ * тень появляются только у закреплённой полосы, чтобы она не спорила с содержимым.
+ *
+ * **Отступ.** `offset` — на сколько ниже порога встаёт полоса. Число — пиксели, строка — любое
+ * CSS-значение (`'12px'`, `'1rem'`). Порог отсчитывается от **края содержимого** области прокрутки:
+ * её собственный `padding` браузер учитывает сам (в Chromium `sticky` стоит по content box),
+ * поэтому у страницы приложения (у `center` есть отступ под шапку) полосе хватает `offset: 0` —
+ * она встаёт ровно под шапкой. Отдельный отступ нужен, когда у контейнера прокрутки нет
+ * внутреннего отступа, а сверху что-то наложено.
+ *
+ * **Состояние считается замером, а не наблюдателем.** `IntersectionObserver` здесь не годится:
+ * липкий узел нельзя наблюдать относительно самого себя, а сторож, движущийся вместе с полосой,
+ * пересекает границу ровно в момент закрепления и даёт неустойчивый сигнал на дробных пикселях.
+ * Поэтому раз в кадр сравниваются верх полосы и верх области прокрутки; слушатель `scroll` —
+ * пассивный, работа сведена к одному замеру на кадр через `requestAnimationFrame`.
+ *
+ * Доступность: компонент ничего не объявляет и не перехватывает — содержимое остаётся обычным
+ * содержимым. `destroy()` снимает слушатели; повторный вызов безвреден.
+ */
+class StickyBar {
+    static #counter = 0;
+
+    #root = document.createElement("chui_sticky_bar");
+    #content = document.createElement("sticky_bar_content");
+    #id = undefined;
+    #offset = "0px";
+    #target = undefined;
+    #stuck = false;
+    #on_change = undefined;
+    #container = undefined;
+    #destroyed = false;
+    #frame = 0;
+    #pending = 0;
+
+    constructor(options = {
+        id: String(), offset: Number(), target: undefined, onChange: undefined
+    }) {
+        setStyles(__dirname + "/styles.css", "chUiJS_StickyBar");
+        StickyBar.#counter += 1;
+        this.#id = optionOr(options.id, `chui_sticky_bar_${StickyBar.#counter}`);
+        this.#root.id = this.#id;
+        // Начальное состояние видно в разметке: до порога полоса в своей позиции
+        this.#root.dataset.stuck = "false";
+        this.#root.appendChild(this.#content);
+        this.#target = options.target;
+        this.#on_change = options.onChange;
+        this.setOffset(options.offset === undefined ? 0 : options.offset);
+        this.#observe();
+    }
+
+    // GET
+    getId() {
+        return this.#id;
+    }
+
+    /** Отступ закрепления: как задан (число пикселей или CSS-значение) */
+    getOffset() {
+        return this.#offset;
+    }
+
+    /** Закреплена ли полоса сейчас */
+    isStuck() {
+        return this.#stuck;
+    }
+
+    /** Контейнер прокрутки: свой из `target`, иначе ближайший прокручиваемый предок */
+    getTarget() {
+        const target = this.#target;
+        if (target !== undefined && target !== null) {
+            if (typeof target === "string") return document.querySelector(target) ?? document.scrollingElement;
+            if (target instanceof Element) return target;
+            if (typeof target.set === "function") return target.set();
+        }
+        return scrollParent(this.#root);
+    }
+
+    /** Содержимое полосы (в него пишет `add()`) */
+    getContent() {
+        return this.#content;
+    }
+
+    // SET
+    setId(id = String()) {
+        this.#id = id;
+        this.#root.id = id;
+        return this;
+    }
+
+    /** Отступ закрепления: число пикселей или строка CSS (`"12px"`, `"var(--header_height)"`) */
+    setOffset(offset = Number()) {
+        this.#offset = typeof offset === "string" ? offset : `${Number(offset) || 0}px`;
+        this.#root.style.setProperty("--sticky_offset", this.#offset);
+        this.update();
+        return this;
+    }
+
+    setOnChange(listener = undefined) {
+        this.#on_change = listener;
+        return this;
+    }
+
+    /** Содержимое полосы: компоненты фреймворка или готовые узлы (содержимое заменяется) */
+    add(...components) {
+        this.#content.innerHTML = "";
+        for (const component of components) {
+            if (component === undefined || component === null) continue;
+            this.#content.appendChild(component instanceof Element ? component : component.set());
+        }
+        this.update();
+        return this;
+    }
+
+    clear() {
+        this.#content.innerHTML = "";
+        return this;
+    }
+
+    /** Пересобрать слушатели и замер — после смены содержимого, контейнера или раскладки */
+    update() {
+        this.#detach();
+        this.#observe();
+        return this;
+    }
+
+    /** Снять слушатели; повторный вызов безвреден */
+    destroy() {
+        this.#destroyed = true;
+        this.#detach();
+        return this;
+    }
+
+    // RENDER
+    set() {
+        return this.#root;
+    }
+
+    // === ВНУТРЕННЕЕ ===
+    /**
+     * Первое подключение — на следующем кадре: узел обычно вставляют в документ сразу после
+     * `set()`, и только тогда виден настоящий контейнер прокрутки. Повторные вызовы ничего не
+     * делают, пока подключение не снято.
+     */
+    #observe() {
+        if (this.#destroyed === true) return;
+        if (this.#container !== undefined || this.#pending !== 0) return;
+        this.#pending = requestAnimationFrame(() => {
+            this.#pending = 0;
+            this.#attach();
+        });
+    }
+
+    #attach() {
+        if (this.#destroyed === true) return;
+        this.#container = this.getTarget();
+        if (this.#container instanceof Element) {
+            this.#container.addEventListener("scroll", this.#onScroll, { passive: true });
+        }
+        window.addEventListener("resize", this.#onScroll);
+        this.#schedule();
+    }
+
+    #detach() {
+        if (this.#container instanceof Element) {
+            this.#container.removeEventListener("scroll", this.#onScroll);
+        }
+        window.removeEventListener("resize", this.#onScroll);
+        this.#container = undefined;
+        if (this.#pending !== 0) {
+            cancelAnimationFrame(this.#pending);
+            this.#pending = 0;
+        }
+        if (this.#frame !== 0) {
+            cancelAnimationFrame(this.#frame);
+            this.#frame = 0;
+        }
+    }
+
+    #onScroll = () => this.#schedule();
+
+    #schedule() {
+        if (this.#frame !== 0 || this.#destroyed === true) return;
+        this.#frame = requestAnimationFrame(() => {
+            this.#frame = 0;
+            this.#measure();
+        });
+    }
+
+    /**
+     * Закреплена ли полоса: её верх доехал до порога (край содержимого области прокрутки плюс
+     * отступ). Запас в 1px гасит дребезг на дробных пикселях (сглаживание при масштабе окна).
+     */
+    #measure() {
+        if (this.#destroyed === true) return;
+        const container = this.#container;
+        if (!(container instanceof Element) || this.#root.isConnected === false) return;
+        // Порог — от края содержимого контейнера: собственный отступ прокрутки браузер
+        // учитывает сам, а рамку — нет, поэтому она прибавляется отдельно
+        const container_style = window.getComputedStyle(container);
+        const padding = Number.parseFloat(container_style.paddingTop) || 0;
+        const reference_top = container.getBoundingClientRect().top + container.clientTop + padding;
+        const inset = Number.parseFloat(window.getComputedStyle(this.#root).top);
+        const offset = Number.isFinite(inset) ? inset : 0;
+        const stuck = this.#root.getBoundingClientRect().top <= reference_top + offset + 1;
+        if (stuck === this.#stuck) return;
+        this.#stuck = stuck;
+        this.#root.dataset.stuck = String(stuck);
+        this.#root.classList.toggle("sticky_bar_stuck", stuck);
+        if (typeof this.#on_change === "function") this.#on_change(stuck);
+    }
+}
+
+exports.StickyBar = StickyBar;

package/framework/components/chui_sticky_bar/styles.css

@@ -0,0 +1,37 @@
+/* Прилипающая полоса: корень сам липнет к верху области прокрутки, поэтому место в потоке
+   сохраняется и подпорка-заглушка не нужна. Отступ задаёт компонент переменной `--sticky_offset`
+   (число или CSS-значение); отсчитывается он от края содержимого области прокрутки. */
+chui_sticky_bar {
+    --sticky_offset: 0px;
+    display: block;
+    position: sticky;
+    inset-block-start: var(--sticky_offset);
+    width: -webkit-fill-available;
+    /* Ниже шапки (999) и выше содержимого страницы: полоса — слой над текстом, но под оболочкой */
+    z-index: 6;
+    box-sizing: border-box;
+}
+
+sticky_bar_content {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 6px;
+    width: -webkit-fill-available;
+    box-sizing: border-box;
+    /* Отступы есть всегда, а фон и рамка — только у закреплённой полосы: иначе при закреплении
+       содержимое прыгало бы. Прозрачная рамка держит ту же высоту, что и видимая */
+    padding: 8px 10px;
+    border: 1px solid transparent;
+    border-radius: var(--radius_md);
+    transition: background-color var(--transition_time) ease, box-shadow var(--transition_time) ease;
+}
+
+/* Закреплённая полоса читается отдельным слоем: материал как у шапки, волосяной край и тень.
+   В покое она — обычная строка содержимого, ни фона, ни тени */
+chui_sticky_bar[data-stuck="true"] sticky_bar_content {
+    border-color: var(--border_color);
+    background: var(--header_background);
+    backdrop-filter: var(--global_blur);
+    box-shadow: var(--box_shadow_main);
+}

package/framework/modules/chui_bridge/preload.js

@@ -127,6 +127,20 @@ contextBridge.exposeInMainWorld("chui", {
         shell: {
             openExternal: (url = String()) => Desktop.shell.openExternal(url)
         },
+        app: {
+            path: (name = String()) => Desktop.app.path(name),
+            info: () => Desktop.app.info()
+        },
+        dialog: {
+            open: (options = {}) => Desktop.dialog.open(options),
+            save: (options = {}) => Desktop.dialog.save(options),
+            message: (options = {}) => Desktop.dialog.message(options)
+        },
+        session: {
+            getCacheSize: () => Desktop.session.getCacheSize(),
+            clearCache: () => Desktop.session.clearCache(),
+            clearStorageData: (options = {}) => Desktop.session.clearStorageData(options)
+        },
         print: {
             page: (options = {}) => Desktop.print.page(options),
             html: (html = String(), options = {}) => Desktop.print.html(html, options),

package/framework/modules/chui_functions.js

@@ -4,11 +4,14 @@ function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/** Кэш прочитанных таблиц стилей: один файл отдаётся разным `id` без повторного чтения с диска */
+const styles_cache = new Map();
+
 function setStyles(pathToCSS = String(), component = String()) {
     if (document.getElementById(component) != null) return;
-    let data = fs.readFileSync(pathToCSS, 'utf8');
+    if (styles_cache.has(pathToCSS) === false) styles_cache.set(pathToCSS, fs.readFileSync(pathToCSS, 'utf8'));
     let style = document.createElement('style');
-    style.innerHTML = String(data);
+    style.innerHTML = styles_cache.get(pathToCSS);
     style.type = 'text/css';
     style.setAttribute('id', component);
     document.head.appendChild(style);
@@ -101,14 +104,27 @@ function shouldOpenDropdownUp(dropdown = new HTMLElement(), anchor = new HTMLEle
     return dropdownPlacement(dropdown, anchor).up;
 }
 
+/**
+ * Разбор markdown в HTML — `markdown-it`.
+ *
+ * Рендер идёт с `html: false`: сырой HTML из разметки не пропускается, а показывается текстом,
+ * поэтому `<script>` или обработчик события в `markdownText` не исполняются. Таблицы и
+ * ~~зачёркивание~~ включены по умолчанию, авто-ссылок нет — адрес становится ссылкой только
+ * явным `[текст](адрес)`. Разборщик создаётся при первом вызове: markdown нужен не каждой
+ * странице, а `require` тянет библиотеку целиком.
+ */
+let markdown_parser = undefined;
 function markdownToHtml(text = String()) {
-    let showdown = require('showdown');
-    return new showdown.Converter().makeHtml(text);
+    if (text === undefined || text === null || String(text) === "") return "";
+    if (markdown_parser === undefined) markdown_parser = new (require('markdown-it'))({html: false, linkify: false, breaks: false});
+    return markdown_parser.render(String(text)).trim();
 }
 
+/** Обратный разбор: HTML → markdown (`turndown`) */
 function htmlToMarkdown(text = String()) {
-    let showdown = require('showdown');
-    return new showdown.Converter().makeMarkdown(text);
+    if (text === undefined || text === null || String(text) === "") return "";
+    const TurndownService = require('turndown');
+    return new TurndownService().turndown(String(text));
 }
 
 function getDate() {

package/framework/modules/chui_services/chui_channels.js

@@ -40,9 +40,31 @@ const SERVICES_CHANNELS = {
     /** Событие main → рендерер: язык приложения изменился */
     LOCALE_EVENT: "chui_services_locale_event",
     /** Событие main → рендерер: сработала глобальная клавиша */
-    SHORTCUT_EVENT: "chui_shortcut"
+    SHORTCUT_EVENT: "chui_shortcut",
+    /** Путь приложения по имени из `APP_PATH_NAMES` */
+    APP_PATH: "chui_services_app_path",
+    /** Сведения о приложении: имя, версия, язык, сборка */
+    APP_INFO: "chui_services_app_info",
+    /** Системные диалоги: окно берётся у отправителя */
+    DIALOG_OPEN: "chui_services_dialog_open",
+    DIALOG_SAVE: "chui_services_dialog_save",
+    DIALOG_MESSAGE: "chui_services_dialog_message",
+    /** Сессия окна-отправителя: кеш и хранилище */
+    SESSION_CACHE_SIZE: "chui_services_session_cache_size",
+    SESSION_CLEAR_CACHE: "chui_services_session_clear_cache",
+    SESSION_CLEAR_STORAGE: "chui_services_session_clear_storage"
 };
 
+/**
+ * Имена путей `app.getPath()`, которые может запросить страница. Это белый список: всё, что
+ * вне него, main отклоняет — странице не должен быть доступен произвольный каталог системы.
+ * Имена совпадают с именами Electron, кроме `logs` (в Electron это `logs`).
+ */
+const APP_PATH_NAMES = [
+    "home", "appData", "userData", "sessionData", "temp", "exe", "module",
+    "desktop", "documents", "downloads", "music", "pictures", "videos", "logs", "recent", "crashDumps"
+];
+
 /**
  * Метод моста preload'а → канал. `Desktop` вызывает метод по имени: в безопасном режиме
  * его берут из `window.chui.services`, в обычном — сами зовут `ipcRenderer.invoke(канал)`.
@@ -74,7 +96,15 @@ const SERVICES_CALLS = {
     themeSet: SERVICES_CHANNELS.THEME_SET,
     themeToggle: SERVICES_CHANNELS.THEME_TOGGLE,
     localeGet: SERVICES_CHANNELS.LOCALE_GET,
-    localeSet: SERVICES_CHANNELS.LOCALE_SET
+    localeSet: SERVICES_CHANNELS.LOCALE_SET,
+    appPath: SERVICES_CHANNELS.APP_PATH,
+    appInfo: SERVICES_CHANNELS.APP_INFO,
+    dialogOpen: SERVICES_CHANNELS.DIALOG_OPEN,
+    dialogSave: SERVICES_CHANNELS.DIALOG_SAVE,
+    dialogMessage: SERVICES_CHANNELS.DIALOG_MESSAGE,
+    sessionCacheSize: SERVICES_CHANNELS.SESSION_CACHE_SIZE,
+    sessionClearCache: SERVICES_CHANNELS.SESSION_CLEAR_CACHE,
+    sessionClearStorage: SERVICES_CHANNELS.SESSION_CLEAR_STORAGE
 };
 
 /** Каналы моста: окно, тема и прикладные сообщения безопасного окна */
@@ -99,4 +129,5 @@ const BRIDGE_ARGS = {
 exports.SERVICES_CHANNELS = SERVICES_CHANNELS
 exports.SERVICES_CALLS = SERVICES_CALLS
 exports.BRIDGE_CHANNELS = BRIDGE_CHANNELS
+exports.APP_PATH_NAMES = APP_PATH_NAMES
 exports.BRIDGE_ARGS = BRIDGE_ARGS

package/framework/modules/chui_services/desktop.js

@@ -125,6 +125,51 @@ class Desktop {
         onChange: (listener = () => {}) => Desktop.#subscribeLocale(listener)
     };
 
+    /**
+     * Приложение со стороны страницы: пути и сведения. Прямого доступа к модулям Electron
+     * у страницы нет — это и есть рекомендация Electron вместо `remote`.
+     *
+     * ```javascript
+     * await Desktop.app.path('userData');   // каталог настроек приложения
+     * await Desktop.app.info();             // {name, version, locale, isPackaged}
+     * ```
+     */
+    static app = {
+        /** Путь по имени из белого списка (`"userData"`, `"downloads"`, …) */
+        path: (name = String()) => Desktop.#call("appPath", String(name)),
+        /** @returns {Promise<{name: string, version: string, locale: string, systemLocale: string, isPackaged: boolean}>} */
+        info: () => Desktop.#call("appInfo")
+    };
+
+    /**
+     * Системные диалоги — в том окне, которое их вызвало: родитель и модальность main
+     * берёт у отправителя. Результат открытия — `{canceled, filePaths}`, как у `dialog.*`.
+     *
+     * ```javascript
+     * const {canceled, filePaths} = await Desktop.dialog.open({properties: ["openFile"]});
+     * ```
+     */
+    static dialog = {
+        open: (options = Object()) => Desktop.#call("dialogOpen", options),
+        save: (options = Object()) => Desktop.#call("dialogSave", options),
+        message: (options = Object()) => Desktop.#call("dialogMessage", options)
+    };
+
+    /**
+     * Сессия окна-отправителя: кеш и хранилище. Именно своя сессия, а не чужого окна.
+     *
+     * ```javascript
+     * await Desktop.session.clearCache();
+     * await Desktop.session.clearStorageData({storages: ["cookies"]});
+     * ```
+     */
+    static session = {
+        /** @returns {Promise<number>} размер кеша в байтах */
+        getCacheSize: () => Desktop.#call("sessionCacheSize"),
+        clearCache: () => Desktop.#call("sessionClearCache"),
+        clearStorageData: (options = Object()) => Desktop.#call("sessionClearStorage", options)
+    };
+
     // accelerator → набор обработчиков этого окна
     static #shortcut_handlers = new Map();
     static #shortcut_event_bound = false;