374 lines
8.3 KiB
Markdown
374 lines
8.3 KiB
Markdown
# @workshack/ui
|
||
|
||
Workshack UI component library for Angular applications with layout and navigation components.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
npm install @workshack/ui
|
||
```
|
||
|
||
## Components
|
||
|
||
### LayoutModule
|
||
|
||
Import the complete layout module to get access to all layout components:
|
||
|
||
```typescript
|
||
import { LayoutModule } from '@workshack/ui';
|
||
|
||
@Component({
|
||
imports: [LayoutModule],
|
||
template: `
|
||
<ui-layout>
|
||
<ui-menu>
|
||
<ui-menu-item label="Home" icon="home"></ui-menu-item>
|
||
<ui-menu-item label="Settings" icon="settings"></ui-menu-item>
|
||
</ui-menu>
|
||
<ui-content>
|
||
<ui-header label="Page Title">
|
||
<button>Action Button</button>
|
||
</ui-header>
|
||
<!-- Your content here -->
|
||
</ui-content>
|
||
</ui-layout>
|
||
`
|
||
})
|
||
export class AppComponent {}
|
||
```
|
||
|
||
### Layout Components
|
||
|
||
#### LayoutComponent (`<ui-layout>`)
|
||
|
||
**Selector:** `ui-layout`
|
||
**Description:** Root container component that provides the main layout structure.
|
||
|
||
**Usage:**
|
||
```html
|
||
<ui-layout>
|
||
<!-- Menu and content components go here -->
|
||
</ui-layout>
|
||
```
|
||
|
||
**Properties:** None
|
||
**Content Projection:** Accepts any content, typically `ui-menu` and `ui-content`
|
||
|
||
---
|
||
|
||
#### MenuComponent (`<ui-menu>`)
|
||
|
||
**Selector:** `ui-menu`
|
||
**Description:** Vertical sidebar menu container for navigation items.
|
||
|
||
**Usage:**
|
||
```html
|
||
<ui-menu>
|
||
<ui-menu-item label="Dashboard" icon="dashboard"></ui-menu-item>
|
||
<ui-menu-item label="Users" icon="people"></ui-menu-item>
|
||
</ui-menu>
|
||
```
|
||
|
||
**Properties:** None
|
||
**Content Projection:** Accepts `ui-menu-item` components
|
||
**Styling:**
|
||
- Width: 4rem
|
||
- Background: `var(--ui-color-menu-bg, #343a40)`
|
||
- Color: `var(--ui-color-menu-text, #ffffff)`
|
||
|
||
---
|
||
|
||
#### MenuItemComponent (`<ui-menu-item>`)
|
||
|
||
**Selector:** `ui-menu-item`
|
||
**Description:** Individual menu item with icon and label.
|
||
|
||
**Usage:**
|
||
```html
|
||
<ui-menu-item
|
||
label="Dashboard"
|
||
icon="dashboard">
|
||
</ui-menu-item>
|
||
```
|
||
|
||
**Properties:**
|
||
- `label: string` (required) - Text label displayed below the icon
|
||
- `icon: string` (required) - Icon name (uses RemixIcon classes)
|
||
|
||
**Styling:**
|
||
- Size: 4rem × 4rem
|
||
- Hover effect: `rgba(255, 255, 255, 0.1)` background
|
||
- Active state: `#2c2c2c` background
|
||
- Icon size: 1.7rem
|
||
- Label size: 0.6rem
|
||
|
||
---
|
||
|
||
#### ContentComponent (`<ui-content>`)
|
||
|
||
**Selector:** `ui-content`
|
||
**Description:** Main content area container.
|
||
|
||
**Usage:**
|
||
```html
|
||
<ui-content>
|
||
<ui-header label="Page Title"></ui-header>
|
||
<!-- Your page content -->
|
||
</ui-content>
|
||
```
|
||
|
||
**Properties:** None
|
||
**Content Projection:** Accepts any content, typically starts with `ui-header`
|
||
|
||
---
|
||
|
||
#### HeaderComponent (`<ui-header>`)
|
||
|
||
**Selector:** `ui-header`
|
||
**Description:** Page header with title and action buttons.
|
||
|
||
**Usage:**
|
||
```html
|
||
<ui-header label="Dashboard">
|
||
<button class="btn btn-primary">Add New</button>
|
||
<button class="btn btn-secondary">Export</button>
|
||
</ui-header>
|
||
```
|
||
|
||
**Properties:**
|
||
- `label: string` - Page title displayed in the header
|
||
|
||
**Content Projection:** Right-aligned action buttons or other controls
|
||
**Styling:**
|
||
- Padding: 0.6rem
|
||
- Background: `var(--ui-color-menu-bg, #343a40)`
|
||
- Color: `var(--ui-color-menu-text, #ffffff)`
|
||
- Title font size: 1.4rem
|
||
- Title transform: capitalize
|
||
|
||
---
|
||
|
||
### IconComponent (Directive)
|
||
|
||
**Selector:** `[uiIcon]`
|
||
**Description:** Directive for displaying RemixIcon icons.
|
||
|
||
**Usage:**
|
||
```html
|
||
<i uiIcon="home"></i>
|
||
<span uiIcon="settings"></span>
|
||
```
|
||
|
||
**Properties:**
|
||
- `uiIcon: string` - Icon name (RemixIcon class name without 'ri-' prefix)
|
||
|
||
**Features:**
|
||
- Automatically adds appropriate CSS classes
|
||
- Injects SVG content for icons
|
||
- Works with any HTML element
|
||
|
||
## CSS Variables
|
||
|
||
The library uses CSS variables for theming. You can customize colors by defining these variables:
|
||
|
||
```css
|
||
:root {
|
||
--ui-color-menu-bg: #343a40; /* Menu background */
|
||
--ui-color-menu-text: #ffffff; /* Menu text color */
|
||
--ui-color-menu-hover: rgba(255, 255, 255, 0.1); /* Hover effect */
|
||
--ui-color-menu-active: #2c2c2c; /* Active item background */
|
||
--ui-color-icon-primary: #2c3e50; /* Icon color */
|
||
}
|
||
```
|
||
|
||
## Complete Example
|
||
|
||
```typescript
|
||
import { Component } from '@angular/core';
|
||
import { LayoutModule } from '@workshack/ui';
|
||
|
||
@Component({
|
||
selector: 'app-root',
|
||
imports: [LayoutModule],
|
||
template: `
|
||
<ui-layout>
|
||
<ui-menu>
|
||
<ui-menu-item
|
||
label="Dashboard"
|
||
icon="dashboard"
|
||
(click)="navigate('dashboard')">
|
||
</ui-menu-item>
|
||
<ui-menu-item
|
||
label="Users"
|
||
icon="user"
|
||
(click)="navigate('users')">
|
||
</ui-menu-item>
|
||
<ui-menu-item
|
||
label="Settings"
|
||
icon="settings"
|
||
(click)="navigate('settings')">
|
||
</ui-menu-item>
|
||
</ui-menu>
|
||
|
||
<ui-content>
|
||
<ui-header label="Dashboard">
|
||
<button class="btn btn-primary" (click)="addNew()">
|
||
<i uiIcon="add"></i> Add New
|
||
</button>
|
||
<button class="btn btn-secondary" (click)="export()">
|
||
<i uiIcon="download"></i> Export
|
||
</button>
|
||
</ui-header>
|
||
|
||
<div class="content-body">
|
||
<!-- Your page content here -->
|
||
<h2>Welcome to Dashboard</h2>
|
||
<p>This is the main content area.</p>
|
||
</div>
|
||
</ui-content>
|
||
</ui-layout>
|
||
`,
|
||
styles: [`
|
||
.content-body {
|
||
padding: 1rem;
|
||
}
|
||
.btn {
|
||
margin-left: 0.5rem;
|
||
padding: 0.5rem 1rem;
|
||
border: none;
|
||
border-radius: 4px;
|
||
cursor: pointer;
|
||
}
|
||
.btn-primary {
|
||
background: #007bff;
|
||
color: white;
|
||
}
|
||
.btn-secondary {
|
||
background: #6c757d;
|
||
color: white;
|
||
}
|
||
`]
|
||
})
|
||
export class AppComponent {
|
||
navigate(route: string) {
|
||
console.log('Navigate to:', route);
|
||
}
|
||
|
||
addNew() {
|
||
console.log('Add new item');
|
||
}
|
||
|
||
export() {
|
||
console.log('Export data');
|
||
}
|
||
}
|
||
```
|
||
|
||
### Card Components
|
||
|
||
**Selectors:** `ui-card`, `ui-card-title`, `ui-card-menu`, `ui-card-footer`
|
||
**Description:** Zestaw komponentów do tworzenia kart z opcjonalnym nagłówkiem, menu i stopką.
|
||
|
||
**CardComponent (`ui-card`) Properties:**
|
||
- `title?: string` - Tytuł karty wyświetlany w nagłówku
|
||
- `margin: 0.5rem` - Domyślny margin karty
|
||
- Kolory jak ui-menu (--ui-color-menu-bg, --ui-color-menu-text)
|
||
|
||
**Standalone Components:**
|
||
- `ui-card-title` - Tytuł karty z własnymi stylami
|
||
- `ui-card-menu` - Menu/przyciski w nagłówku
|
||
- `ui-card-footer` - Stopka karty z własnymi stylami
|
||
|
||
**Usage:**
|
||
```html
|
||
<!-- Podstawowe użycie -->
|
||
<ui-card title="Tytuł karty">
|
||
<p>Zawartość karty</p>
|
||
</ui-card>
|
||
|
||
<!-- Pełne użycie z wszystkimi slotami -->
|
||
<ui-card title="Statystyki">
|
||
<ui-card-menu>
|
||
<button class="btn btn-sm">Edytuj</button>
|
||
<button class="btn btn-sm">Usuń</button>
|
||
</ui-card-menu>
|
||
|
||
<div class="stats">
|
||
<div class="stat-item">
|
||
<span class="value">123</span>
|
||
<span class="label">Użytkownicy</span>
|
||
</div>
|
||
</div>
|
||
|
||
<ui-card-footer>
|
||
<small class="text-muted">Ostatnia aktualizacja: dziś</small>
|
||
</ui-card-footer>
|
||
</ui-card>
|
||
|
||
<!-- Niestandardowy tytuł -->
|
||
<ui-card>
|
||
<ui-card-title>
|
||
<div class="d-flex align-items-center">
|
||
<i class="icon-chart"></i>
|
||
<span>Raporty sprzedaży</span>
|
||
</div>
|
||
</ui-card-title>
|
||
|
||
<ui-card-menu>
|
||
<span class="text-success">+12%</span>
|
||
</ui-card-menu>
|
||
|
||
<div class="chart-container">
|
||
<!-- wykres -->
|
||
</div>
|
||
</ui-card>
|
||
```
|
||
|
||
**CSS Variables:**
|
||
- `--ui-color-card-bg` - tło karty
|
||
- `--ui-color-card-border` - kolor obramowania
|
||
- `--ui-color-card-title` - kolor tytułu
|
||
- `--ui-color-card-text` - kolor tekstu
|
||
- `--ui-color-card-footer-bg` - tło stopki
|
||
- `--ui-shadow-card` - standardowy cień karty
|
||
- `--ui-shadow-card-hover` - cień przy hover
|
||
|
||
## Development
|
||
|
||
### Building
|
||
```bash
|
||
npm run build:ui
|
||
```
|
||
|
||
### Watching for changes
|
||
```bash
|
||
npm run watch:ui
|
||
```
|
||
|
||
### Testing
|
||
```bash
|
||
npm run test:ui
|
||
```
|
||
|
||
### Publishing
|
||
```bash
|
||
npm run publish:ui
|
||
```
|
||
|
||
## License
|
||
|
||
This library is licensed under a custom license that allows:
|
||
|
||
- **Free use** for non-commercial applications (no revenue, no ads, no paid features)
|
||
- **Commercial use** with attribution requirement - you must credit the library in your app (e.g., on an "About" or "For Developers" page)
|
||
|
||
For full license terms, see the [LICENSE](LICENSE) file.
|
||
|
||
### Attribution Example for Commercial Use
|
||
|
||
```
|
||
This application uses Workshack UI Library
|
||
(https://www.npmjs.com/package/@workshack/ui)
|
||
© 2025 Workshack Team
|
||
```
|