@eagami/ui 1.2.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -170
- package/fesm2022/eagami-ui.mjs +426 -426
- package/fesm2022/eagami-ui.mjs.map +1 -1
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,31 +1,17 @@
|
|
|
1
|
+
<h1 align="center">Eagami UI</h1>
|
|
2
|
+
|
|
1
3
|
<p align="center">
|
|
2
|
-
<img src="
|
|
4
|
+
<img src="assets/logo.png" alt="Eagami UI logo" width="150" height="150" />
|
|
3
5
|
</p>
|
|
4
6
|
|
|
5
7
|
<p align="center">
|
|
6
8
|
<a href="https://www.npmjs.com/package/@eagami/ui"><img src="https://img.shields.io/npm/v/@eagami/ui.svg" alt="npm version" /></a>
|
|
7
|
-
<a href="https://github.com/mwiraszka/eagami
|
|
8
|
-
<a href="https://github.com/mwiraszka/eagami-design-system/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@eagami/ui.svg" alt="license" /></a>
|
|
9
|
+
<a href="https://github.com/mwiraszka/eagami/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@eagami/ui.svg" alt="license" /></a>
|
|
9
10
|
</p>
|
|
10
11
|
|
|
11
|
-
A lightweight, accessible Angular component library built on CSS custom properties,
|
|
12
|
-
|
|
13
|
-
Every component is standalone, signal-based, and fully themed via design tokens (no wrapping modules, complex setup, or runtime style conflicts). Designed with clear APIs, consistent patterns, and comprehensive documentation to make it easy for both developers and AI assistants to integrate in any project.
|
|
12
|
+
A lightweight, accessible Angular component library built on CSS custom properties. Standalone, signal-based, fully themable, and localized in five languages out of the box.
|
|
14
13
|
|
|
15
|
-
**
|
|
16
|
-
|
|
17
|
-
## Features
|
|
18
|
-
|
|
19
|
-
- **Zero configuration**: works immediately after install with sensible defaults
|
|
20
|
-
- **Standalone components**: no `NgModule` boilerplate, just import and use
|
|
21
|
-
- **Signal-based**: built on Angular's modern reactivity primitives (`input()`, `model()`, `output()`, `effect()`)
|
|
22
|
-
- **Full theming via CSS custom properties**: override any design token on `:root` or scope overrides to individual components
|
|
23
|
-
- **Dark mode built in**: automatic via `prefers-color-scheme`, no extra setup
|
|
24
|
-
- **Accessible**: ARIA attributes, keyboard navigation, focus management, and screen reader support throughout
|
|
25
|
-
- **Localized**: built-in component strings ship in English, French, Greek, Polish, and Spanish, switchable at runtime
|
|
26
|
-
- **Form-ready**: `ControlValueAccessor` on every form control (input, textarea, checkbox, switch, radio, dropdown, autocomplete, date picker, slider, code input, segmented)
|
|
27
|
-
- **Tree-shakeable**: only the components you import end up in your bundle
|
|
28
|
-
- **Tiny**: the entire library is **70 KB gzipped**, and only the components you import end up in your bundle
|
|
14
|
+
**Live documentation:** [eagami.com/ui](https://eagami.com/ui)
|
|
29
15
|
|
|
30
16
|
## Installation
|
|
31
17
|
|
|
@@ -33,181 +19,60 @@ Every component is standalone, signal-based, and fully themed via design tokens
|
|
|
33
19
|
npm install @eagami/ui
|
|
34
20
|
# or
|
|
35
21
|
pnpm add @eagami/ui
|
|
22
|
+
# or
|
|
23
|
+
yarn add @eagami/ui
|
|
36
24
|
```
|
|
37
25
|
|
|
38
|
-
Add the global stylesheet to your `angular.json
|
|
26
|
+
Add the global stylesheet to your `angular.json`:
|
|
39
27
|
|
|
40
28
|
```json
|
|
41
29
|
"styles": ["node_modules/@eagami/ui/src/styles/eagami-ui.scss"]
|
|
42
30
|
```
|
|
43
31
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
```html
|
|
47
|
-
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
48
|
-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
|
49
|
-
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;1,9..40,400&family=Syne:wght@400;500;600;700&display=swap" />
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
## Quick start
|
|
32
|
+
See the [Setup](https://eagami.com/ui/setup) page for fonts and your first component import.
|
|
53
33
|
|
|
54
|
-
|
|
55
|
-
import { ButtonComponent } from '@eagami/ui';
|
|
56
|
-
|
|
57
|
-
@Component({
|
|
58
|
-
imports: [ButtonComponent],
|
|
59
|
-
template: `<ea-button variant="primary" (clicked)="save()">Save</ea-button>`,
|
|
60
|
-
})
|
|
61
|
-
export class MyComponent {
|
|
62
|
-
save() { /* ... */ }
|
|
63
|
-
}
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
No modules to register, no providers to configure. Every component works the same way: import it, drop it in your template.
|
|
34
|
+
## Features
|
|
67
35
|
|
|
68
|
-
|
|
36
|
+
- Standalone components; no `NgModule` boilerplate
|
|
37
|
+
- Signal-based APIs (`input()`, `model()`, `output()`)
|
|
38
|
+
- Tree-shakeable; ~70 KB gzipped for the whole library
|
|
39
|
+
- Themed via CSS custom properties on `:root`
|
|
40
|
+
- Dark mode automatic via `prefers-color-scheme`
|
|
41
|
+
- Accessible: ARIA, keyboard, focus management, reduced motion
|
|
42
|
+
- Localized in English, French, Greek, Polish, Spanish
|
|
43
|
+
- `ControlValueAccessor` on every form control
|
|
69
44
|
|
|
70
45
|
## What's included
|
|
71
46
|
|
|
72
|
-
- **Form controls**: Input, Textarea, Checkbox, Switch, Radio, Dropdown, Autocomplete, Date picker, Slider, Code input, Segmented
|
|
47
|
+
- **Form controls**: Input, Textarea, Checkbox, Switch, Radio, Dropdown, Autocomplete, Date picker, Slider, Code input, Segmented, Avatar editor
|
|
73
48
|
- **Overlays**: Dialog, Drawer, Tooltip, Menu, Toast
|
|
74
49
|
- **Navigation**: Tabs, Breadcrumbs, Paginator, Accordion
|
|
75
|
-
- **Display**: Card, Badge, Tag, Alert, Avatar, Skeleton, Spinner, Progress bar, Empty state, Divider, Eagami wordmark
|
|
76
|
-
- **
|
|
77
|
-
- **Specialised**: Avatar editor
|
|
78
|
-
- **Icons**: 52 stroke-based SVG icon components (`<ea-icon-*>`)
|
|
50
|
+
- **Display**: Card, Badge, Tag, Alert, Avatar, Skeleton, Spinner, Progress bar, Empty state, Divider, Eagami wordmark, Data table
|
|
51
|
+
- **Icons**: 100 stroke-based SVG icon components (`<ea-icon-*>`)
|
|
79
52
|
|
|
80
|
-
Full
|
|
53
|
+
Full API and live demos at [eagami.com/ui/components](https://eagami.com/ui/components).
|
|
81
54
|
|
|
82
55
|
## Theming
|
|
83
56
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
```css
|
|
87
|
-
:root {
|
|
88
|
-
--color-primary-600: #2563eb;
|
|
89
|
-
--font-family-sans: 'Inter', sans-serif;
|
|
90
|
-
--radius-md: 0.5rem;
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
Component-level overrides are available where useful:
|
|
95
|
-
|
|
96
|
-
```css
|
|
97
|
-
.my-card {
|
|
98
|
-
--ea-card-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
|
|
99
|
-
--ea-button-font-weight: 600;
|
|
100
|
-
}
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
See [`src/styles/tokens/`](src/styles/tokens/) for the full token reference.
|
|
57
|
+
Every visual property is a CSS custom property on `:root`, so overriding any token retunes the whole library. See [design tokens](https://eagami.com/ui/design-tokens) for the full reference and theming examples.
|
|
104
58
|
|
|
105
59
|
## Internationalization
|
|
106
60
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
Set the locale once at bootstrap with `provideEagamiUi`:
|
|
110
|
-
|
|
111
|
-
```typescript
|
|
112
|
-
import { provideEagamiUi } from '@eagami/ui';
|
|
113
|
-
|
|
114
|
-
bootstrapApplication(AppComponent, {
|
|
115
|
-
providers: [provideEagamiUi({ locale: 'fr-FR' })],
|
|
116
|
-
});
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
Switch it at runtime by injecting `EagamiI18nService`, and every component updates reactively:
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
import { EagamiI18nService } from '@eagami/ui';
|
|
123
|
-
|
|
124
|
-
export class LanguagePicker {
|
|
125
|
-
private readonly i18n = inject(EagamiI18nService);
|
|
126
|
-
setFrench() { this.i18n.setLocale('fr-FR'); }
|
|
127
|
-
}
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Individual strings can still be overridden per instance via component inputs (e.g. `placeholder`, `removeLabel`), or globally through `provideEagamiUi({ messages })`. `DatePickerComponent` also follows the active locale when formatting dates.
|
|
131
|
-
|
|
132
|
-
### French typography for user-supplied text
|
|
133
|
-
|
|
134
|
-
Standard French typography puts a narrow non-breaking space (U+202F, *espace fine insécable*) before `?` `!` `:` `;` and around `«` `»`. Without it the punctuation can wrap onto its own line. The library's built-in French messages already follow this rule, but **user-typed content and other consumer-supplied strings are not auto-transformed** — the components render whatever string they receive.
|
|
135
|
-
|
|
136
|
-
What this means in practice:
|
|
137
|
-
|
|
138
|
-
- **macOS / iOS** with a French keyboard already inserts the correct space automatically. Most other operating systems (Windows, Android, most Linux input methods) just send a regular ASCII space, so typed text can wrap awkwardly.
|
|
139
|
-
- For consumer-supplied strings you want to render correctly, the library exposes an opt-in helper:
|
|
140
|
-
|
|
141
|
-
```typescript
|
|
142
|
-
import { frenchSpacing } from '@eagami/ui';
|
|
143
|
-
|
|
144
|
-
const corrected = frenchSpacing(userInput);
|
|
145
|
-
// 'Lignes par page :' -> 'Lignes par page :'
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
Apply it to prose only (not URLs, CSS, or JSON — `:` and `?` carry non-prose meaning there). It's idempotent and a no-op on text without space-before-punctuation. Also remember to set `<html lang="fr-FR">` so the browser applies locale-aware CSS uppercase rules; the same lang attribute lets screen readers pick the right voice.
|
|
61
|
+
Built-in strings ship in English, French (France), Greek, Polish, and Spanish (Spain), with runtime switching via `EagamiI18nService`. See [internationalization](https://eagami.com/ui/i18n) for setup and per-string overrides.
|
|
149
62
|
|
|
150
63
|
## Framework integration
|
|
151
64
|
|
|
152
|
-
`@eagami/ui` is
|
|
153
|
-
|
|
154
|
-
- **[design-system-flutter.md](design-system-flutter.md)**: Dart `ThemeExtension`, `MaterialApp` wiring, reduced-motion handling, and widget API conventions for Flutter projects
|
|
155
|
-
- **[design-system-react.md](design-system-react.md)**: CSS custom properties, TypeScript constants, and component prop conventions for React projects (plain CSS, CSS Modules, styled-components, emotion, or Tailwind)
|
|
156
|
-
|
|
157
|
-
Both files contain the full token set, mandatory design rules, theme setup, usage patterns, component API conventions, and accessibility requirements. Copy the relevant file into the target project and follow it when building UI.
|
|
158
|
-
|
|
159
|
-
## Peer dependencies
|
|
160
|
-
|
|
161
|
-
| Package | Version |
|
|
162
|
-
|---------|---------|
|
|
163
|
-
| `@angular/common` | `^21.0.0` |
|
|
164
|
-
| `@angular/core` | `^21.0.0` |
|
|
165
|
-
| `@angular/forms` | `^21.0.0` |
|
|
166
|
-
|
|
167
|
-
## Browser support
|
|
168
|
-
|
|
169
|
-
Components are authored for modern evergreen browsers and follow Angular's default [browserslist](https://github.com/browserslist/browserslist) configuration. Specifically:
|
|
170
|
-
|
|
171
|
-
- **Chrome / Edge**: last 2 stable versions
|
|
172
|
-
- **Firefox**: last 2 stable versions, plus the current ESR
|
|
173
|
-
- **Safari**: last 2 stable versions
|
|
174
|
-
- **Modern mobile browsers** (iOS Safari, Chrome Android)
|
|
175
|
-
|
|
176
|
-
The library is published as ES2022. Internet Explorer and pre-Chromium Edge are not supported.
|
|
177
|
-
|
|
178
|
-
### Runtime requirements
|
|
179
|
-
|
|
180
|
-
| Tool | Minimum |
|
|
181
|
-
|------|---------|
|
|
182
|
-
| Node.js | 20.x (for build/dev tooling) |
|
|
183
|
-
| Angular | 21.0 |
|
|
184
|
-
| TypeScript | 5.5 |
|
|
185
|
-
|
|
186
|
-
## Development
|
|
187
|
-
|
|
188
|
-
```bash
|
|
189
|
-
pnpm install # Install dependencies
|
|
190
|
-
pnpm sandbox # Run sandbox dev app on http://localhost:4200
|
|
191
|
-
pnpm storybook # Run Storybook on http://localhost:6006
|
|
192
|
-
pnpm test # Run tests
|
|
193
|
-
pnpm build # Build the library
|
|
194
|
-
pnpm lint # Lint
|
|
195
|
-
```
|
|
196
|
-
|
|
197
|
-
## Icons
|
|
198
|
-
|
|
199
|
-
The icon set is derived from [Feather Icons](https://feathericons.com/) (© Cole Bemis, MIT). Stroke style, dimensions, and most paths match Feather one-for-one. Browse the full set at [eagami.com/ui/icons](https://eagami.com/ui/icons).
|
|
200
|
-
|
|
201
|
-
### Brand icons
|
|
65
|
+
`@eagami/ui` is Angular-only, but its design tokens are framework-agnostic. Copy-and-paste guides for non-Angular targets:
|
|
202
66
|
|
|
203
|
-
|
|
67
|
+
- **[eagami-ui-flutter.md](https://github.com/mwiraszka/eagami/blob/main/eagami-ui-flutter.md)** for Flutter projects
|
|
68
|
+
- **[eagami-ui-react.md](https://github.com/mwiraszka/eagami/blob/main/eagami-ui-react.md)** for React projects
|
|
204
69
|
|
|
205
|
-
|
|
206
|
-
- **GitHub**: [Logos and usage](https://github.com/logos)
|
|
207
|
-
- **Google**: [Sign-in branding guidelines](https://developers.google.com/identity/branding-guidelines)
|
|
208
|
-
- **Microsoft**: [Trademark and brand guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks)
|
|
209
|
-
- **X (Twitter)**: [Brand toolkit](https://about.x.com/en/who-we-are/brand-toolkit)
|
|
70
|
+
## Compatibility
|
|
210
71
|
|
|
211
|
-
|
|
72
|
+
| | |
|
|
73
|
+
|---|---|
|
|
74
|
+
| Angular | `^21.0.0` (peer dep) |
|
|
75
|
+
| Node | `>= 20` for build/dev tooling |
|
|
76
|
+
| Browsers | Last 2 stable versions of Chrome, Edge, Firefox (plus current ESR), Safari |
|
|
212
77
|
|
|
213
|
-
|
|
78
|
+
> **Upgrading from v0.x?** See [MIGRATION.md](MIGRATION.md).
|