@cyber-harbour/ui 2.2.43 → 3.0.0-fix-button-focus-visible.0

package/README.md

@@ -1,301 +1,211 @@
-# Початок роботи з Cyber Harbor UI Kit
+# Cyber Harbour UI Kit
 
-## Розробка
+React UI component library built with Tailwind CSS 4, class-variance-authority, and a custom Material-style icon set.
 
-### Встановлення
+## Installation
 
 ```bash
-npm install
+npm install @cyber-harbour/ui
 ```
 
-### Збірка бібліотеки
-
-Бібліотека збирається за допомогою tsup, що забезпечує оптимізовані збірки для форматів ESM та CommonJS.
+### Peer dependencies
 
 ```bash
-# Розробка з режимом відстеження
-npm run dev
-
-# Продакшн збірка
-npm run build
-
-# Збірка без мінімізації
-npm run build:dev
-
-# Перевірка типів без збірки
-npm run type-check
+npm install tailwindcss react-tiny-popover
 ```
 
-### Результат збірки
+FileViewer additionally requires: `react-pdf`, `d3`, `date-fns`, `@codemirror/lang-*`, `@uiw/react-codemirror`.
 
-При збірці бібліотеки в папці `dist` генерується наступне:
+## Usage
 
-- ESM модулі (`.mjs` файли)
-- CommonJS модулі (`.js` файли)
-- TypeScript файли декларацій (`.d.ts` та `.d.mts`)
-- Source maps
+### Import styles
 
-### Storybook
+The library exports source Tailwind CSS (with `@theme` tokens, not compiled output). Your project must have its own Tailwind CSS 4 pipeline to compile it.
 
-Ви можете запустити Storybook для розробки та тестування компонентів:
+See [Vite SPA](#vite-spa-react) or [Next.js](#nextjs) setup sections below for full configuration.
 
-```bash
-npm run storybook
-```
-
-Для збірки Storybook:
+### Import components
 
-```bash
-npm run build-storybook
+```tsx
+import { Button2, Panel, TextInput2 } from '@cyber-harbour/ui';
+import { SearchIcon, ChevronDownIcon } from '@cyber-harbour/ui/Icons2';
+import { cn, useEscapeLayer, useOutclickLayer } from '@cyber-harbour/ui/utils';
 ```
 
-## Оптимізації збірки
-
-Проект використовує різні оптимізації для ефективної збірки:
-
-### Продакшн режим
-
-- Мінімізація вихідних файлів
-- Tree shaking для видалення невикористаного коду
-- Видалення console logs
-- Source maps для налагодження
-
-### Режим розробки
-
-- Режим відстеження для автоматичної перебудови при змінах
-- Вбудовані source maps для легшого налагодження
-- Без мінімізації для швидшої збірки
-- Без генерації типів для швидкості
+| Subpath | Contents |
+|---|---|
+| `@cyber-harbour/ui` | Components |
+| `@cyber-harbour/ui/Icons2` | Custom Material-style SVG icons |
+| `@cyber-harbour/ui/utils` | `cn`, hooks, `getFilesFromDataTransfer` |
+| `@cyber-harbour/ui/styles` | Source Tailwind CSS with custom theme (requires consumer Tailwind pipeline) |
 
-## Інструмент перемикання UI бібліотеки
+## Development
 
-Цей інструмент дозволяє легко перемикатися між локальною версією UI бібліотеки та версією з NPM.
-
-### Використання
-
-#### Варіант 1: Через npx (рекомендований)
+### Setup
 
 ```bash
-npx @cyber-harbour/ui switch-ui-lib
-```
-
-#### Варіант 2: Через npm скрипт
-
-Додайте скрипт в package.json вашого проекту:
-
-```json
-{
-  "scripts": {
-    "switch-ui": "npx @cyber-harbour/ui switch-ui-lib"
-  }
-}
+npm install
 ```
 
-Потім запускайте:
+### Scripts
 
 ```bash
-npm run switch-ui
+npm run dev            # Watch mode
+npm run build          # Production build
+npm run build:dev      # Dev build (no minification)
+npm run type:check     # Type check
+npm run test           # Run tests
+npm run storybook      # Start Storybook
+npm run build-storybook
 ```
 
-### Налаштування
+### Build output
 
-#### Змінні середовища
+The `dist` folder contains:
 
-Створіть файл `.env` або `.env.local` в корені вашого проекту:
+- ESM modules (`.mjs`)
+- CommonJS modules (`.js`)
+- TypeScript declarations (`.d.ts`, `.d.mts`)
+- Source maps
 
-```bash
-UI_LIBRARY_PATH=/path/to/your/ui-kit
-```
+## Integration
 
-Якщо змінна не встановлена, скрипт спробує знайти UI бібліотеку в папці `ui-kit` поруч з вашим проектом.
+The library uses **Tailwind CSS 4** with CSS-based configuration. Styles are shipped as a prebuilt CSS file with custom color palette, shadows, and z-index tokens.
 
-#### Структура проектів
+### Dark mode
 
-Рекомендована структура:
+Dark mode uses the `dark` CSS class. Add `class="dark"` to a parent element:
 
+```html
+<html class="dark">
 ```
-projects/
-├── ui-kit/          # UI бібліотека
-├── my-app/          # Ваш проект
-└── another-app/     # Інший проект
-```
-
-### Що робить скрипт
-
-#### Локальна версія
-
-- Видаляє NPM версію пакету
-- Створює npm link для React та React DOM
-- Створює глобальний link для UI бібліотеки
-- Підключає локальну версію через npm link
-
-#### NPM версія
-
-- Видаляє всі npm links
-- Встановлює останню версію з NPM
-
-### Залежності
 
-Скрипт потребує:
+Components automatically adapt to dark mode.
 
-- `prompts` - для інтерактивного вибору
-- `dotenv` - для читання змінних середовища (опційно)
+### Vite SPA (React)
 
-Ці пакети автоматично встановлюються разом з UI бібліотекою.
-
-### Усунення несправностей
-
-Відсутній лінк на бібліотеку після першого завантаження. Запустіть
+1. Install dependencies:
 
 ```bash
-npm link
+npm install @tailwindcss/vite tailwindcss
 ```
 
----
-
-# 🔹 Інструкція інтеграції UI-kit у Next.js з Tailwind
+2. Add the Tailwind plugin to `vite.config.ts`:
 
-Цей UI-kit побудований на **TailwindCSS** і постачається з власною конфігурацією (`tailwind.config.js`).
-Щоб уникнути конфліктів і дозволити кастомізацію у проєкті, потрібно **мерджити** конфіг UI-kit із конфігом Next.js.
+```ts
+import tailwindcss from '@tailwindcss/vite';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
 
----
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
 
-## 1. Встановіть залежності
+3. Import library styles in your global CSS (`src/index.css`):
 
-У вашому Next.js-проєкті мають бути встановлені:
+```css
+@import 'tailwindcss';
+@import '@cyber-harbour/ui/styles';
 
-```bash
-pnpm add tailwindcss postcss autoprefixer
+@source "../node_modules/@cyber-harbour/ui/dist";
 ```
 
----
-
-## 2. Створіть `tailwind.config.js` у Next.js
+### Next.js
 
-У корені вашого Next.js-проєкту створіть файл `tailwind.config.js` і підключіть конфіг із UI-kit.
-Ми будемо мерджити конфіги за допомогою `lodash.merge`:
+1. Install dependencies:
 
 ```bash
-pnpm add lodash.merge
+npm install @tailwindcss/postcss tailwindcss
 ```
 
-**`tailwind.config.js`**
+2. Configure PostCSS in `postcss.config.mjs`:
 
 ```js
-const merge = require('lodash.merge');
-const uiKitConfig = require('ui-kit/tailwind.config.js'); // шлях до UI-kit пакета
-
-module.exports = merge({}, uiKitConfig, {
-  content: [
-    './pages/**/*.{js,ts,jsx,tsx}',
-    './components/**/*.{js,ts,tsx}',
-    './app/**/*.{js,ts,jsx,tsx}', // якщо використовуєте app router
-    './node_modules/@cyber-harbour/ui/dist/**/*.{js,mjs', // важливо: UI-kit компоненти
-  ],
-  theme: {
-    extend: {
-      colors: {
-        accent: '#f59e0b', // локальні кольори вашого проєкту
-      },
-    },
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
   },
-});
+};
 ```
 
----
-
-## 3. Підключіть Tailwind у глобальні стилі
-
-У вашому Next.js проєкті додайте у `globals.css` (або `app/globals.css`):
+3. Import library styles in your global CSS (`app/globals.css`):
 
 ```css
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
-
----
+@import 'tailwindcss';
+@import '@cyber-harbour/ui/styles';
 
-## 4. Використання компонентів із UI-kit
+@source "../node_modules/@cyber-harbour/ui/dist";
+```
 
-Тепер ви можете імпортувати і використовувати компоненти з UI-kit у будь-яких файлах вашого Next.js-проєкту:
+### Example
 
 ```tsx
-import { Button } from 'ui-kit';
+import { Button2, Panel } from '@cyber-harbour/ui';
+import { SearchIcon } from '@cyber-harbour/ui/Icons2';
 
 export default function Page() {
   return (
-    <div className="p-6">
-      <Button variant="primary">Клікни мене</Button>
-    </div>
+    <Panel as="section" className="p-6">
+      <Button2 type="primary" leftIcon={<SearchIcon />}>
+        Search
+      </Button2>
+    </Panel>
   );
 }
 ```
 
----
-
-## 5. Кастомізація теми
+## FileViewer configuration
 
-Якщо потрібно змінити кольори, spacing чи інші токени —
-додавайте їх у секцію `theme.extend` вашого `tailwind.config.js`.
+PDF preview requires copying the pdfjs-dist worker.
 
-⚡️ Вони автоматично поєднаються з токенами з UI-kit.
+### Auto copy
 
----
+Add the command to your `postinstall` script in `package.json` so the worker is copied automatically after every install:
 
-## 6. Альтернатива підключення
-
-Додайте до вашого головного CSS файлу або entry point:
-
-```css
-/* Імпорт скомпільованих Tailwind стилів з бібліотеки */
-@import '@cyber-harbour/ui/styles';
-```
-
-Або в JS/TS файлі:
-
-```js
-import '@cyber-harbour/ui/styles';
+```json
+{
+  "scripts": {
+    "postinstall": "npx @cyber-harbour/ui copy-pdfjs"
+  }
+}
 ```
 
----
-
-## 7. FileViewer configuration
-
-Для роботи перегляду PDF потрібно скопіювати worker pdfjs-dist
-
-### Автоматичне копіювання
+Or run it manually:
 
 ```bash
 npx @cyber-harbour/ui copy-pdfjs
 ```
 
-### Кастомна папка для worker'ів
+### Custom worker directory
 
 ```bash
 UI_LIBRARY_WORKERS_DIR=public/assets npx @cyber-harbour/ui copy-pdfjs
 ```
 
-### Вирішення проблем
+## Switch UI library tool
 
-Якщо виникає помилка про відсутність PDF worker'а:
+Switch between local and NPM versions of the library during development.
 
-1. **Встановіть pdfjs-dist** у вашому проекті:
+```bash
+npx @cyber-harbour/ui switch-ui-lib
+```
 
-   ```bash
-   npm install pdfjs-dist
-   ```
+### Setup
 
-2. **Або встановіть як peer dependency** та запустіть скрипт:
+Set the path to your local UI kit via `.env` or `.env.local`:
+
+```bash
+UI_LIBRARY_PATH=/path/to/your/ui-kit
+```
 
-   ```bash
-   npm install --save-peer pdfjs-dist
-   npx @cyber-harbour/ui copy-pdfjs
-   ```
+If not set, the script looks for `ui-kit` folder next to your project.
 
-3. **Перевірте структуру проекту**: скрипт шукає worker у наступних місцях:
-   - `node_modules/pdfjs-dist/build/pdf.worker.min.mjs`
-   - `node_modules/@cyber-harbour/ui/node_modules/pdfjs-dist/build/pdf.worker.min.mjs`
-   - Інші можливі локації
+### Recommended project structure
 
-Скрипт автоматично знайде правильну локацію та скопіює worker до папки `public/workers/`.
+```
+projects/
+  ui-kit/          # This library
+  my-app/          # Your project
+  another-app/     # Another project
+```