@carparkteam/parz-ui 0.0.0-stage → 1.0.1

package/docs/parz-menu.ru.md

@@ -0,0 +1,393 @@
+# Parz Menu
+
+[English](parz-menu.en.md) · [Հայերեն](parz-menu.hy.md) · **Русский**
+
+Нижнее меню CarPark, вынесенное в React-компонент. Подсветка активного пункта перетекает между вкладками как капля, круглые кнопки справа упруго отвечают на нажатие. Вид настраивается целиком: цвета, размеры, скругления, стекло, скорость и сила анимаций.
+
+- до 5–6 пунктов с иконкой и подписью, бейдж-число или бейдж-точка на любом пункте;
+- круглые кнопки справа: иконка или аватар (буквы или фото), тоже с бейджем;
+- иконки: встроенные из CarPark, Material Symbols, Material Icons или любой свой React-элемент;
+- три раскладки: иконка над подписью, в строку, только иконки;
+- прилипает к низу или верху экрана либо стоит в потоке страницы;
+- уважает системную настройку «уменьшить движение» и работает с клавиатуры.
+
+## Установка
+
+```bash
+npm install @carparkteam/parz-ui
+```
+
+```tsx
+import { ParzMenu } from '@carparkteam/parz-ui';
+import '@carparkteam/parz-ui/style.css';
+```
+
+## Быстрый старт
+
+```tsx
+import { useState } from 'react';
+import { ParzMenu } from '@carparkteam/parz-ui';
+import '@carparkteam/parz-ui/style.css';
+
+export function AppNav() {
+  const [tab, setTab] = useState('garage');
+  const [panel, setPanel] = useState<string | null>(null);
+
+  return (
+    <ParzMenu
+      items={[
+        { id: 'garage', label: 'Гараж', icon: 'ms:directions_car' },
+        { id: 'parking', label: 'Парковка', icon: 'ms:local_parking', badge: 2 },
+        { id: 'map', label: 'Карта', icon: 'pin' }
+      ]}
+      value={panel ?? tab}
+      onChange={id => { setPanel(null); setTab(id); }}
+      actions={[
+        { id: 'notif', ariaLabel: 'Уведомления', icon: 'bell', badge: 'dot' },
+        { id: 'profile', ariaLabel: 'Профиль', avatar: { text: 'A' } }
+      ]}
+      activeAction={panel}
+      onAction={id => setPanel(p => (p === id ? null : id))}
+    />
+  );
+}
+```
+
+Когда открыт раздел из круглой кнопки, передайте в `value` его id: капля под пунктами спрячется, потому что такого пункта нет. Так сделано в CarPark.
+
+## Пропсы
+
+| Проп | Тип | По умолчанию | Что делает |
+|---|---|---|---|
+| `items` | `TabItem[]` | — | Пункты меню |
+| `value` | `string \| null` | — | Активный пункт (управляемый режим). Нет такого пункта или `null` — капля прячется |
+| `defaultValue` | `string` | первый пункт | Активный пункт без управления снаружи |
+| `onChange` | `(id) => void` | — | Нажали пункт |
+| `actions` | `ActionItem[]` | `[]` | Круглые кнопки справа, не больше двух. Любые: колокольчик, профиль, «+», поиск… |
+| `activeAction` | `string \| null` | `null` | Какая круглая кнопка подсвечена |
+| `onAction` | `(id) => void` | — | Нажали круглую кнопку |
+| `hideActions` | `boolean` | `false` | Спрятать круглые кнопки справа. Меню сожмётся по пунктам и встанет по центру |
+| `position` | `'bottom' \| 'top' \| 'static'` | `'bottom'` | Прилипать к низу или верху экрана либо стоять в потоке |
+| `layout` | `'stacked' \| 'inline' \| 'icons'` | `'stacked'` | Иконка над подписью, в строку или только иконки |
+| `theme` | `Partial<ParzMenuTheme>` | — | Цвета и размеры, см. ниже |
+| `glass` | `number \| GlassPreset` | — | Прозрачность стекла: 0…100 % или пресет, см. «Стекло» |
+| `overflow` | `'more' \| 'none'` | `'more'` | Что делать, если пункты не помещаются: прятать в кнопку «Меню» или нет |
+| `minItemWidth` | `number` | 64 / 104 / 52 | Уже какой ширины пункт уходит в «Меню», px. По умолчанию зависит от `layout` |
+| `locale` | `'en' \| 'ru' \| 'hy'` | `'en'` | Язык встроенных подписей: «Меню», поиск, озвучка бейджей. Свои `moreLabel`, `ariaLabel`, `searchPlaceholder` важнее |
+| `moreLabel` | `string` | по `locale` | Подпись кнопки «Меню» |
+| `mobileSearch` | `boolean \| MobileSearchOptions` | — | Поиск на узком экране, как в iOS, см. «Поиск на телефоне» |
+| `desktop` | `boolean \| DesktopOptions` | — | **Beta.** Шапка для больших экранов, см. «Шапка для компьютера» |
+| `moreIcon` | `IconSpec` | `'more'` | Иконка кнопки «Меню». По умолчанию — три точки в круге: контур, а когда открыт спрятанный пункт — заливка |
+| `motion` | `Partial<LiquidMotion>` | — | Анимации, см. ниже |
+| `maxBadge` | `number` | `99` | Числа больше показываются как «99+» |
+| `badgeLabel` | `(label, badge) => string` | — | Как диктор читает пункт с бейджем |
+| `autoLoadFonts` | `boolean` | `true` | Сам подключать шрифты Material, если они есть в иконках |
+| `ariaLabel` | `string` | по `locale` | Подпись всего меню для диктора |
+| `className`, `style` | — | — | Обычные |
+
+### TabItem
+
+| Поле | Тип | Что делает |
+|---|---|---|
+| `id` | `string` | Уникальный ключ |
+| `label` | `string` | Подпись |
+| `icon` | `IconSpec` | Иконка, см. «Иконки» |
+| `activeIcon` | `IconSpec` | Своя иконка для активного состояния. Встроенным и Material Symbols не нужна |
+| `badge` | `number \| string \| 'dot' \| boolean` | Бейдж. `0`, `false`, `null` — нет бейджа |
+| `disabled` | `boolean` | Пункт неактивен |
+| `ariaLabel` | `string` | Подпись для диктора вместо `label` |
+
+### ActionItem
+
+| Поле | Тип | Что делает |
+|---|---|---|
+| `id` | `string` | Уникальный ключ |
+| `ariaLabel` | `string` | Подпись для диктора. Обязательна: у кнопки нет текста |
+| `icon`, `activeIcon` | `IconSpec` | Иконка |
+| `avatar` | `{ text?: string; src?: string }` | Аватар вместо иконки: буквы или фото |
+| `badge` | как у пункта | Бейдж |
+| `variant` | `'default' \| 'accent'` | `accent` — залитая цветом кнопка для главного действия, например «+» |
+
+## Кнопки справа
+
+В группе справа — до двух круглых кнопок, любых. Колокольчик и аватар в примерах — просто самый частый вариант. Если передать больше двух, покажутся первые две, а в консоли будет предупреждение.
+
+Кнопка бывает трёх видов:
+- **иконка** — как колокольчик: `{ id: 'notif', ariaLabel: 'Уведомления', icon: 'bell' }`;
+- **акцентная** — залита цветом, для главного действия: `{ id: 'add', ariaLabel: 'Добавить', icon: 'plus', variant: 'accent' }`;
+- **аватар** — буквы или фото: `{ id: 'profile', ariaLabel: 'Профиль', avatar: { src: '/me.jpg' } }`.
+
+Кнопка может открывать свой раздел (тогда передайте её id в `activeAction` — она подсветится, а капля под пунктами спрячется) или просто выполнять действие, как «+»: тогда ничего подсвечивать не нужно.
+
+```tsx
+<ParzMenu
+  items={items}
+  value={panel ?? tab}
+  onChange={id => { setPanel(null); setTab(id); }}
+  actions={[
+    { id: 'notif', ariaLabel: 'Уведомления', icon: 'bell', badge: 3 },
+    { id: 'add', ariaLabel: 'Добавить', icon: 'plus', variant: 'accent' }
+  ]}
+  activeAction={panel}
+  onAction={id => (id === 'add' ? openCreateSheet() : setPanel(p => (p === id ? null : id)))}
+/>
+```
+
+## Пункты и кнопки на лету
+
+Пункты и кнопки справа можно добавлять и убирать в любой момент — например, скрипт на сайте включает пункт «Акции», когда началась распродажа. Ничего не дёргается:
+
+- уходящий пункт или кнопка плавно схлопывается, соседи сдвигаются на его место;
+- новый «вырастает» из нуля с упругим перелётом;
+- кнопка «Меню» появляется и исчезает так же, когда пункты перестают или снова начинают помещаться;
+- капля едет вместе со своим пунктом.
+
+Длительность — та же `motion.shift`. Достаточно просто поменять массив `items` или `actions`:
+
+```tsx
+const items = [garage, parking, ...(saleIsOn ? [sale] : [])];
+```
+
+## Меню без кнопок справа
+
+Если не передать `actions` или поставить `hideActions`, группы справа нет. Переключение `hideActions` анимируется: группа сворачивается, капсула с пунктами плавно сужается и переезжает в центр, капля едет за своим пунктом. Скорость задаёт `motion.shift`. Тогда капсула с пунктами не тянется на всю ширину, а сжимается по содержимому и встаёт по центру. Освободившееся место можно отдать под пункты: на телефоне спокойно помещается 5–6.
+
+```tsx
+<ParzMenu
+  items={[
+    { id: 'home', label: 'Главная', icon: 'ms:home' },
+    { id: 'search', label: 'Поиск', icon: 'ms:search' },
+    { id: 'parking', label: 'Парковка', icon: 'ms:local_parking', badge: 2 },
+    { id: 'saved', label: 'Избранное', icon: 'ms:favorite' },
+    { id: 'profile', label: 'Профиль', icon: 'ms:person', badge: 'dot' }
+  ]}
+  value={tab}
+  onChange={setTab}
+/>
+```
+
+Пункты одинаковой ширины, её задаёт `theme.itemMinWidth` (84 px). Капсула шириной «пункты × эта ширина», но не шире экрана. Если пункты не влезают, они делят ширину поровну, а длинные подписи обрезаются многоточием — тогда лучше `layout="icons"`.
+
+## Если пункты не помещаются
+
+Компонент сам следит за шириной. Когда пункт становится уже `minItemWidth` (64 px для раскладки «иконка над подписью»), последние пункты уходят в кнопку «Меню» (три точки в круге). По нажатию над ней всплывает список спрятанных пунктов: иконка, подпись и бейдж.
+
+- Если открыт спрятанный пункт, капля стоит под «Меню», а в списке он подсвечен.
+- Бейджи спрятанных пунктов собираются на «Меню»: числа складываются, а если чисел нет — ставится точка.
+- Список закрывается выбором пункта, повторным нажатием на «Меню», кликом мимо или клавишей Esc.
+- Ширина пересчитывается при изменении размера окна, поэтому на планшете и компьютере видно больше пунктов.
+
+```tsx
+<ParzMenu items={tenItems} value={tab} onChange={setTab} moreLabel="Ещё" />
+```
+
+Чтобы никогда ничего не прятать, поставьте `overflow="none"` — тогда пункты просто сжимаются.
+
+## Поиск на телефоне
+
+`mobileSearch` добавляет на узком экране поиск в духе iOS. Лупа встаёт первой кнопкой в группу справа; из `actions` остаётся последняя, чтобы в группе по-прежнему было две кнопки.
+
+По нажатию на лупу группа по-жидкому растекается на всю ширину меню, а капсула с пунктами схлопывается. Внутри:
+- слева лупа превращается в «✕» поменьше — закрыть поиск и очистить поле, пункты возвращаются;
+- посередине поле ввода, клавиатура сразу открыта;
+- справа, отдельной круглой кнопкой в своём стекле, — «→» (искать); выкатывается из-за группы и загорается акцентным цветом, когда в поле есть текст.
+
+```tsx
+<ParzMenu
+  items={items}
+  actions={[bell, profile]}            // на телефоне в группе будут лупа и профиль
+  mobileSearch={{ searchPlaceholder: 'Марка или парковка', onSearch: q => navigate(`/search?q=${q}`) }}
+/>
+```
+
+Поля те же, что у поиска в шапке: `searchPlaceholder`, `searchValue` / `onSearchChange`, `onSearch`. На широком экране, если включена шапка, работает её поиск.
+
+## Шапка для компьютера (beta)
+
+На широком экране меню может становиться полноценной верхней шапкой: слева логотип, затем пункты в строку, по центру поиск, справа кнопки. Под шапкой — затенение с размытием, контент красиво уходит под неё при прокрутке. На узком экране меню остаётся обычным нижним.
+
+```tsx
+<ParzMenu
+  items={items}
+  value={tab}
+  onChange={setTab}
+  actions={actions}
+  desktop={{
+    logo: 'CARPARK',                  // строка или любой элемент: <img>, svg, анимированный логотип
+    search: 'expand',                 // 'bar' | 'button' | 'expand' | 'none'
+    searchPlaceholder: 'Марка, модель или парковка…',
+    onSearch: q => navigate(`/search?q=${q}`)
+  }}
+/>
+```
+
+| Поле | По умолчанию | Что делает |
+|---|---|---|
+| `breakpoint` | `1100` | С какой ширины включается шапка, px |
+| `breakpointBy` | `'window'` | Мерить ширину окна или родителя меню (`'parent'` — для узких контейнеров и превью) |
+| `logo` | — | Логотип слева: строка или React-элемент |
+| `search` | `'bar'` | `bar` — отдельная строка поиска; `button` — круглая кнопка поиска в группе справа; `expand` — кнопка в группе справа, которая раскрывается в строку прямо внутри группы; `none` — без поиска |
+| `searchPlaceholder` | по `locale` | Подсказка в строке |
+| `searchValue` / `onSearchChange` | — | Текст поиска, если хотите управлять им сами |
+| `onSearch` | — | Нажали Enter (или кнопку поиска в раскрытой строке) |
+| `onSearchClick` | — | Нажали кнопку поиска в виде `button` — например, открыть свой поиск |
+| `searchShortcut` | `'/'` | Клавиша, которая открывает поиск; `false` — выключить |
+| `searchWidth` | `420` / `320` | Ширина строки поиска, px: отдельной строки — 420, раскрытой внутри группы — 320 |
+| `searchAt` | `'start'` | Где кнопка поиска в группе справа (`button`, `expand` и поиск на телефоне): `start` — первой, `end` — последней |
+| `actionsAlign` | `'end'` | Где стоит группа справа, если нет строки поиска: `end` — у правого края, `next` — сразу за пунктами |
+| `layout` | `'inline'` | Раскладка пунктов в шапке |
+| `maxWidth` | `1360` | Ширина содержимого шапки, px |
+| `height` | `80` | Высота шапки, px |
+
+Цвета шапки — в теме: `headerTop`, `headerMid` (затенение), `headerBlur` (размытие), `searchBg`, `searchBorder` (строка поиска). Если пункты не помещаются рядом с логотипом и поиском, работает то же «Меню», только список открывается вниз. Все переключения шапки плавные: смена вида поиска (строка схлопывается, кнопка «вырастает» в группе), перенос группы между краем и пунктами, появление и смена логотипа, переход между шапкой и нижним меню при смене ширины.
+
+Кнопка поиска в видах `button` и `expand` стоит первой в группе справа и не считается в лимит двух кнопок. Раскрывающийся поиск растягивает всю группу; если пунктам становится тесно, лишние плавно уходят в «Меню». Закрывается клавишей Esc или кликом мимо, если в нём ничего не набрано.
+
+## Бейджи
+
+```tsx
+{ id: 'fines', label: 'Штрафы', icon: 'ms:receipt_long', badge: 3 }     // число
+{ id: 'fines', label: 'Штрафы', icon: 'ms:receipt_long', badge: 150 }   // покажет «99+»
+{ id: 'news', label: 'Новое', icon: 'sparkles', badge: 'dot' }   // точка
+{ id: 'sale', label: 'Акции', icon: 'gift', badge: 'new' }       // текст
+```
+
+Бейдж появляется с упругим «прыжком» и прыгает заново, когда меняется число. Цвета: `badgeBg` и `badgeText` для числа, `accent` для точки.
+
+## Иконки
+
+| Запись | Что это |
+|---|---|
+| `'pin'` | Встроенная иконка. У активного пункта контур сменяется заливкой |
+| `'ms:home'` | Material Symbols Rounded. У активного пункта заливка плавно перетекает |
+| `'ms:home:outlined'`, `'ms:home:sharp'` | Material Symbols другого стиля |
+| `'mi:home'` | Классические Material Icons (заливка) |
+| `'mi:home:outlined'` | Также `round`, `sharp`, `two-tone` |
+| `<MyIcon />` | Любой React-элемент: svg, картинка, иконка из любой библиотеки |
+
+Встроенные: `film`, `ticket`, `pin`, `bell`, `glasses3d`, `clapperboard`, `flame`, `gift`, `card`, `globe`, `sparkles`, `info`, `logout`, `bulb`, `rotate`, `star`, `check`, `chevL`, `chevR`, `popcorn`, `calendar`, `wallet`, `route`, `users`, `more`, `plus`, `search`, `close`, `arrowR`.
+
+Шрифты Material компонент подключает сам с Google Fonts, когда видит `ms:` или `mi:`. Если шрифты уже подключены у вас или Google Fonts недоступен, выключите это: `autoLoadFonts={false}`. Названия иконок — на [fonts.google.com/icons](https://fonts.google.com/icons).
+
+Для своих иконок разный вид активного состояния задаётся через `activeIcon`:
+
+```tsx
+{ id: 'home', label: 'Главная', icon: <HomeOutline />, activeIcon: <HomeFilled /> }
+```
+
+## Язык
+
+`locale` переключает собственные подписи компонента: кнопку «Меню», подпись меню для диктора, подсказки и кнопки поиска, озвучку бейджа-точки.
+
+| `locale` | «Меню» | Поиск | Бейдж-точка |
+|---|---|---|---|
+| `'en'` (по умолчанию) | More | Search | «Parking, new» |
+| `'hy'` | Մենյու | Որոնում | «Կայանատեղի, նոր» |
+| `'ru'` | Меню | Поиск | «Парковка, есть новое» |
+
+```tsx
+<ParzMenu locale="ru" items={items} />
+```
+
+Подписи пунктов и `ariaLabel` кнопок — ваши, переводите их у себя в приложении. Сами строки экспортируются как `LTB_STRINGS`, если нужны где-то ещё.
+
+## Тема
+
+Все поля необязательны. Цвета — любые CSS-цвета, размеры — числа в пикселях.
+
+| Поле | По умолчанию | Что задаёт |
+|---|---|---|
+| `accent` | `#6ee7a0` | Точка-бейдж, кольцо фокуса, обводка активного аватара |
+| `text` / `textActive` | `#8b8b93` / `#fff` | Подписи и иконки |
+| `surfaceTop` / `surfaceBottom` | тёмное стекло | Градиент капсул |
+| `border` | `rgba(255,255,255,.06)` | Тонкая обводка капсул |
+| `bevelTop` / `bevelBottom` | белый 14% / чёрный 40% | Объёмный блик капсул: линия сверху и тень снизу. На светлой теме нижнюю делайте почти прозрачной |
+| `highlightTop` / `highlightBottom` | белый 13% / 5% | Градиент капли |
+| `highlightShadow` | тонкий блик | Тень и блик капли (CSS box-shadow). На светлой теме — мягкая тень снизу |
+| `actionBg` | белый 7% | Фон круглых кнопок |
+| `actionActiveBg` / `actionActiveText` | `#fff` / `#000` | Нажатая круглая кнопка |
+| `actionAccentBg` / `actionAccentText` | `#6ee7a0` / `#04130a` | Акцентная круглая кнопка (`variant: 'accent'`) |
+| `badgeBg` / `badgeText` | `#ff4d5e` / `#fff` | Бейдж с числом |
+| `badgeRing` | `#1d1d21` | Кольцо вокруг бейджа — ставьте цвет панели |
+| `avatarFrom` / `avatarTo` / `avatarText` | зелёный градиент | Аватар |
+| `fontFamily` | `inherit` | Шрифт подписей |
+| `radius` | `999` | Скругление капсул и капли |
+| `padding` | `6` | Отступ внутри капсул |
+| `gap` | `10` | Расстояние между капсулами |
+| `itemPaddingY` | `8` | Высота пунктов |
+| `iconSize` | `22` | Размер иконок |
+| `fontSize` | `11` | Размер подписей |
+| `actionSize` | `50` | Диаметр круглых кнопок |
+| `blur` | `20` | Размытие стекла |
+| `maxWidth` | `540` | Ширина меню на широких экранах |
+| `offset` | `12` | Отступ от края экрана |
+| `itemMinWidth` | `84` | Ширина пункта в меню без кнопок справа |
+| `shadow` | мягкая тень | Тень под капсулами |
+| `headerTop` / `headerMid` | почти чёрный 96% / 82% | Затенение под шапкой на большом экране: сверху и в середине, ниже растворяется |
+| `headerBlur` | `14` | Размытие под шапкой |
+| `searchBg` / `searchBorder` | белый 6% / 8% | Строка поиска: фон и обводка |
+
+То же самое можно задать в CSS — каждое поле это переменная `--ltb-*`:
+
+```css
+.my-bar {
+  --ltb-accent: #ff7a00;
+  --ltb-surface-top: rgba(255, 255, 255, .8);
+  --ltb-surface-bottom: rgba(240, 240, 245, .9);
+  --ltb-text: #6b6b75;
+  --ltb-text-active: #111;
+}
+```
+
+```tsx
+<ParzMenu className="my-bar" items={items} />
+```
+
+## Стекло
+
+Проп `glass` задаёт, насколько прозрачен фон капсул: число от 0 до 100 (процент прозрачности) или готовый пресет. Цвет остаётся из темы (`surfaceTop` / `surfaceBottom`), меняется только прозрачность.
+
+| Пресет | Прозрачность | Размытие | Как выглядит |
+|---|---|---|---|
+| `'solid'` | 0 % | 0 | Сплошная плашка, контент сквозь неё не виден |
+| `'frosted'` | 15 % | 20 px | Матовое стекло — как в CarPark |
+| `'glass'` | 40 % | 16 px | Заметно просвечивает |
+| `'clear'` | 70 % | 10 px | Почти прозрачное, держится на размытии и обводке |
+| `'none'` | 100 % | 0 | Фона нет — только иконки, подписи и капля |
+
+```tsx
+<ParzMenu glass="glass" items={items} />      // пресет
+<ParzMenu glass={55} items={items} />          // 55 % прозрачности, размытие из темы
+```
+
+Пресет задаёт и размытие. Нужно своё размытие — передайте `glass` числом, а размытие задайте в `theme.blur`. Без `glass` прозрачность берётся из цветов темы как есть. Для цветов в формате `hsl()`, `oklch()` и именах вроде `navy` прозрачность не меняется — задавайте их в `#rrggbb` или `rgb()`.
+
+## Анимации
+
+| Поле | По умолчанию | Что задаёт |
+|---|---|---|
+| `lead` | `360` | Время ведущего края капли, мс |
+| `lag` | `660` | Время отстающего края, мс. Чем больше разница с `lead`, тем сильнее капля тянется |
+| `squash` | `0.26` | Насколько капля сплющивается в полёте. `0` — без этого |
+| `overshoot` | `1.35` | Пружинистость: `1` — без перелёта, `1.6` — сильный |
+| `jelly` | `true` | Упругий отклик круглых кнопок и «всплеск» их капсулы |
+| `wave` | `0.035` | Упругая волна всей капсулы с пунктами: при переходе — в сторону хода капли, при возврате из кнопок справа — влево, при повторном нажатии на открытый пункт — от центра. `0` — выключено, `0.08` — сильно |
+| `shift` | `550` | За сколько мс группа справа появляется или прячется, а пункты переезжают по центру |
+
+```tsx
+<ParzMenu motion={{ lead: 280, lag: 820, squash: 0.35 }} items={items} />
+```
+
+При системной настройке «уменьшить движение» капля просто быстро переезжает, без растяжения и упругости.
+
+## Доступность
+
+- Меню — элемент `nav`, активный пункт помечен `aria-current="page"`, круглые кнопки — `aria-pressed`.
+- Бейдж зачитывается вместе с пунктом: «Штрафы, 3», «Новое, есть новое». Формулировку меняет `badgeLabel`.
+- Всё работает с клавиатуры: Tab и Enter, видно кольцо фокуса.
+
+## Чего здесь нет
+
+- Своих сообщений, роутинга и состояния страниц: компонент только показывает меню и сообщает о нажатиях.
+- Перетаскивания пунктов и свайпа между вкладками.
+- Поддержки браузеров без `backdrop-filter`: там капсулы будут без размытия, но с фоном.

package/docs/parz-slider.en.md

@@ -0,0 +1,76 @@
+# Parz Slider & Parz Range
+
+Two Parz UI sliders with one liquid core.
+
+- **`ParzSlider`** — a single value: volume, brightness, size.
+- **`ParzRange`** — an interval with **2 to 5 thumbs** on one track: price “from–to”, working hours with a break, several zones.
+
+How they move:
+
+- **drag** — the thumb grows a little and stretches with the speed of your movement, then rounds back with a soft spring;
+- **tap the track** — the nearest thumb slides over with a light overshoot, the fill catches up;
+- **value bubble** — pops up above the thumb while you drag or focus it;
+- **keyboard** — Tab to a thumb, arrows ±`step`, PageUp/PageDown ±10%, Home/End to the edges;
+- **reduced motion** — with `prefers-reduced-motion` only short plain moves remain.
+
+In `ParzRange` thumbs never jump over each other, and `minDistance` keeps a gap between neighbours.
+
+```tsx
+import { useState } from 'react';
+import { ParzSlider, ParzRange } from '@carparkteam/parz-ui';
+import '@carparkteam/parz-ui/style.css';
+
+const [volume, setVolume] = useState(60);
+<ParzSlider value={volume} onChange={setVolume} label="Volume" formatValue={v => `${v}%`} />
+
+const [price, setPrice] = useState([2000, 7000]);
+<ParzRange value={price} onChange={setPrice} min={0} max={10000} step={500}
+  label="Price" formatValue={v => `$${v}`} onChangeEnd={loadResults} />
+
+// four thumbs: work 9–13, break, work 14–18
+<ParzRange defaultValue={[9, 13, 14, 18]} min={0} max={24} minDistance={1} fill="pairs" formatValue={v => `${v}:00`} />
+```
+
+## Shared props
+
+| Prop | Default | What it does |
+|---|---|---|
+| `min` / `max` / `step` | `0` / `100` / `1` | Bounds and step |
+| `label` | — | Caption above the slider |
+| `showOutput` | `true` if `label` | Current value on the right of the caption |
+| `formatValue` | — | How to print a number, e.g. ``v => `${v} km` `` |
+| `showValue` | `'auto'` | Bubble above the thumb: `'auto'` — while dragging or focused, `'always'`, `'never'` |
+| `marks` | — | `true` — a dot at every step, or a list: `[0, 50, { value: 100, label: 'Max' }]` |
+| `size` | `'md'` | `'sm'` (16 px), `'md'` (20 px), `'lg'` (26 px) or thumb diameter in px |
+| `disabled` | `false` | Turned off and dimmed |
+| `accent` | `#6ee7a0` | Fill color |
+| `trackColor` | `#2a2a30` | Track color. On a light page use something like `#d9dae1` |
+| `thumbColor` | `#fff` | Thumb color |
+| `name` | — | Values are sent with a form as hidden inputs |
+| `className` / `style` | — | On the root element |
+
+## ParzSlider
+
+| Prop | Default | What it does |
+|---|---|---|
+| `value` / `defaultValue` | — / `min` | Value (controlled / uncontrolled) |
+| `onChange` | — | `(value: number) => void` — on every move |
+| `onChangeEnd` | — | `(value: number) => void` — when released or after a key press |
+| `ariaLabel` | — | Name for screen readers when there is no `label` |
+
+## ParzRange
+
+| Prop | Default | What it does |
+|---|---|---|
+| `value` / `defaultValue` | — / 25% and 75% | Values in ascending order, **from 2 to 5**. Extra ones are cut, missing ones are added at `max` |
+| `onChange` | — | `(value: number[]) => void` |
+| `onChangeEnd` | — | `(value: number[]) => void` — good place to load results |
+| `minDistance` | `0` | Minimum gap between neighbouring thumbs |
+| `fill` | `'span'` | `'span'` — fill from the first to the last thumb, `'pairs'` — only pairs 1–2, 3–4 (work — break — work) |
+| `ariaLabels` | — | Screen-reader names for thumbs, e.g. `['From', 'To']` |
+
+The limits are exported too: `RANGE_MIN_THUMBS` (2) and `RANGE_MAX_THUMBS` (5).
+
+## CSS variables
+
+`--pz-sl-accent`, `--pz-sl-track`, `--pz-sl-knob`, `--pz-sl-tip-bg`, `--pz-sl-tip-fg` — on the slider or any parent.

package/docs/parz-slider.hy.md

@@ -0,0 +1,76 @@
+# Parz Slider և Parz Range
+
+Parz UI-ի երկու սահիչ՝ ընդհանուր հեղուկ միջուկով։
+
+- **`ParzSlider`** — մեկ արժեք՝ ձայն, պայծառություն, չափ։
+- **`ParzRange`** — միջակայք, մեկ ուղու վրա **2-ից 5 սահնակ**՝ գին «սկսած–մինչև», աշխատանքային ժամեր ընդմիջումով, մի քանի գոտի։
+
+Ինչպես են շարժվում.
+
+- **քաշել** — սահնակը մի փոքր մեծանում է և ձգվում շարժման արագությանը համապատասխան, հետո մեղմ զսպանակով կլորանում;
+- **սեղմել ուղուն** — մոտակա սահնակը մոտենում է թեթև անցումով, լցումը հասնում է;
+- **արժեքի պղպջակ** — հայտնվում է սահնակի վերևում, երբ այն քաշում են կամ ֆոկուսում է;
+- **ստեղնաշար** — Tab՝ սահնակին, սլաքներ ±`step`, PageUp/PageDown ±10%, Home/End՝ եզրերին;
+- **քիչ շարժում** — `prefers-reduced-motion`-ի դեպքում մնում են միայն կարճ պարզ տեղաշարժեր։
+
+`ParzRange`-ում սահնակները միմյանց վրայով չեն ցատկում, իսկ `minDistance`-ը պահում է բացը հարևանների միջև։
+
+```tsx
+import { useState } from 'react';
+import { ParzSlider, ParzRange } from '@carparkteam/parz-ui';
+import '@carparkteam/parz-ui/style.css';
+
+const [volume, setVolume] = useState(60);
+<ParzSlider value={volume} onChange={setVolume} label="Ձայն" formatValue={v => `${v}%`} />
+
+const [price, setPrice] = useState([2000, 7000]);
+<ParzRange value={price} onChange={setPrice} min={0} max={10000} step={500}
+  label="Գին" formatValue={v => `${v} ֏`} onChangeEnd={loadResults} />
+
+// չորս սահնակ՝ աշխատանք 9–13, ընդմիջում, աշխատանք 14–18
+<ParzRange defaultValue={[9, 13, 14, 18]} min={0} max={24} minDistance={1} fill="pairs" formatValue={v => `${v}:00`} />
+```
+
+## Ընդհանուր props
+
+| Prop | Լռելյայն | Ինչ է անում |
+|---|---|---|
+| `min` / `max` / `step` | `0` / `100` / `1` | Սահմաններ և քայլ |
+| `label` | — | Պիտակ սահիչի վերևում |
+| `showOutput` | `true`, եթե կա `label` | Ընթացիկ արժեքը պիտակի աջ կողմում |
+| `formatValue` | — | Ինչպես ցույց տալ թիվը, օրինակ ``v => `${v} կմ` `` |
+| `showValue` | `'auto'` | Պղպջակ սահնակի վրա՝ `'auto'` — քաշելիս կամ ֆոկուսում, `'always'`, `'never'` |
+| `marks` | — | `true` — կետ ամեն քայլին, կամ ցուցակ՝ `[0, 50, { value: 100, label: 'Max' }]` |
+| `size` | `'md'` | `'sm'` (16 px), `'md'` (20 px), `'lg'` (26 px) կամ սահնակի տրամագիծը px-ով |
+| `disabled` | `false` | Անջատված և խամրած |
+| `accent` | `#6ee7a0` | Լցման գույնը |
+| `trackColor` | `#2a2a30` | Ուղու գույնը։ Բաց էջում՝ օրինակ `#d9dae1` |
+| `thumbColor` | `#fff` | Սահնակի գույնը |
+| `name` | — | Արժեքները ձևի հետ ուղարկվում են թաքնված input-ներով |
+| `className` / `style` | — | Արմատային տարրի վրա |
+
+## ParzSlider
+
+| Prop | Լռելյայն | Ինչ է անում |
+|---|---|---|
+| `value` / `defaultValue` | — / `min` | Արժեք (կառավարվող / չկառավարվող) |
+| `onChange` | — | `(value: number) => void` — ամեն շարժման ժամանակ |
+| `onChangeEnd` | — | `(value: number) => void` — բաց թողնելիս կամ ստեղնը սեղմելուց հետո |
+| `ariaLabel` | — | Անուն էկրանի ընթերցողների համար, եթե `label` չկա |
+
+## ParzRange
+
+| Prop | Լռելյայն | Ինչ է անում |
+|---|---|---|
+| `value` / `defaultValue` | — / 25% և 75% | Արժեքներ աճման կարգով, **2-ից 5**։ Ավելորդները կտրվում են, պակասողները ավելացվում են `max`-ում |
+| `onChange` | — | `(value: number[]) => void` |
+| `onChangeEnd` | — | `(value: number[]) => void` — հարմար է արդյունքները բեռնելու համար |
+| `minDistance` | `0` | Նվազագույն բացը հարևան սահնակների միջև |
+| `fill` | `'span'` | `'span'` — լցում առաջինից մինչև վերջին սահնակը, `'pairs'` — միայն զույգերը 1–2, 3–4 (աշխատանք — ընդմիջում — աշխատանք) |
+| `ariaLabels` | — | Սահնակների անուններ էկրանի ընթերցողների համար, օրինակ `['Սկսած', 'Մինչև']` |
+
+Սահմանները նույնպես արտահանվում են՝ `RANGE_MIN_THUMBS` (2) և `RANGE_MAX_THUMBS` (5)։
+
+## CSS փոփոխականներ
+
+`--pz-sl-accent`, `--pz-sl-track`, `--pz-sl-knob`, `--pz-sl-tip-bg`, `--pz-sl-tip-fg` — սահիչի կամ ցանկացած ծնողի վրա։

package/docs/parz-slider.ru.md

@@ -0,0 +1,76 @@
+# Parz Slider и Parz Range
+
+Два ползунка Parz UI с общим жидким ядром.
+
+- **`ParzSlider`** — одно значение: громкость, яркость, размер.
+- **`ParzRange`** — промежуток, на одной дорожке **от 2 до 5 бегунков**: цена «от и до», рабочие часы с перерывом, несколько зон.
+
+Как двигаются:
+
+- **перетаскивание** — бегунок чуть увеличивается и тянется по скорости движения, потом мягко пружинит обратно в круг;
+- **нажатие на дорожку** — ближайший бегунок подъезжает с лёгким перелётом, заливка догоняет;
+- **пузырёк со значением** — выпрыгивает над бегунком, пока его тянут или он в фокусе;
+- **клавиатура** — Tab на бегунок, стрелки ±`step`, PageUp/PageDown ±10%, Home/End — к краям;
+- **меньше движения** — при `prefers-reduced-motion` остаются только короткие простые сдвиги.
+
+В `ParzRange` бегунки не перепрыгивают друг через друга, а `minDistance` держит зазор между соседями.
+
+```tsx
+import { useState } from 'react';
+import { ParzSlider, ParzRange } from '@carparkteam/parz-ui';
+import '@carparkteam/parz-ui/style.css';
+
+const [volume, setVolume] = useState(60);
+<ParzSlider value={volume} onChange={setVolume} label="Громкость" formatValue={v => `${v}%`} />
+
+const [price, setPrice] = useState([2000, 7000]);
+<ParzRange value={price} onChange={setPrice} min={0} max={10000} step={500}
+  label="Цена" formatValue={v => `${v} ₽`} onChangeEnd={loadResults} />
+
+// четыре бегунка: работа 9–13, перерыв, работа 14–18
+<ParzRange defaultValue={[9, 13, 14, 18]} min={0} max={24} minDistance={1} fill="pairs" formatValue={v => `${v}:00`} />
+```
+
+## Общие пропсы
+
+| Проп | По умолчанию | Что делает |
+|---|---|---|
+| `min` / `max` / `step` | `0` / `100` / `1` | Границы и шаг |
+| `label` | — | Подпись над ползунком |
+| `showOutput` | `true`, если есть `label` | Текущее значение справа от подписи |
+| `formatValue` | — | Как печатать число, например ``v => `${v} км` `` |
+| `showValue` | `'auto'` | Пузырёк над бегунком: `'auto'` — пока тянут или фокус, `'always'`, `'never'` |
+| `marks` | — | `true` — точка на каждом шаге, или список: `[0, 50, { value: 100, label: 'Макс' }]` |
+| `size` | `'md'` | `'sm'` (16 px), `'md'` (20 px), `'lg'` (26 px) или диаметр бегунка в px |
+| `disabled` | `false` | Отключён и приглушён |
+| `accent` | `#6ee7a0` | Цвет заливки |
+| `trackColor` | `#2a2a30` | Цвет дорожки. На светлой странице — например, `#d9dae1` |
+| `thumbColor` | `#fff` | Цвет бегунка |
+| `name` | — | Значения уходят с формой скрытыми input |
+| `className` / `style` | — | На корневом элементе |
+
+## ParzSlider
+
+| Проп | По умолчанию | Что делает |
+|---|---|---|
+| `value` / `defaultValue` | — / `min` | Значение (управляемый / неуправляемый режим) |
+| `onChange` | — | `(value: number) => void` — при каждом движении |
+| `onChangeEnd` | — | `(value: number) => void` — когда отпустили или после нажатия клавиши |
+| `ariaLabel` | — | Имя для экранных дикторов, если нет `label` |
+
+## ParzRange
+
+| Проп | По умолчанию | Что делает |
+|---|---|---|
+| `value` / `defaultValue` | — / 25% и 75% | Значения по возрастанию, **от 2 до 5**. Лишние отбрасываются, недостающие добавляются на `max` |
+| `onChange` | — | `(value: number[]) => void` |
+| `onChangeEnd` | — | `(value: number[]) => void` — удобно загружать результаты здесь |
+| `minDistance` | `0` | Минимальный зазор между соседними бегунками |
+| `fill` | `'span'` | `'span'` — заливка от первого до последнего бегунка, `'pairs'` — только пары 1–2, 3–4 (работа — перерыв — работа) |
+| `ariaLabels` | — | Имена бегунков для экранных дикторов, например `['От', 'До']` |
+
+Ограничения тоже экспортируются: `RANGE_MIN_THUMBS` (2) и `RANGE_MAX_THUMBS` (5).
+
+## CSS-переменные
+
+`--pz-sl-accent`, `--pz-sl-track`, `--pz-sl-knob`, `--pz-sl-tip-bg`, `--pz-sl-tip-fg` — на ползунке или любом родителе.