@boobooking/dashboard-ui-components 0.12.0 → 0.13.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
@@ -421,64 +436,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 +637,9 @@ sm:rounded-lg`, `box-sizing: border-box`. Отступов у неё нет: ф
 Inertia SSR), а серверная разметка гидратируется без расхождений. К API
 браузера компоненты обращаются только после монтирования, поэтому:
 
-- `PageCard` на сервере рисует карточку без крестика: история вкладки
-  известна только в браузере. Крестик появляется сразу после гидратации;
+- `PageCard` на сервере рисует крестик, только если задан `fallback-url`:
+  адрес возврата известен только в браузере, и крестик, ведущий на него,
+  появляется после монтирования;
 - `PickDay` загружает Pikaday в браузере при монтировании: календарь
   появляется, когда загрузка закончится;
 - остальные компоненты рендерятся на сервере так же, как в браузере.
@@ -650,6 +739,15 @@ Tailwind, `@tailwindcss/forms` и типографикой, как у потре
 Правила номера телефона в `RussianMobileFilter` — российские; язык текстов
 задаётся, см. «Языки».
 
+## Обновление с 0.12
+
+- Крестик `PageCard` больше не ходит по истории: подключите `currentUrl`
+  к плагину и дайте карточкам `fallback-url`. Без них крестика нет.
+- На корень `PageCard` переносятся только `class`, `style`, `data-*`
+  и `aria-*`.
+- Карточка из нескольких страниц объявляет `PageCard` постоянным макетом
+  с `window-key` (см. раздел `PageCard`).
+
 ## Обновление с 0.11
 
 - `Pagination` больше не экспортируется. Страница, импортирующая её