@elcrm/notice

v0.1.8

Published

4 days ago

React-уведомления для elCRM: тосты, Undo с таймером, кнопки действий, темы и CSS-переменные.

0High
0Medium
0Low

maskal

elcrm notice toast react notification undo

`@elcrm/notice`

React-библиотека уведомлений для elCRM: типы error / success / remark / copy, режим Undo с таймером, до двух кнопок действий, глобальные настройки через <Notice.Init />, темы и CSS-переменные.

Содержание

Установка

npm install @elcrm/notice
# или
bun add @elcrm/notice

Peer-зависимости: react ≥ 18, react-dom ≥ 18.

Быстрый старт

1. Импортируйте библиотеку и стили

import { Notice } from "@elcrm/notice";
import "@elcrm/notice/style.css";

2. Один раз подключите инициализацию в корне приложения

function App() {
    return (
        <>
            {/* контент */}
            <Notice.Init durationMs={1800} maxVisible={5} />
        </>
    );
}

3. Вызывайте методы из любого места

const id = Notice.Success("Готово");
// позже: Notice.Close(id);

Все методы показа возвращают NoticeId (число) — его можно передать в Notice.Close(id).

Импорт стилей и тем

CSS Modules с короткими уникальными классами (prefix u): всегда 3 символа — u + буква модуля + 1 локальная (Notice .n → unn). Не n — занята nav в @elcrm/components (см. REGISTER.md).

| Путь | Назначение | | -------------------------- | ------------------------------------------------------- | | @elcrm/notice/style.css | Стили компонента (обязательно) | | @elcrm/notice/tokens.css | Геометрия (--notice-*) + --elcrm-z-notice | | @elcrm/notice/light.css | Цвета светлой темы (html/body [data-theme=light]) | | @elcrm/notice/dark.css | Цвета тёмной темы (html/body [data-theme=dark]) |

Алиас @elcrm/notice/dist/style.css тоже работает (совместимость).

Пример с переключением темы:

import "@elcrm/notice/style.css";
import "@elcrm/notice/tokens.css";
import "@elcrm/notice/light.css";
// import "@elcrm/notice/dark.css";

Или через elcrm.css + elcrm css (допишет @import и недостающие цвета в theme*).

Переменные --notice-* / --elcrm-z-notice можно переопределить в своём CSS (см. CSS-переменные).

API

`Notice.Init`

Контейнер уведомлений. Должен быть смонтирован один раз (пока нужны тосты). Пока список пустой, в DOM ничего не рендерится.

Параметры (className + NoticeInitConfig):

| Параметр | Тип | По умолчанию | Описание | | -------------- | --------- | ------------ | ------------------------------------------------------------------ | | className | string | — | Дополнительный класс контейнера (ul) | | durationMs | number | 1800 | Автоскрытие обычных уведомлений (мс), не меньше 100 | | pauseOnHover | boolean | true | Пауза таймера Undo при наведении | | undoLabel | string | "Отменить" | Текст кнопки в Undo, если не переопределён в вызове | | maxVisible | number | 5 | Максимум одновременно видимых карточек (не меньше 1) | | icon | boolean | true | true — иконка слева; false — вертикальная палочка (accent) | | position | см. ниже | — | Позиция через inset без ручного CSS | | titles | объект | см. ниже | Заголовки по типам уведомлений |

position: "top-right" | "top-left" | "bottom-right" | "bottom-left".
Задаёт CSS-переменную --notice-inset. Если не указан — используются только ваши глобальные переменные / дефолты.

titles — частичное переопределение заголовков:

| Ключ | Тип уведомления | | --------- | ---------------- | | error | Notice.Error | | success | Notice.Success | | remark | Notice.Remark | | copy | Notice.Copy | | undo | Notice.Undo |

<Notice.Init
    durationMs={2000}
    maxVisible={4}
    icon={false}
    position="bottom-right"
    titles={{
        success: "Успех:",
        error: "Ошибка:",
        undo: "Отмена действия:",
    }}
/>

Методы показа

Сигнатуры для Error, Success, Remark, Copy:

Notice.Error(text, hideOrOptions?): NoticeId

text — строка текста.
hideOrOptions — либо boolean (как раньше: автоскрытие), либо объект NoticeShowOptions (см. ниже).

| Метод | Назначение | | ------------------------- | -------------------------- | | Notice.Error(text, …) | Ошибка | | Notice.Success(text, …) | Успех | | Notice.Remark(text, …) | Подсказка | | Notice.Copy(text, …) | Копирование в буфер и т.п. |

`NoticeShowOptions` и `NoticeAction`

type NoticeShowOptions = {
    hide?: boolean; // автоскрытие (по умолчанию true для этих методов)
    actions?: NoticeAction[]; // до 2 кнопок справа
};

type NoticeAction = {
    label: string;
    onClick?: () => void;
    disabled?: boolean;
    tone?: "primary" | "secondary";
};

Пример с кнопками:

Notice.Success("Файл сохранён", {
    hide: true,
    actions: [
        { label: "Открыть", onClick: () => openFile() },
        { label: "Отмена", tone: "secondary", onClick: () => {} },
    ],
});

`Notice.Undo`

Notice.Undo(text, options?): NoticeId

| Поле в options | Тип | Описание | | ---------------- | ------------ | -------------------------------------------------------- | | durationMs | number | Длительность таймера (мс); по умолчанию из Notice.Init | | undoLabel | string | Подпись кнопки отмены | | pauseOnHover | boolean | Пауза при наведении | | onUndo | () => void | Клик по «Отменить» | | onTimeout | () => void | Время истекло (без отмены) |

`Notice.Send`

Универсальная отправка с типом из payload:

Notice.Send({
    type: "error" | "success" | "remark" | "copy",
    text: string,
    hide?: boolean,
    actions?: NoticeAction[],
}): NoticeId

`Notice.Custom`

Notice.Custom(element: React.ReactNode, hide?: boolean): NoticeId

Произвольный контент; hide — автоскрытие (по умолчанию true).

`Notice.Close` / `Notice.CloseAll`

Notice.Close(id: NoticeId): void
Notice.CloseAll(): void

Быстрые рецепты

Только «не скрывать само»

Notice.Error("Сообщение", false);

Объект опций (в т.ч. с кнопками)

Notice.Success("Готово", { hide: false });

Notice.Remark("Проверьте поле", {
    actions: [{ label: "OK", onClick: () => Notice.CloseAll() }],
});

Таймер Undo + закрытие по `id`

const id = Notice.Undo("Элемент будет удалён", {
    durationMs: 5000,
    onUndo: () => restoreItem(),
    onTimeout: () => deleteItem(),
});
// Notice.Close(id);

Позиция без ручных `--notice-inset`

<Notice.Init position="top-left" />

Тёмная тема

import "@elcrm/notice/style.css";
import "@elcrm/notice/dark.css";

CSS-переменные и позиция

Позиция через Notice.Init задаёт inset в формате top/right/bottom/left (в т.ч. auto). Дополнительно можно настроить вручную:

Геометрия — в tokens.css (:root). Цвета — в light.css / dark.css под html[data-theme] / body[data-theme].

:root {
    --notice-inset: 20px 20px auto auto;
    --notice-width: clamp(280px, 92vw, 360px);
    --notice-height: auto;
    --notice-radius: 20px;
    --notice-filter: blur(5px);
    --notice-family: system-ui, sans-serif;
    --elcrm-z-notice: 1000;
}

html[data-theme="light"],
body[data-theme="light"] {
    --notice-background: rgba(255, 255, 255, 0.95);
    --notice-border: transparent;
    --notice-color: #333333;
    --notice-error: #bb2014;
    --notice-success: #367738;
    --notice-remark: #b77513;
    --notice-copy: #3f51b5;
    --notice-undo: #5c6bc0;
}

Доступность (a11y)

Контейнер списка: aria-live="polite", aria-relevant="additions text".
Карточка: role="status" или для Undo — role="alertdialog", aria-live соответственно.
Кнопки отмены и действий: видимый фокус :focus-visible, подписи для таймера Undo.
При prefers-reduced-motion: reduce упрощаются анимации и переходы прогресс-бара.

Миграция

| Раньше | Сейчас | | -------------------------------- | --------------------------------------------------------------------------------------------------------- | | Второй аргумент только boolean | Можно по-прежнему: Notice.Success("Текст", true) | | Нет id | Все методы показа возвращают NoticeId | | Нет глобального конфига | durationMs, pauseOnHover, undoLabel, maxVisible, icon, position, titles в <Notice.Init /> | | Нет действий | Notice.Success("…", { actions: [...] }) и Notice.Send({ …, actions }) | | Только CSS для угла | position="top-right" и т.д. в Notice.Init |

Дополнительно

Автоскрытие

Если hide !== false и для типа задан durationMs в рантайме, срабатывает таймер. Undo не использует автоскрытие по hide — только таймер отмены.

Клик по карточке

Для обычных уведомлений без кнопок действий клик по карточке закрывает её. Для Undo и карточек с actions клик по фону не закрывает (закрытие — через кнопки / таймер).

Несколько уведомлений

Новые добавляются в конец; ограничение — maxVisible в Notice.Init.

Типы и экспорты

Из пакета реэкспортируются:

NoticeId, NoticeInitConfig, NoticeAction, NoticeShowOptions, NoticePayload, UndoNoticeOptions, TCustomItem

import type { NoticeInitConfig, NoticeAction } from "@elcrm/notice";

`TCustomItem`

type TCustomItem = {
    key: number;
    text: React.ReactNode;
    hide?: boolean;
};

Требования

React ≥ 18 (peer)
Node ≥ 18 (сборка / CI)
Поддержка CSS-переменных в браузере

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme