@boobooking/dashboard-ui-components 0.12.0 → 0.14.0

package/README.md

@@ -15,16 +15,19 @@ import '@boobooking/dashboard-ui-components/style.css'
 
 ### Подключение к приложению
 
-Плагин `dashboardUi` задаёт язык и переход по ссылкам пакета. Оба параметра
-необязательны; без плагина компоненты русскоязычные, а ссылки — обычные `<a>`.
+Плагин `dashboardUi` задаёт язык, переход по ссылкам пакета и адрес
+страницы на экране. Все параметры необязательны; без плагина компоненты
+русскоязычные, ссылки — обычные `<a>`, а `PageCard` закрывается только на
+`fallback-url`.
 
 ```js
 import { dashboardUi } from '@boobooking/dashboard-ui-components'
-import { router } from '@inertiajs/vue3'
+import { router, usePage } from '@inertiajs/vue3'
 
 createApp(App).use(dashboardUi, {
     lang: 'en',
     navigate: (href) => router.visit(href),
+    currentUrl: () => usePage().url,
 })
 ```
 
@@ -35,6 +38,18 @@ createApp(App).use(dashboardUi, {
   настоящий `<a href>` и отдают `navigate` только обычный клик левой кнопкой;
   клики с Ctrl/Cmd/Shift/Alt, средней кнопкой и ссылки с `target` остаются
   браузеру. Без `navigate` браузер идёт по ссылке сам.
+- `currentUrl()` — адрес страницы на экране, по нему `PageCard` знает,
+  откуда его открыли. Для Inertia — `() => usePage().url` (проверено на
+  `@inertiajs/vue3` 3.6.1). Договор для другого роутера: функция читает
+  реактивное состояние роутера; её значение меняется при каждом показе
+  страницы с новым адресом, в том числе при замене записи истории,
+  «Назад»/«Вперёд» и первой загрузке, и меняется до создания компонентов
+  новой страницы; неуспешный или отменённый переход значения не меняет;
+  пока роутер не готов, функция возвращает `null` или `undefined`.
+  У Vue Router, например, до первой навигации `currentRoute` —
+  `START_LOCATION` с `fullPath === '/'`, и его надо отдавать как `null`.
+  Плагин следит за адресом только в браузере и перестаёт при
+  размонтировании приложения.
 
 `navigate` получает адрес ровно таким, каким он лежит в компоненте:
 пагинация `DataTable` отдаёт `links` Laravel как есть, а это абсолютные URL. С Vue
@@ -211,6 +226,18 @@ Chrome 114+, Firefox 125+. В браузерах старше меню видн
 События: `update:modelValue` и `changed` — при выборе элемента (повторный
 клик по уже выбранному снимает выбор) и при очистке через ластик.
 
+С клавиатуры: пока список открыт, стрелки вверх и вниз переводят фокус по
+пунктам и страницу не прокручивают. Отсчёт идёт от выбранного пункта: вниз —
+следующий за ним, вверх — предыдущий; без выбранного вниз — первый пункт,
+вверх — последний; с краёв — по кругу. Enter или пробел выбирают пункт под
+фокусом так же, как клик, Escape закрывает список. После закрытия фокус
+возвращается на кнопку фильтра. У закрытого списка стрелки прокручивают
+страницу.
+
+Подсветка пункта — это фокус, и мышь ведёт тот же фокус: движение по пункту
+ставит фокус на него, стрелки продолжают от пункта под курсором. Подсвечен
+всегда один пункт — тот, на который последними указали клавиатура или мышь.
+
 ### SmallBadge
 
 Бейдж-пилюля с коротким текстом. Текст не переносится.
@@ -301,19 +328,45 @@ ConfirmationModal нет v-model».
 ### DropdownButtonWithAction
 
 Кнопка с меню дополнительных действий: основная часть — слот `button`, стрелка
-справа открывает меню из слота `actions`. Без слота `actions` стрелки нет, и
+справа открывает меню из пунктов пропа `actions`. Без пунктов стрелки нет, и
 кнопка скругляется с обеих сторон.
 
-    <dropdown-button-with-action v-model="menuIsOpen">
+    <dropdown-button-with-action
+        v-model="menuIsOpen"
+        :actions="[
+            { label: 'Поменять пароль', href: route('user.password.edit', { user: row.getId() }) },
+            { label: 'Удалить', danger: true, onSelect: () => prepareUserDelete(row) },
+        ]"
+    >
         <template #button>…основное действие…</template>
-        <template #actions>…пункты меню…</template>
     </dropdown-button-with-action>
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
+| `actions` | `Array` | `[]` | Пункты меню, см. ниже |
 | `modelValue` | `Boolean` | `false` | Открыто ли меню |
 | `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
+Пункт меню — объект одной из двух форм: переход (`href` без `onSelect`) или
+действие (`onSelect` без `href`). Поле со значением `undefined` считается
+отсутствующим.
+
+| Поле | Тип | Описание |
+| --- | --- | --- |
+| `label` | `String`, обязательно | Текст пункта |
+| `href` | `String` | Переход: обычный клик уходит в `navigate` плагина `dashboardUi`, клик с Cmd/Ctrl/Shift и средней кнопкой — браузеру; без `navigate` — обычная ссылка |
+| `onSelect` | `Function` | Действие: вызывается без аргументов при выборе пункта |
+| `danger` | `Boolean` | Опасный пункт — красный; по умолчанию `false` |
+
+Неверный список Vue отмечает предупреждением о пропе в режиме разработки,
+а компонент не падает: элементы-необъекты пропускает, кнопка без функции
+`onSelect` только закрывает меню. `null` — пустой список.
+
+Вид пунктов задаёт компонент: страница передаёт данные, а не разметку,
+и классов пунктам не даёт. Обычный пункт — серый текст, при подсветке —
+серый фон; опасный — красный фон, при подсветке темнее. Слота `actions`
+нет с версии 0.14.0 — см. «Обновление с 0.13».
+
 Событие: `update:modelValue` — только когда меню открыл или закрыл сам
 компонент или браузер: клик по стрелке, клик вне меню, Escape, клик
 по пункту меню, прокрутка, изменение размера окна. Значение, пришедшее
@@ -327,6 +380,14 @@ ConfirmationModal нет v-model».
 по любому пункту, прокруткой страницы или таблицы и изменением размера
 окна. Открытие другого меню закрывает предыдущее.
 
+Пока меню открыто, стрелки вверх и вниз переводят фокус по пунктам и
+страницу не прокручивают: вниз — на первый пункт, вверх — на последний,
+дальше — по соседним, с краёв — по кругу. Enter на пункте под фокусом
+выбирает его. Подсветка пункта — это фокус, и мышь ведёт тот же фокус:
+движение по пункту ставит фокус на него, стрелки продолжают от пункта под
+курсором. Подсвечен всегда один пункт — тот, на который последними указали
+клавиатура или мышь.
+
 ### DataTable
 
 Список данных: бейдж «Найдено X: N», таблица в карточке с горизонтальной
@@ -421,64 +482,137 @@ ConfirmationModal нет v-model».
 
 ### PageCard
 
-Карточка отдельной страницы — формы или просмотра записи — по центру с
-крестиком «назад по истории».
+Карточка отдельной страницы — формы или просмотра записи — по центру
+с крестиком, который ведёт туда, откуда карточку открыли.
 
-    <page-card class="px-4 pt-4 sm:px-6 sm:pt-6">
+    <page-card class="px-4 pt-4 sm:px-6 sm:pt-6" :fallback-url="route('users')">
         <h3 class="pr-(--bb-closer-space) text-lg font-medium">Создание администратора</h3>
         …поля формы…
     </page-card>
 
 Страница просмотра, у секций которой свои отступы:
 
-    <page-card>
+    <page-card :fallback-url="route('payments')">
         <div class="px-4 py-5 border-b border-gray-200 sm:px-6">
             <h3 class="pr-(--bb-closer-space) text-lg font-medium">{{ name }}</h3>
         </div>
         <div class="overflow-hidden sm:rounded-b-lg">…строки…</div>
     </page-card>
 
-Карточка — `relative my-6 mx-auto bg-white shadow-xl sm:max-w-xl
-sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: форма передаёт
-их классом на корень, страница просмотра — не передаёт. Классы и атрибуты
-приложения попадают на корень и сильнее классов пакета. Ресет пакета на
-карточку и её содержимое не распространяется: разметка страницы, в том числе
-поля `@tailwindcss/forms`, выглядит так же, как вне карточки.
-
-Крестик показан, если в истории вкладки больше одной записи
-(`history.length > 1`, значение читается один раз после монтирования), и по
-клику возвращает назад (`history.back()`). При серверном рендеринге (SSR)
-сервер историю вкладки не знает и отдаёт карточку без крестика: крестик
-появляется сразу после гидратации, и на экранах уже `md` заголовок в этот
-момент сдвигается, освобождая под него место. Без SSR крестик появляется до
-первой отрисовки. `history.length` считает и записи впереди текущей, поэтому
-это не гарантия, что назад есть куда. От `md` крестик стоит
-снаружи карточки, на `1rem` правее её края; ниже `md` — в её правом верхнем
-углу. Порог рассчитан на карточку по центру области на всю ширину страницы: в
-узкой колонке или рядом с боковой панелью места снаружи может не хватить. Он
-рассчитан и на ширину карточки по умолчанию (`max-w-xl`, 36rem): если передать
-классом на корень более широкую, места снаружи тоже может не хватить.
+**Куда ведёт крестик.** Плагин `dashboardUi` с `currentUrl` (см.
+«Подключение к приложению») помнит адрес страницы, которая была на экране
+перед карточкой, со всеми её фильтрами и номером страницы, и крестик
+ведёт ровно туда. Адрес не попадает ни в адрес страницы, ни в хранилища
+браузера, ни в историю: он живёт в памяти приложения. «Как было» — это
+адрес: прокрутку, несохранённый ввод и раскрытые элементы
+страницы-источника карточка не возвращает.
+
+Если адреса нет — карточку открыли в новой вкладке, прямой ссылкой, после
+F5 или в приложении без `currentUrl`, — крестик ведёт на `fallback-url`.
+Без `fallback-url` крестика нет. Истории браузера карточка не касается.
+
+**Окна.** Открытая карточка — окно. Карточка, открытая со страницы
+другой карточки (например, форма с таба), — вложенное окно: её крестик
+ведёт на страницу, с которой её открыли, а крестик внешней карточки —
+по-прежнему туда, откуда открыли её. Окно закрывается, когда показана
+страница, куда оно возвращает: крестиком, «Отменой», после успешного
+действия или кнопкой «Назад» браузера.
+
+**Карточка из нескольких страниц** (табы) — постоянный макет этих страниц
+Inertia с общим ключом окна:
+
+    export default {
+        layout: (props) => [PageCard, {
+            width: '7xl',
+            windowKey: `group:${props.group.data.uuid}`,
+            fallbackUrl: route('groups'),
+            class: 'px-4 py-4 sm:px-6 sm:py-6',
+        }],
+    }
+
+`layout` — стрелочная функция одного аргумента или кортеж: обычную
+функцию Inertia примет за компонент. Пока соседние страницы объявляют тот
+же макет, карточка не пересоздаётся, и смена таба, фильтров и страницы
+таблицы окна не меняет. Ключ окна по умолчанию — путь страницы без query:
+отдельной странице-карточке его задавать не нужно, а если роутер
+переиспользовал её для другой записи (`/users/1/edit` → `/users/2/edit`),
+у неё новое окно. Ключ меняется только вместе со сменой страницы: смена
+без неё оставляет карточку в прежнем окне и пишет предупреждение
+в консоль. Рецепт проверен на `@inertiajs/vue3` 3.6.1.
+
+**«Отмена» и закрытие из кода.** `close()` делает то же, что крестик.
+Он доступен пропом слота по умолчанию и методом компонента:
+
+    <page-card ref="card" v-slot="{ close }" :fallback-url="route('users')">
+        …
+        <button type="button" @click="close">Отмена</button>
+    </page-card>
+
+    // после успешного сохранения
+    this.$refs.card.close()
+
+`close()` переходит через `navigate` плагина, без него — полной загрузкой
+страницы. Без адреса возврата и `fallback-url` он ничего не делает.
+
+**Ширина и крестик.** От `width` зависят ширина карточки и порог, от
+которого крестик стоит снаружи, на `1rem` правее её края; ниже порога —
+в правом верхнем углу:
+
+| `width` | Ширина от `sm` | Крестик снаружи |
+| --- | --- | --- |
+| `xl` (по умолчанию) | `max-w-xl` (36rem) | от `md` |
+| `4xl` | `max-w-4xl` (56rem) | от `lg` |
+| `7xl` | `max-w-7xl` (80rem) | от `2xl` |
+
+Пороги рассчитаны на карточку по центру области на всю ширину страницы:
+в узкой колонке или рядом с боковой панелью места снаружи может не
+хватить.
 
 Заголовок оставляет место под крестик правым отступом из переменной
-`--bb-closer-space`: `3.5rem`, пока крестик в углу, `0` — когда он снаружи или
-его нет. В Tailwind это `pr-(--bb-closer-space)`; без Tailwind 4 — обычный CSS
-`padding-right: var(--bb-closer-space)`, а в Tailwind 3 —
+`--bb-closer-space`: `3.5rem`, пока крестик в углу, `0` — когда он снаружи
+или его нет. В Tailwind это `pr-(--bb-closer-space)`; без Tailwind 4 —
+обычный CSS `padding-right: var(--bb-closer-space)`, а в Tailwind 3 —
 `pr-[var(--bb-closer-space)]`. Вне `PageCard` отступ равен нулю.
 
-Карточка не обрезает содержимое, как у `ConfirmationModal`: выпадающие списки
-и календари могут выходить за её край. Блок со своим фоном у края карточки
-скругляет свои углы сам — например, нижний блок строк:
+**Атрибуты.** Карточка — `relative my-6 mx-auto bg-white shadow-xl
+sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: форма
+передаёт их классом на корень, страница просмотра — не передаёт. На корень
+попадают `class`, `style`, `data-*` и `aria-*` приложения; классы
+приложения сильнее классов пакета. Остальные атрибуты, в том числе `id`,
+не переносятся: в роли макета карточка получает атрибутами пропы
+страницы. Пропы страницы с именами пропов карточки — `lang`, `width`,
+`fallbackUrl`, `windowKey` — приходят ей пропами, а не атрибутами; кортеж
+макета перекрывает только те, что задаёт сам. Ресет пакета на карточку и её содержимое не распространяется:
+разметка страницы, в том числе поля `@tailwindcss/forms`, выглядит так же,
+как вне карточки.
+
+Карточка не обрезает содержимое, как у `ConfirmationModal`: выпадающие
+списки и календари могут выходить за её край. Блок со своим фоном у края
+карточки скругляет свои углы сам — например, нижний блок строк:
 `overflow-hidden sm:rounded-b-lg`.
 
-Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции крестик
-идёт после содержимого карточки; при фокусе с клавиатуры
-вокруг него кольцо. Доступное имя — «Назад» / «Back».
+Крестик доступен с клавиатуры: Tab, Enter, пробел; в порядке табуляции
+крестик идёт после содержимого карточки; при фокусе с клавиатуры вокруг
+него кольцо. Доступное имя — «Назад» / «Back».
 
 | Проп | Тип | По умолчанию | Описание |
 | --- | --- | --- | --- |
+| `width` | `String` | `"xl"` | `"xl"`, `"4xl"` или `"7xl"` |
+| `fallback-url` | `String` | `null` | куда закрываться без адреса возврата; `""` — как `null` |
+| `window-key` | `String` | путь страницы | общий ключ окна карточки из нескольких страниц |
 | `lang` | `String` | язык плагина | `"ru"` или `"en"` |
 
-Событий нет.
+Событий нет. Проп слота по умолчанию — `close`.
+
+Ограничения:
+
+- память плагина не переживает F5 и новую вкладку: тогда работает
+  `fallback-url`;
+- адреса сравниваются строкой: равнозначный адрес с другим порядком
+  параметров или с лишним `page=1` — другой адрес;
+- если вернуться в карточку «Назад» или «Вперёд» после ухода из неё не
+  через крестик, адрес возврата — страница, с которой пришли в этот раз;
+- на одной странице — одна карточка.
 
 ### NotificationMessage
 
@@ -549,8 +683,9 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 Inertia SSR), а серверная разметка гидратируется без расхождений. К API
 браузера компоненты обращаются только после монтирования, поэтому:
 
-- `PageCard` на сервере рисует карточку без крестика: история вкладки
-  известна только в браузере. Крестик появляется сразу после гидратации;
+- `PageCard` на сервере рисует крестик, только если задан `fallback-url`:
+  адрес возврата известен только в браузере, и крестик, ведущий на него,
+  появляется после монтирования;
 - `PickDay` загружает Pikaday в браузере при монтировании: календарь
   появляется, когда загрузка закончится;
 - остальные компоненты рендерятся на сервере так же, как в браузере.
@@ -650,6 +785,50 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
 задаётся, см. «Языки».
 
+## Обновление с 0.13
+
+- `DropdownButtonWithAction`: пункты меню передаются пропом `actions`,
+  слот `actions` убран, и страница больше не оформляет пункты — вид задаёт
+  компонент. Было:
+
+      <template v-slot:actions>
+          <Link
+              class="block px-4 py-2 text-sm text-gray-700 hover:bg-gray-100 hover:text-gray-900"
+              :href="route('user.password.edit', {'user': row.getId()})"
+          >
+              Поменять пароль
+          </Link>
+          <a
+              href="#"
+              @click.prevent="prepareUserDelete(row)"
+              class="block px-4 py-2 text-sm bg-red-400 hover:bg-red-500 text-white"
+              role="menuitem"
+          >
+              Удалить
+          </a>
+      </template>
+
+  Стало — проп на самом `dropdown-button-with-action`:
+
+      :actions="[
+          { label: 'Поменять пароль', href: route('user.password.edit', { user: row.getId() }) },
+          { label: 'Удалить', danger: true, onSelect: () => prepareUserDelete(row) },
+      ]"
+
+  Меню со старым слотом остаётся без пунктов и без стрелки; в режиме
+  разработки компонент пишет об этом в консоль.
+- `0.14.0` не подтянется по `^0.13.0`: для версий `0.x` знак `^` пропускает
+  только патчи. Обновление — `npm install @boobooking/dashboard-ui-components@^0.14.0`.
+
+## Обновление с 0.12
+
+- Крестик `PageCard` больше не ходит по истории: подключите `currentUrl`
+  к плагину и дайте карточкам `fallback-url`. Без них крестика нет.
+- На корень `PageCard` переносятся только `class`, `style`, `data-*`
+  и `aria-*`.
+- Карточка из нескольких страниц объявляет `PageCard` постоянным макетом
+  с `window-key` (см. раздел `PageCard`).
+
 ## Обновление с 0.11
 
 - `Pagination` больше не экспортируется. Страница, импортирующая её