@edsis/angular 0.0.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 ADDED
@@ -0,0 +1,227 @@
1
+ # @edsis/angular
2
+
3
+ Reusable Angular UI library for themes, navigation/layout primitives, and icons.
4
+
5
+ ## Publish Surface
6
+
7
+ Official package imports after publish are:
8
+
9
+ - `@edsis/angular` for all UI exports and shared helpers
10
+ - `@edsis/angular/styles/main.css` for the shared stylesheet
11
+
12
+ Domain routes, auth helpers, and generated API clients live in `@edsis/library`.
13
+
14
+ Category-style imports such as `@edsis/angular/components` or `@edsis/angular/themes` are not published secondary entry points. Those paths only work inside this monorepo because the workspace `tsconfig.json` defines development aliases.
15
+
16
+ ## Installation
17
+
18
+ The package is published publicly to npm.
19
+
20
+ ```bash
21
+ npm install @edsis/angular
22
+ ```
23
+
24
+ Install the companion domain package when you also need auth, routes, or generated API clients:
25
+
26
+ ```bash
27
+ npm install @edsis/library
28
+ ```
29
+
30
+ Peer dependencies expected by the published package:
31
+
32
+ - Angular 21 (`@angular/core`, `@angular/common`, `@angular/forms`, `@angular/router`, `@angular/cdk`, `@angular/material`, `@angular/animations`)
33
+
34
+ ## Styles
35
+
36
+ Import the shared stylesheet in your application:
37
+
38
+ ```css
39
+ @import '@edsis/angular/styles/main.css';
40
+ ```
41
+
42
+ Or register it in `angular.json`:
43
+
44
+ ```json
45
+ {
46
+ "styles": ["node_modules/@edsis/angular/styles/main.css", "src/styles.css"]
47
+ }
48
+ ```
49
+
50
+ ## Production Usage
51
+
52
+ ```ts
53
+ import { Component, inject } from '@angular/core';
54
+ import { LucideIcon, ThemeService, type ColorScheme } from '@edsis/angular';
55
+
56
+ @Component({
57
+ selector: 'app-root',
58
+ imports: [LucideIcon],
59
+ template: `
60
+ <icon>heart</icon>
61
+ <button type="button" (click)="toggleTheme()">Toggle theme</button>
62
+ `,
63
+ })
64
+ export class AppComponent {
65
+ private readonly themeService = inject(ThemeService);
66
+
67
+ toggleTheme(): void {
68
+ this.themeService.toggleTheme();
69
+ }
70
+
71
+ useSystemTheme(): void {
72
+ this.themeService.setTheme('system');
73
+ }
74
+
75
+ setScheme(scheme: ColorScheme): void {
76
+ this.themeService.setScheme(scheme);
77
+ }
78
+ }
79
+ ```
80
+
81
+ Domain and API features are published from the companion package:
82
+
83
+ ```ts
84
+ import { AuthService } from '@edsis/library';
85
+ ```
86
+
87
+ ## Workspace Development
88
+
89
+ Inside this repository, `tsconfig.json` exposes development-only aliases:
90
+
91
+ ```json
92
+ {
93
+ "compilerOptions": {
94
+ "paths": {
95
+ "@edsis/angular": ["./projects/library/angular/src/public-api"],
96
+ "@edsis/angular/*": ["./projects/library/angular/src/lib/*"]
97
+ }
98
+ }
99
+ }
100
+ ```
101
+
102
+ That means imports like `@edsis/angular/themes` are valid while developing in this workspace, but they should not be documented as published package entry points.
103
+
104
+ ## Theme Bootstrapping
105
+
106
+ `ThemeService` reads settings in this order:
107
+
108
+ 1. localStorage values if they exist
109
+ 2. HTML `data-*` attributes if storage is empty
110
+ 3. built-in defaults if neither source is present
111
+
112
+ Supported attributes on `<html>`:
113
+
114
+ - `data-theme`
115
+ - `data-scheme`
116
+ - `data-container`
117
+ - `data-layout`
118
+
119
+ Built-in defaults when no persisted or HTML values are available:
120
+
121
+ - `data-theme="light"`
122
+ - `data-container="boxed"`
123
+ - `data-scheme="blue"`
124
+ - `data-layout="vertical"`
125
+
126
+ ## Library Development
127
+
128
+ Useful commands from the workspace root:
129
+
130
+ ```bash
131
+ npm run build:lib
132
+ npx ng test edsis-angular --watch=false
133
+ npm run lint
134
+ ```
135
+
136
+ ### Reactive Signals
137
+
138
+ All settings are exposed as Angular signals for reactive updates:
139
+
140
+ ```typescript
141
+ import { Component, inject, computed } from '@angular/core';
142
+ import { ThemeService } from '@edsis/angular';
143
+
144
+ @Component({
145
+ template: `
146
+ <div>
147
+ <p>Current theme: {{ currentTheme() }}</p>
148
+ <p>Is dark mode: {{ isDark() }}</p>
149
+ <p>Scheme color: {{ schemeColor() }}</p>
150
+ </div>
151
+ `,
152
+ })
153
+ export class MyComponent {
154
+ themeService = inject(ThemeService);
155
+
156
+ // Direct access to signals
157
+ currentTheme = this.themeService.theme;
158
+ currentResolvedTheme = this.themeService.resolvedTheme;
159
+
160
+ // Computed signals
161
+ isDark = computed(() => this.themeService.resolvedTheme() === 'dark');
162
+ schemeColor = computed(() => this.themeService.getCurrentSchemeColor());
163
+ }
164
+ ```
165
+
166
+ #### Persistence
167
+
168
+ All settings are automatically:
169
+
170
+ - ✅ Saved to `localStorage` on change
171
+ - ✅ Loaded from `localStorage` on app init
172
+ - ✅ Applied to DOM via `data-*` attributes
173
+ - ✅ `data-theme="system"` follows the OS light/dark preference
174
+ - ✅ Synced across tabs/windows
175
+
176
+ ## 🎨 Design Tokens
177
+
178
+ ### Theme Colors
179
+
180
+ - `--background` / `bg-background`
181
+ - `--foreground` / `text-foreground`
182
+ - `--card` / `bg-card`
183
+ - `--primary` / `bg-primary`
184
+ - `--secondary` / `bg-secondary`
185
+ - `--muted` / `bg-muted`
186
+ - `--accent` / `bg-accent`
187
+ - `--destructive` / `bg-destructive`
188
+ - `--border` / `border-border`
189
+
190
+ ### Typography
191
+
192
+ ```css
193
+ font-family: var(--font-sans); /* Inter */
194
+ font-family: var(--font-mono); /* CommitMono */
195
+ ```
196
+
197
+ Custom font weights:
198
+
199
+ - `font-normal` - 450
200
+ - `font-medium` - 550
201
+ - `font-semibold` - 650
202
+ - `font-bold` - 700
203
+
204
+ ## 📚 Documentation
205
+
206
+ For detailed usage instructions, see:
207
+
208
+ - [USAGE.md](./src/lib/styles/USAGE.md) - Complete usage guide
209
+ - [Lucide Icons README](./src/lib/styles/icons/README.md) - Legacy sprite usage details
210
+
211
+ ## 🔧 Building the Library
212
+
213
+ ```bash
214
+ # Build library
215
+ ng build edsis-angular
216
+
217
+ # Build and watch
218
+ ng build edsis-angular --watch
219
+ ```
220
+
221
+ ## 📄 License
222
+
223
+ Private library for ETOS projects.
224
+
225
+ ## 🤝 Contributing
226
+
227
+ This is a workspace library. Make changes in `projects/library/angular/src/lib/styles/` and test in the demo app.