poe-svelte-ui-lib 1.9.8 → 1.9.9

package/dist/Accordion/README.md

@@ -2,7 +2,7 @@
 
 ## Описание
 
-Аккордеон - это интерактивный UI-компонент, который позволяет скрывать и отображать содержимое в виде раскрывающегося блока. Компонент предоставляет возможность настройки внешнего вида, размеров, иконок, изображений фона и других параметров через систему пропсов.
+Аккордеон - это UI-компонент, который позволяет скрывать и отображать содержимое в виде раскрывающегося блока. Компонент предоставляет возможность настройки внешнего вида, размеров, иконок, изображений фона и других параметров через систему пропсов.
 
 ## Пропсы
 

package/dist/Button/README.md

@@ -0,0 +1,184 @@
+# Button Component
+
+## Описание
+
+Кнопка - это интерактивный UI-компонент, который предоставляет возможность выполнения действий при клике. Компонент поддерживает настройку внешнего вида, иконок, информационных подсказок, горячих клавиш и другие параметры через систему пропсов.
+
+## Пропсы
+
+| Название       | Тип                                                                                                                                                   | По умолчанию                                              | Описание                                         |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------ |
+| id             | string                                                                                                                                                | crypto.randomUUID()                                       | Уникальный идентификатор компонента              |
+| wrapperClass   | string                                                                                                                                                | ""                                                        | Дополнительные CSS-классы для обертки компонента |
+| componentClass | string                                                                                                                                                | ""                                                        | CSS-классы для стилизации самой кнопки           |
+| disabled       | boolean                                                                                                                                               | false                                                     | Состояние отключения кнопки                      |
+| content        | { name?: string; info?: { text: string; side: "top" \| "bottom" \| "left" \| "right" }; icon?: ConstructorOfATypedSvelteComponent \| string \| null } | { name: "", info: { text: "", side: "top" }, icon: null } | Настройки содержимого кнопки                     |
+| keyBind        | { key?: string; ctrlKey?: boolean; shiftKey?: boolean; altKey?: boolean; metaKey?: boolean; showHint?: boolean }                                      | { showHint: true }                                        | Настройки горячих клавиш для активации кнопки    |
+| onClick        | () => void                                                                                                                                            | undefined                                                 | Обработчик клика по кнопке                       |
+
+### Вложенные типы
+
+#### Content
+
+| Название | Тип                                                            | По умолчанию              | Описание                                                 |
+| -------- | -------------------------------------------------------------- | ------------------------- | -------------------------------------------------------- |
+| name     | string                                                         | ""                        | Текст кнопки                                             |
+| info     | { text: string; side: "top" \| "bottom" \| "left" \| "right" } | { text: "", side: "top" } | Информационная подсказка                                 |
+| icon     | ConstructorOfATypedSvelteComponent \| string \| null           | null                      | Иконка, отображаемая в кнопке (SVG строка или компонент) |
+
+#### Info
+
+| Название | Тип                                    | По умолчанию | Описание                       |
+| -------- | -------------------------------------- | ------------ | ------------------------------ |
+| text     | string                                 | ""           | Текст информационной подсказки |
+| side     | "top" \| "bottom" \| "left" \| "right" | "top"        | Сторона отображения подсказки  |
+
+#### KeyBind
+
+| Название | Тип     | По умолчанию | Описание                                   |
+| -------- | ------- | ------------ | ------------------------------------------ |
+| key      | string  | undefined    | Клавиша для активации                      |
+| ctrlKey  | boolean | undefined    | Требование нажатия Ctrl                    |
+| shiftKey | boolean | undefined    | Требование нажатия Shift                   |
+| altKey   | boolean | undefined    | Требование нажатия Alt                     |
+| metaKey  | boolean | undefined    | Требование нажатия Meta (Cmd на Mac)       |
+| showHint | boolean | true         | Показывать ли подсказку о горячих клавишах |
+
+## События
+
+| Название | Тип        | Описание                                                                |
+| -------- | ---------- | ----------------------------------------------------------------------- |
+| onClick  | () => void | Срабатывает при клике по кнопке или при активации через горячую клавишу |
+
+## Примеры
+
+### Базовое использование
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+
+  const handleClick = () => {
+    console.log("Кнопка нажата!")
+  }
+</script>
+
+<UI.Button content={{ name: "Button 1" }} componentClass="bg-red" onClick={handleClick} />
+```
+
+### Кнопка с информацией и иконкой
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+  import IconGripVerticalDual from "./appIcons/IconGripVerticalDual.svelte"
+
+  const handleClick = () => {
+    console.log("Кнопка с иконкой нажата!")
+  }
+</script>
+
+<UI.Button
+  content={{
+    name: "Button 2",
+    icon: IconGripVerticalDual,
+    info: { text: "Info for Icon Button", side: "right" },
+  }}
+  componentClass="bg-green h-12 rounded-3xl"
+  onClick={handleClick}
+/>
+```
+
+### Отключенная кнопка
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+</script>
+
+<UI.Button content={{ name: "Button 3" }} componentClass="bg-blue" disabled={true} />
+```
+
+### Кнопка только с иконкой
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+  import IconGripHorizontalUp from "./appIcons/IconGripHorizontalUp.svelte"
+
+  const handleClick = () => {
+    console.log("Кнопка с иконкой нажата!")
+  }
+</script>
+
+<div class="flex h-10 items-center justify-around">
+  <UI.Button content={{ icon: IconGripHorizontalUp }} wrapperClass="w-20 h-10" componentClass="bg-purple rounded-full" onClick={handleClick} />
+</div>
+```
+
+## Внутренняя архитектура
+
+### Реактивность
+
+- Переменная `showInfo` управляет видимостью информационной подсказки
+- Переменная `svgSize` вычисляет размеры SVG иконки на основе классов
+- Объект `tooltipConfig` содержит конфигурацию позиционирования подсказок
+
+### Сторы и зависимости
+
+- Используется стор `twMerge` для объединения Tailwind CSS классов
+- Применяется переход `fly` из `svelte/transition` для анимации подсказки
+- Используется `onMount` для подписки и отписки от глобальных событий клавиатуры
+
+### Директивы
+
+- `transition:fly` для анимации появления/скрытия информационной подсказки
+- Обработчики `onmouseenter` и `onmouseleave` для показа/скрытия подсказки
+- Обработчик `onclick` для активации кнопки
+
+### Слоты
+
+- Компонент не использует внешних слотов
+
+## Конструктор свойств (ButtonProps.svelte)
+
+### Описание
+
+Компонент `ButtonProps.svelte` предоставляет визуальный интерфейс для редактирования свойств кнопки. Поддерживает два режима отображения: для конструктора и для редактирования.
+
+### Пропсы конструктора
+
+| Название         | Тип                                                                                                                               | По умолчанию | Описание                                                |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
+| component        | UIComponent & { properties: Partial<IButtonProps> }                                                                               | -            | Объект компонента с его свойствами                      |
+| onPropertyChange | (updates: Partial<{ properties?: string \| object; name?: string; access?: string; eventHandler?: IUIComponentHandler }>) => void | -            | Коллбэк для обновления свойств компонента               |
+| forConstructor   | boolean                                                                                                                           | true         | Режим отображения (для конструктора или редактирования) |
+
+### Особенности конструктора
+
+- Предоставляет визуальные элементы управления для всех доступных свойств
+- Включает модальное окно для выбора иконок из библиотеки
+- Поддерживает настройку обработчика событий и аргументов
+- Имеет различные наборы полей в зависимости от режима (`forConstructor`)
+- Использует систему локализации через `$t('constructor.props.*')`
+- Поддерживает валидацию вводимых данных через регулярные выражения
+
+## Заметки
+
+### Адаптивность
+
+- Компонент использует Tailwind CSS для адаптивного дизайна
+- Используются относительные единицы измерения для обеспечения масштабируемости
+- Подсказки автоматически позиционируются в зависимости от стороны отображения
+
+### Ограничения
+
+- При использовании только иконки (без текста) кнопка становится прозрачной без фона
+- Горячие клавиши регистрируются глобально и могут конфликтовать с другими компонентами
+- Подсказки не поддерживают HTML-разметку, отображают только текст
+
+### Производительность
+
+- Компонент использует оптимизации Svelte для минимизации перерисовок
+- Обработчики клавиатуры удаляются при размонтировании компонента
+- Используется эффективное объединение классов через `twMerge`

package/dist/Carousel/README.md

@@ -0,0 +1,147 @@
+# Carousel Component
+
+## Описание
+
+Карусель - это интерактивный UI-компонент, который позволяет просматривать контент в виде прокручиваемой ленты с возможностью навигации по стрелкам.
+
+## Пропсы
+
+| Название     | Тип                               | По умолчанию                     | Описание                                                    |
+| ------------ | --------------------------------- | -------------------------------- | ----------------------------------------------------------- |
+| id           | string                            | crypto.randomUUID()              | Уникальный идентификатор компонента                         |
+| wrapperClass | string                            | ""                               | Дополнительные CSS-классы для обертки компонента            |
+| label        | { name?: string; class?: string } | { name: "", class: "text-left" } | Настройки заголовка карусели                                |
+| scrollValue  | number                            | 200                              | Значение прокрутки при нажатии на стрелки (в пикселях)      |
+| children     | Snippet                           | undefined                        | Слот для содержимого, которое будет отображаться в карусели |
+
+### Вложенные типы
+
+#### Label
+
+| Название | Тип    | По умолчанию | Описание                                   |
+| -------- | ------ | ------------ | ------------------------------------------ |
+| name     | string | ""           | Текст заголовка карусели                   |
+| class    | string | "text-left"  | CSS-классы для стилизации текста заголовка |
+
+## События
+
+Компонент не генерирует специфические события.
+
+## Примеры
+
+### Базовое использование
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+</script>
+
+<UI.Carousel scrollValue={200}>
+  <div class="w-90 min-w-90 h-20 bg-white p-2">
+    <div class="mr-2 flex flex-col items-end">
+      <h5 class="flex items-center whitespace-nowrap">COIV-REQE-J1U9-VCS7 |</h5>
+      <p class="flex w-fit text-sm whitespace-nowrap gap-0.5">10.00.000-00_00007C9E0000BDE300000718:B2</p>
+    </div>
+  </div>
+  <div class="w-90 min-w-90 h-20 bg-white p-2">
+    <div class="mr-2 flex flex-col items-end">
+      <h5 class="flex items-center whitespace-nowrap">COIV-REQE-J1U9-VCS7 |</h5>
+      <p class="flex w-fit text-sm whitespace-nowrap gap-0.5">10.00.000-00_00007C9E0000BDE300000718:B2</p>
+    </div>
+  </div>
+  <div class="w-90 min-w-90 h-20 bg-white p-2">
+    <div class="mr-2 flex flex-col items-end">
+      <h5 class="flex items-center whitespace-nowrap">COIV-REQE-J1U9-VCS7 |</h5>
+      <p class="flex w-fit text-sm whitespace-nowrap gap-0.5">10.00.000-00_00007C9E0000BDE300000718:B2</p>
+    </div>
+  </div>
+</UI.Carousel>
+```
+
+### С заголовком
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+</script>
+
+<UI.Carousel label={{ name: "Карусель с заголовком" }} scrollValue={300}>
+  <div class="w-80 min-w-80 h-24 bg-blue-100 p-3 rounded-lg">
+    <p>Элемент 1</p>
+  </div>
+  <div class="w-80 min-w-80 h-24 bg-green-100 p-3 rounded-lg">
+    <p>Элемент 2</p>
+  </div>
+  <div class="w-80 min-w-80 h-24 bg-yellow-100 p-3 rounded-lg">
+    <p>Элемент 3</p>
+  </div>
+  <div class="w-80 min-w-80 h-24 bg-red-100 p-3 rounded-lg">
+    <p>Элемент 4</p>
+  </div>
+</UI.Carousel>
+```
+
+### С настраиваемым классом обертки
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+</script>
+
+<UI.Carousel wrapperClass="my-4 mx-auto max-w-4xl" scrollValue={150}>
+  <div class="w-72 min-w-72 h-16 bg-purple-100 p-2 rounded-md">
+    <p>Контент 1</p>
+  </div>
+  <div class="w-72 min-w-72 h-16 bg-pink-100 p-2 rounded-md">
+    <p>Контент 2</p>
+  </div>
+  <div class="w-72 min-w-72 h-16 bg-indigo-100 p-2 rounded-md">
+    <p>Контент 3</p>
+  </div>
+</UI.Carousel>
+```
+
+## Внутренняя архитектура
+
+### Реактивность
+
+- Переменная `carouselRef` хранит ссылку на DOM-элемент карусели
+- Переменная `isAtStart` отслеживает, находится ли карусель в начале прокрутки
+- Переменная `isAtEnd` отслеживает, находится ли карусель в конце прокрутки
+- Функция `updateScrollState` обновляет состояния `isAtStart` и `isAtEnd` при прокрутке
+
+### Сторы и зависимости
+
+- Используется стор `twMerge` для объединения Tailwind CSS классов
+- Применяется переход `slide` из `svelte/transition` для анимации стрелок навигации
+- Используется `ResizeObserver` для отслеживания изменений размера
+
+### Директивы
+
+- `bind:this={carouselRef}` для получения ссылки на элемент карусели
+- `transition:slide` для анимации стрелок навигации
+- `$effect` для установки и очистки обработчиков событий
+
+### Слоты
+
+- `children` - слот для содержимого, которое отображается внутри карусели
+
+## Заметки
+
+### Адаптивность
+
+- Компонент использует Tailwind CSS для адаптивного дизайна
+- Стрелки навигации автоматически скрываются при достижении начала или конца карусели
+- Используются относительные единицы измерения для обеспечения масштабируемости
+
+### Ограничения
+
+- Для корректного отображения элементы внутри карусели должны иметь фиксированную ширину
+- Компонент не поддерживает вертикальную прокрутку
+- Значение `scrollValue` влияет на величину прокрутки при нажатии стрелок
+
+### Производительность
+
+- Компонент использует оптимизации Svelte для минимизации перерисовок
+- Обработчики событий и `ResizeObserver` корректно удаляются при размонтировании
+- Используется эффективное объединение классов через `twMerge`

package/dist/ColorPicker/README.md

@@ -0,0 +1,141 @@
+# ColorPicker Component
+
+## Описание
+
+Палитра - это интерактивный UI-компонент, который позволяет выбирать цвета с помощью HSV-палитры и настройки яркости. Компонент поддерживает два режима работы: цветовой (HSV) и белый (градации серого), а также предоставляет превью цвета, его RGB и HEX значения.
+
+## Пропсы
+
+| Название     | Тип                               | По умолчанию            | Описание                                                         |
+| ------------ | --------------------------------- | ----------------------- | ---------------------------------------------------------------- |
+| id           | string                            | crypto.randomUUID()     | Уникальный идентификатор компонента                              |
+| readonly     | boolean                           | false                   | Режим только для чтения (без возможности изменения цвета)        |
+| wrapperClass | string                            | ""                      | Дополнительные CSS-классы для обертки компонента                 |
+| label        | { name?: string; class?: string } | { name: "", class: "" } | Настройки заголовка компонента                                   |
+| value        | [number, number, number]          | [0, 0, 0]               | Начальное значение цвета в формате RGB (массив из 3 чисел 0-255) |
+| onChange     | () => void                        | () => {}                | Обработчик изменения цвета                                       |
+
+### Вложенные типы
+
+#### Label
+
+| Название | Тип    | По умолчанию | Описание                                   |
+| -------- | ------ | ------------ | ------------------------------------------ |
+| name     | string | ""           | Текст заголовка компонента                 |
+| class    | string | ""           | CSS-классы для стилизации текста заголовка |
+
+## События
+
+| Название | Тип                                | Описание                                                      |
+| -------- | ---------------------------------- | ------------------------------------------------------------- |
+| onChange | ([number, number, number]) => void | Срабатывает при изменении цвета, передает массив RGB значений |
+
+## Примеры
+
+### Базовое использование
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+
+  let selectedColor = [186, 25, 255]
+
+  const handleColorChange = (newColor) => {
+    selectedColor = newColor
+    console.log("Новый цвет:", newColor)
+  }
+</script>
+
+<UI.ColorPicker label={{ name: "Выбор цвета из палитры" }} bind:value={selectedColor} onChange={handleColorChange} />
+```
+
+### С начальным значением
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+
+  const handleColorChange = (newColor) => {
+    console.log("Цвет изменен:", newColor)
+  }
+</script>
+
+<UI.ColorPicker value={[255, 100, 50]} onChange={handleColorChange} />
+```
+
+### Только для чтения
+
+```svelte
+<script>
+  import * as UI from "poe-svelte-ui-lib"
+</script>
+
+<UI.ColorPicker value={[0, 255, 128]} readonly={true} label={{ name: "Просмотр цвета" }} />
+```
+
+## Внутренняя архитектура
+
+### Реактивность
+
+- Переменная `hsv` хранит текущее значение цвета в формате HSV
+- Переменные `huePointer`, `brightnessPointer` и `whiteValue` отслеживают положение слайдеров
+- Переменная `mode` определяет текущий режим (hsv или white)
+- Функция `hsvToRgb` конвертирует HSV в RGB формат
+- `$effect` синхронизирует входное значение RGB с внутренним состоянием HSV
+
+### Сторы и зависимости
+
+- Используется стор `twMerge` для объединения Tailwind CSS классов
+- Используются математические функции для конвертации цветовых пространств
+
+### Директивы
+
+- `bind:this` для получения ссылок на DOM-элементы
+- Обработчики `onmousedown` для перетаскивания слайдеров
+- `$derived` для вычисления цвета превью и HEX значения
+
+### Слоты
+
+- Компонент не использует внешних слотов
+
+## Конструктор свойств (ColorPickerProps.svelte)
+
+### Описание
+
+Компонент `ColorPickerProps.svelte` предоставляет визуальный интерфейс для редактирования свойств компонента выбора цвета. Поддерживает два режима отображения: для конструктора и для редактирования.
+
+### Пропсы конструктора
+
+| Название         | Тип                                                                                                                               | По умолчанию | Описание                                                |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------- |
+| component        | UIComponent & { properties: Partial<IColorPickerProps> }                                                                          | -            | Объект компонента с его свойствами                      |
+| onPropertyChange | (updates: Partial<{ properties?: string \| object; name?: string; access?: string; eventHandler?: IUIComponentHandler }>) => void | -            | Коллбэк для обновления свойств компонента               |
+| forConstructor   | boolean                                                                                                                           | true         | Режим отображения (для конструктора или редактирования) |
+
+### Особенности конструктора
+
+- Предоставляет визуальные элементы управления для всех доступных свойств
+- Поддерживает настройку начального цвета через три числовых поля (RGB)
+- Использует общие сниппеты для настройки различных параметров
+- Имеет различные наборы полей в зависимости от режима (`forConstructor`)
+- Использует систему локализации через `$t('constructor.props.*')`
+
+## Заметки
+
+### Адаптивность
+
+- Компонент использует Tailwind CSS для адаптивного дизайна
+- Превью цвета автоматически изменяет цвет текста для лучшей читаемости
+- Используются относительные единицы измерения для обеспечения масштабируемости
+
+### Ограничения
+
+- Входное значение `value` должно быть массивом из 3 чисел в диапазоне 0-255
+- Компонент автоматически определяет режим (HSV/белый) на основе входного значения
+- При работе в режиме белого цвета все три компонента RGB имеют одинаковое значение
+
+### Производительность
+
+- Компонент использует оптимизации Svelte для минимизации перерисовок
+- Вычисления цветовых преобразований происходят только при необходимости
+- Используется эффективное объединение классов через `twMerge`

package/dist/ComponentExample.svelte

@@ -7,25 +7,28 @@
     component,
     componentProps,
     examples,
+    props,
     codeText,
     forConstructor = $bindable(),
-  }: { component: Snippet; componentProps: Snippet; examples?: Snippet; codeText: string; forConstructor: boolean } = $props()
+  }: { component: Snippet; componentProps: Snippet; examples?: Snippet; props?: Snippet; codeText: string; forConstructor: boolean } = $props()
 
   let isCopied = $state(false)
   let snippetOptions = [
     { id: crypto.randomUUID(), value: "overview", name: $t("library.overview") },
     { id: crypto.randomUUID(), value: "examples", name: $t("library.examples") },
+    { id: crypto.randomUUID(), value: "props", name: $t("library.props") },
   ]
 
   let mainSnippet: string | undefined = $state("overview")
 
   const renderCurrentSnippet = () => {
     if (mainSnippet === "examples" && examples) return examples
+    if (mainSnippet === "props" && props) return props
     else return overview
   }
 </script>
 
-{#if examples}
+<div class="flex flex-col">
   <Select
     wrapperClass="w-1/2 mx-auto mb-3"
     type="buttons"
@@ -33,8 +36,10 @@
     value={snippetOptions.find((o) => o.value == mainSnippet)}
     onUpdate={(value) => (mainSnippet = (value as IOption<string>).value)}
   />
-{/if}
-{@render renderCurrentSnippet()()}
+  <div class="flex-1 whitespace-pre">
+    {@render renderCurrentSnippet()()}
+  </div>
+</div>
 
 {#snippet overview()}
   <div class="flex w-full h-[calc(100vh-9rem)] flex-col">
@@ -53,7 +58,7 @@
       {@render componentProps()}
       <div class="relative mt-3">
         <button
-          class="absolute top-2 right-3 flex cursor-pointer border-none bg-transparent"
+          class="absolute top-9 right-3 flex cursor-pointer border-none bg-transparent"
           onclick={(e) => {
             e.preventDefault()
             navigator.clipboard.writeText(codeText)
@@ -82,8 +87,7 @@
             {/if}
           </div>
         </button>
-        <pre class="overflow-x-auto">{codeText}
-  </pre>
+        <pre class="overflow-x-auto">{codeText}</pre>
       </div>
     </div>
   </div>

package/dist/ComponentExample.svelte.d.ts

@@ -3,6 +3,7 @@ type $$ComponentProps = {
     component: Snippet;
     componentProps: Snippet;
     examples?: Snippet;
+    props?: Snippet;
     codeText: string;
     forConstructor: boolean;
 };