alacard-ui-components 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# @alacard/ui
+
+Enterprise-grade Angular UI Component Library. Built for scale, modularity, and strict typing.
+
+## ✨ Особенности (Features)
+- 🚀 **Zero Dependencies**: Библиотека не зависит от сторонних UI-китов (Angular Material, Bootstrap и т.д.). Полностью кастомная реализация.
+- 🛡️ **Strict & Type-Safe**: Поддержка строгой типизации TypeScript. Никаких `any`. Полная совместимость с Angular AOT Compiler.
+- ⚡ **Performance**: Использование ChangeDetectionStrategy.OnPush, track by функций в циклах, оптимизированная работа с DOM.
+- ♿ **Accessibility (a11y)**: Focus Traps для модальных окон, навигация с клавиатуры для Select и Dropdown.
+- 🎨 **Design System & Theming**: Управление темами (Светлая/Тёмная) через CSS переменные (Design Tokens), легкая конфигурация цветов и отступов.
+
+## 📦 Установка
+
+```bash
+npm install @alacard/ui
+```
+
+В вашем `angular.json` убедитесь, что стили темы подключены (если они экспортируются как глобальные ассеты), либо импортируйте главный SCSS файл в ваш `styles.scss`:
+```scss
+@import '@alacard/ui/styles/index.scss'; /* Пример пути */
+```
+
+## 🏗 Структура библиотеки
+
+Библиотека разделена на логические домены:
+
+* `@alacard/ui/foundations` — Токены дизайна, миксины, функции, базовые тени и цвета. Отвечает за общую визуальную консистентность.
+* `@alacard/ui/layout` — Структурные компоненты: `UiBox`, `UiGrid`, `UiStack`, `UiContainer`. Отвечают за сетку и позиционирование.
+* `@alacard/ui/primitives` — Основные UI компоненты (Кнопки, Инпуты, Формы, Модалки, Select, Data Table).
+* `@alacard/ui/demo` — Встроенная демо-страница для тестирования и просмотра всех компонентов визуально.
+
+## 💻 Использование компонентов
+
+Пример использования базовых компонентов:
+
+```typescript
+import { Component } from '@angular/core';
+import { UiButton, UiBadge, UiInput, UiFormField } from '@alacard/ui';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [UiButton, UiBadge, UiInput, UiFormField],
+  template: `
+    <ui-form-field label="Имя пользователя">
+        <input uiInput placeholder="Введите имя..." />
+    </ui-form-field>
+
+    <ui-button color="primary" (click)="save()">Сохранить</ui-button>
+    <ui-badge color="success">Успех</ui-badge>
+  `
+})
+export class ExampleComponent {
+    save() {
+        console.log('Saved!');
+    }
+}
+```
+
+## 🎨 Темизация (Theming)
+Библиотека поставляется со встроенной поддержкой тёмной и светлой темы. Глобальный сервис `ThemeService` позволяет переключать темы на лету. Все компоненты используют CSS-переменные (CSS Custom Properties).
+
+Для переопределения брендового цвета приложения:
+```css
+:root {
+    --ui-color-primary: #YourHexColor;
+    --ui-color-primary-soft: rgba(...);
+}
+```
+
+## 📋 Разработка (Development)
+
+Чтобы запустить UI часть и демо страницу в рамках workspace:
+```bash
+npm run start:ui
+```
+Затем перейдите на страницу демо.
+
+Для сборки библиотеки для публикации:
+```bash
+npx ng build ui
+```