@guildofgleks/ui 21.3.0 → 21.3.2
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/AGENTS.md +1149 -0
- package/LICENSE +201 -21
- package/README.md +397 -320
- package/TOKENS.md +63 -0
- package/fesm2022/guildofgleks-ui.mjs +863 -120
- package/fesm2022/guildofgleks-ui.mjs.map +1 -1
- package/package.json +12 -5
- package/src/styles/index.css +17 -17
- package/src/styles/theme.css +1681 -1643
- package/styles/fonts.css +16 -0
- package/styles/index.css +17 -0
- package/styles/presets/one-dark.css +48 -0
- package/styles/presets/one-light.css +47 -0
- package/styles/presets/slate.css +55 -0
- package/styles/theme.css +1681 -0
- package/styles/typography.css +15 -0
- package/styles/utilities.css +170 -0
- package/types/guildofgleks-ui.d.ts +642 -54
package/README.md
CHANGED
|
@@ -1,320 +1,397 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
A lightweight Angular 21 component library. No CDK, no Material — the only runtime
|
|
8
|
-
dependencies are `@angular/core`, `@angular/common` and `@angular/forms`.
|
|
9
|
-
|
|
10
|
-
**Tags:** angular, angular21, components, ui-library, design-system, signals, standalone, accessible
|
|
11
|
-
|
|
12
|
-
## Features
|
|
13
|
-
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
`
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
"styles"
|
|
53
|
-
"
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
@
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
```css
|
|
147
|
-
|
|
148
|
-
--gog-btn-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
}
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
`--gog-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
The
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
(
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
:
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
The
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
`
|
|
300
|
-
`
|
|
301
|
-
|
|
302
|
-
`gog-
|
|
303
|
-
`gog-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
`
|
|
311
|
-
`
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
1
|
+
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
A lightweight Angular 21 component library. No CDK, no Material — the only runtime
|
|
8
|
+
dependencies are `@angular/core`, `@angular/common` and `@angular/forms`.
|
|
9
|
+
|
|
10
|
+
**Tags:** angular, angular21, components, ui-library, design-system, signals, standalone, accessible
|
|
11
|
+
|
|
12
|
+
## Features
|
|
13
|
+
|
|
14
|
+
- 27 standalone components and 2 directives — see [Components](#components) for the full
|
|
15
|
+
list — plus `DialogService`, `ToastService` and `ThemeService`.
|
|
16
|
+
- Signal-based API throughout: `input()` / `output()` / `model()`, `OnPush` change
|
|
17
|
+
detection, no NgModules.
|
|
18
|
+
- No CDK, no Material — a small dependency footprint on top of `@angular/core`,
|
|
19
|
+
`@angular/common` and `@angular/forms`.
|
|
20
|
+
- Full theming through CSS custom properties: restyle any component, swap the whole
|
|
21
|
+
palette, or ship light/dark and custom themes at runtime via a `data-theme` attribute.
|
|
22
|
+
- `ControlValueAccessor` on every form control (checkbox, inputfield, select,
|
|
23
|
+
multiselect, slider, textarea) — built and tested against Reactive Forms (`formControl` /
|
|
24
|
+
`formControlName`). The library does not use `ngModel`/`FormsModule` anywhere itself,
|
|
25
|
+
and template-driven usage via `[(ngModel)]` is untested — CVA makes it likely to work,
|
|
26
|
+
but it isn't a supported or verified path.
|
|
27
|
+
- Accessible by default: keyboard navigation, ARIA attributes, WCAG AA contrast.
|
|
28
|
+
|
|
29
|
+
## Install
|
|
30
|
+
|
|
31
|
+
npm:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install @guildofgleks/ui
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
yarn:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
yarn add @guildofgleks/ui
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Setup
|
|
44
|
+
|
|
45
|
+
Add the stylesheet once. It carries the baseline theme (every token the components
|
|
46
|
+
read) plus the utility classes the component templates use, so without it components
|
|
47
|
+
render unstyled.
|
|
48
|
+
|
|
49
|
+
```jsonc
|
|
50
|
+
// angular.json → projects.<app>.architect.build.options
|
|
51
|
+
"styles": [
|
|
52
|
+
"node_modules/@guildofgleks/ui/styles/index.css",
|
|
53
|
+
"src/styles.scss" // your own styles, after the baseline so they win
|
|
54
|
+
]
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
> Up to 21.3.1 the same files shipped under `@guildofgleks/ui/src/styles/…`. That path still
|
|
58
|
+
> works and will keep working until 21.5.0 — new setups should use the shorter one above.
|
|
59
|
+
|
|
60
|
+
Then import a component where you need it:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
import { Component } from '@angular/core';
|
|
64
|
+
import { ButtonComponent, SelectComponent } from '@guildofgleks/ui';
|
|
65
|
+
|
|
66
|
+
@Component({
|
|
67
|
+
selector: 'app-example',
|
|
68
|
+
imports: [ButtonComponent, SelectComponent],
|
|
69
|
+
template: `
|
|
70
|
+
<gog-select label="Region" [options]="regions" [(value)]="region" />
|
|
71
|
+
<gog-button (gogClick)="save()">Save</gog-button>
|
|
72
|
+
`,
|
|
73
|
+
})
|
|
74
|
+
export class ExampleComponent {
|
|
75
|
+
/* … */
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Outputs are prefixed with `gog` (`gogClick`, `gogToggle`) so they never collide with
|
|
80
|
+
native DOM events. Inputs keep their natural names.
|
|
81
|
+
|
|
82
|
+
### Services need a host element
|
|
83
|
+
|
|
84
|
+
`DialogService` and `ToastService` render into a host component you place once, rather than
|
|
85
|
+
creating a detached portal of their own. **Without the host in a template, `open()` and
|
|
86
|
+
`show()` update state and nothing appears on screen.** Put both in your root template — they
|
|
87
|
+
render nothing until something is actually open:
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
import { Component, inject } from '@angular/core';
|
|
91
|
+
import { DialogComponent, ToastContainerComponent, ToastService } from '@guildofgleks/ui';
|
|
92
|
+
|
|
93
|
+
@Component({
|
|
94
|
+
selector: 'app-root',
|
|
95
|
+
imports: [DialogComponent, ToastContainerComponent],
|
|
96
|
+
template: `
|
|
97
|
+
<router-outlet />
|
|
98
|
+
|
|
99
|
+
<gog-dialog />
|
|
100
|
+
<gog-toast-container />
|
|
101
|
+
`,
|
|
102
|
+
})
|
|
103
|
+
export class App {
|
|
104
|
+
private readonly toasts = inject(ToastService);
|
|
105
|
+
notify = () => this.toasts.show({ message: 'Saved', type: 'success' });
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`<gog-dialog />` hosts every dialog opened through `DialogService` (they stack, so one host is
|
|
110
|
+
enough for the whole app). `<gog-toast-container />` hosts all four toast positions at once and
|
|
111
|
+
takes an optional `maxVisiblePerPosition` (default `5`).
|
|
112
|
+
|
|
113
|
+
## Theming
|
|
114
|
+
|
|
115
|
+
Everything is themed through CSS custom properties, and **every value the components
|
|
116
|
+
paint with lives in `styles/theme.css`** — no component stylesheet holds a colour, font,
|
|
117
|
+
border, radius, shadow, spacing or duration of its own. There are three layers:
|
|
118
|
+
|
|
119
|
+
**1. Foundation tokens** — the palette, type scale, spacing, motion and control metrics.
|
|
120
|
+
Override these to restyle everything at once; the component tokens all derive from them,
|
|
121
|
+
so a palette swap carries through without touching anything else.
|
|
122
|
+
|
|
123
|
+
Every group and every token name is listed in [`TOKENS.md`](./TOKENS.md) — generated from
|
|
124
|
+
`theme.css`, so it cannot drift from what the components actually read. The same catalogue is
|
|
125
|
+
available at runtime as `GOG_TOKEN_GROUPS`, typed by `GogTokenName`.
|
|
126
|
+
|
|
127
|
+
**2. Component tokens** — `--gog-<block>-*`, one block per component in `theme.css`, for
|
|
128
|
+
restyling a single component theme-wide. They cover every painted property, including
|
|
129
|
+
per-variant and per-size values (`--gog-btn-ghost-hover-bg`, `--gog-tag-lg-padding-block`,
|
|
130
|
+
`--gog-accordion-sm-chevron-size`, `--gog-skeleton-shine`, `--gog-paginator-gap`, …), plus
|
|
131
|
+
each component's font family, so a theme can decide that e.g. buttons use the body face:
|
|
132
|
+
|
|
133
|
+
```css
|
|
134
|
+
:root[data-theme='mine'] {
|
|
135
|
+
--gog-btn-font-family: var(--gog-font-body);
|
|
136
|
+
--gog-btn-font-weight: 600;
|
|
137
|
+
--gog-btn-ghost-hover-bg: color-mix(in srgb, var(--gog-accent-color) 20%, transparent);
|
|
138
|
+
--gog-table-hover-bg: var(--gog-hover-color);
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
**3. Instance tokens** — a small set left deliberately _undeclared_ so that setting them
|
|
143
|
+
anywhere always wins over the variant/size classes. This is the per-instance escape
|
|
144
|
+
hatch:
|
|
145
|
+
|
|
146
|
+
```css
|
|
147
|
+
.my-form gog-button {
|
|
148
|
+
--gog-btn-bg: rebeccapurple; /* beats .gog-btn--primary, unlike a declared token */
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
They are `--gog-btn-{bg,color,border,shadow,hover-bg,hover-color,hover-shadow,padding,font-size,spinner-color}`,
|
|
153
|
+
`--gog-tag-{accent,bg,border,color,font-size,gap,padding-block,padding-inline,icon-size}`,
|
|
154
|
+
`--gog-chip-{font-size,gap,padding-block,padding-inline,avatar-size,icon-size,remove-size}`,
|
|
155
|
+
the per-size field hooks (`--gog-input-padding-y`, `--gog-select-control-font`,
|
|
156
|
+
`--gog-ms-font-size`, `--gog-table-td-padding-v`, `--gog-accordion-padding-y`, …),
|
|
157
|
+
`--gog-spinner-color`, and `--gog-{input,select,ms}-float-label-on-bg` (the patch masking the
|
|
158
|
+
border behind an `'on'` label).
|
|
159
|
+
|
|
160
|
+
The full list is the `INSTANCE_TOKENS` set in `scripts/check-tokens.mjs`, which is verified
|
|
161
|
+
against the stylesheets on every CI run — an instance token that gets declared anywhere, or
|
|
162
|
+
stops being read, fails the build. That check also enforces the other half of the contract:
|
|
163
|
+
**no component stylesheet carries a default in a `var()` fallback**, so every value a
|
|
164
|
+
component paints with really is discoverable in `theme.css`.
|
|
165
|
+
|
|
166
|
+
The float label's _geometry_ is not instance-layer — it is themeable per component
|
|
167
|
+
(`--gog-{input,select,ms}-float-label-{reserve,in-top,over-gap,over-reserve}`), and all three
|
|
168
|
+
derive from the shared `--gog-field-float-label-*` scale above, so one declaration retunes
|
|
169
|
+
every field at once while a single control can still be overridden on its own.
|
|
170
|
+
|
|
171
|
+
### Light and dark
|
|
172
|
+
|
|
173
|
+
The theme is selected with a `data-theme` attribute on `:root`, and `ThemeService`
|
|
174
|
+
manages it:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
private readonly theme = inject(ThemeService);
|
|
178
|
+
this.theme.toggleTheme(); // light ⇄ dark
|
|
179
|
+
this.theme.setTheme('cyberpunk'); // any custom theme name
|
|
180
|
+
this.theme.theme(); // read-only signal — go through the two methods above
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Out of the box it adopts whatever `data-theme` is already on the document, or `'light'`.
|
|
184
|
+
Persisting the choice and following the OS setting are opt-in, through `GOG_CONFIG.theme`:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
provideGogConfig({
|
|
188
|
+
theme: { storageKey: 'app-theme', followSystem: true, darkTheme: 'cyberpunk' },
|
|
189
|
+
});
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
To add a theme, copy a palette block from `styles/theme.css` and change the attribute
|
|
193
|
+
value. A theme only needs to declare what it actually changes — the component tokens are
|
|
194
|
+
re-derived from whatever palette is in scope, so a swapped `--gog-accent-color` reaches every
|
|
195
|
+
component without listing any of them:
|
|
196
|
+
|
|
197
|
+
```css
|
|
198
|
+
:root[data-theme='cyberpunk'],
|
|
199
|
+
[data-theme='cyberpunk'] {
|
|
200
|
+
color-scheme: dark;
|
|
201
|
+
--gog-background-color: #050816;
|
|
202
|
+
--gog-accent-color: #ff4edb;
|
|
203
|
+
--gog-radius: 22px;
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The second selector is what lets a theme apply to a _subtree_ rather than the whole page
|
|
208
|
+
— put `data-theme="cyberpunk"` on any element and everything inside it re-derives from
|
|
209
|
+
that palette, so one page can show several themes side by side (see the showcase's Theme
|
|
210
|
+
lab). That works because `theme.css` re-declares its derived layer on `:root, [data-theme]`:
|
|
211
|
+
a custom property's `var()` references are substituted where the property is _declared_,
|
|
212
|
+
so a derived token declared only on `:root` would freeze to the root palette.
|
|
213
|
+
|
|
214
|
+
Corollary worth knowing when writing your own themes: **anything you declare that reads
|
|
215
|
+
another token must sit on the theme scope itself**, not on `:root`, or it will not follow
|
|
216
|
+
a nested theme.
|
|
217
|
+
|
|
218
|
+
### Presets
|
|
219
|
+
|
|
220
|
+
`theme.css` ships `light` and `dark`. `slate` is a third, importable separately — a
|
|
221
|
+
palette-only theme in a cool/indigo register:
|
|
222
|
+
|
|
223
|
+
```css
|
|
224
|
+
@import '@guildofgleks/ui/styles/index.css';
|
|
225
|
+
@import '@guildofgleks/ui/styles/presets/slate.css';
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
```html
|
|
229
|
+
<html data-theme="slate"></html>
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
It is worth reading as the worked example of the contract above: it declares **only palette
|
|
233
|
+
tokens** — no `--gog-btn-*`, no `--gog-table-*` — and still restyles every component, because
|
|
234
|
+
the derived layer re-resolves against whatever palette is in scope. If a theme of yours needs to
|
|
235
|
+
list component tokens, that usually means the derived layer is missing something rather than
|
|
236
|
+
that the theme needs to be longer.
|
|
237
|
+
|
|
238
|
+
### Optional font preset
|
|
239
|
+
|
|
240
|
+
`styles/index.css` intentionally leaves fonts alone — generic system stacks, no webfont
|
|
241
|
+
download. For the showcase's typography (Cinzel / Inter / JetBrains Mono, pulled from
|
|
242
|
+
Google Fonts) add `@guildofgleks/ui/styles/fonts.css` as well.
|
|
243
|
+
|
|
244
|
+
## Global configuration
|
|
245
|
+
|
|
246
|
+
Anything visual is a CSS token (above). For the rest — the handful of settings an app would
|
|
247
|
+
otherwise repeat on every instance — there is one provider, not an injection token per
|
|
248
|
+
component per setting:
|
|
249
|
+
|
|
250
|
+
```ts
|
|
251
|
+
// app.config.ts
|
|
252
|
+
import { provideGogConfig } from '@guildofgleks/ui';
|
|
253
|
+
|
|
254
|
+
providers: [
|
|
255
|
+
provideGogConfig({
|
|
256
|
+
control: { size: 'sm', errorDisplay: 'auto', clearable: true },
|
|
257
|
+
dropdown: { appendToBody: true },
|
|
258
|
+
datepicker: { locale: 'de-DE', format: 'dd.MM.yyyy' },
|
|
259
|
+
button: { debounce: 500 },
|
|
260
|
+
}),
|
|
261
|
+
];
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Keys: `control`, `dropdown`, `floatLabel`, `datepicker`, `autocomplete`, `inputfield`,
|
|
265
|
+
`textarea`, `tooltip`, `scroll`, `button`, `toast`, `theme`, `labels`. Every field is optional,
|
|
266
|
+
and an instance's own input always wins over the configured value. Providing it again lower in
|
|
267
|
+
the injector tree (a route, a component) **layers onto** the parent's config one level deep
|
|
268
|
+
rather than replacing it, so a route can override one field and inherit the rest.
|
|
269
|
+
|
|
270
|
+
### Translating the library
|
|
271
|
+
|
|
272
|
+
`labels` carries every fixed string the components render themselves — the ones you never write
|
|
273
|
+
markup for. Set them once instead of on every control:
|
|
274
|
+
|
|
275
|
+
```ts
|
|
276
|
+
provideGogConfig({
|
|
277
|
+
labels: {
|
|
278
|
+
clear: 'Очистить',
|
|
279
|
+
clearSelection: 'Очистить выбор',
|
|
280
|
+
selectAll: 'Выбрать все',
|
|
281
|
+
closeDialog: 'Закрыть',
|
|
282
|
+
previousPage: 'Предыдущая страница',
|
|
283
|
+
today: 'Сегодня',
|
|
284
|
+
// interpolating labels take a function, since word order and agreement vary by language
|
|
285
|
+
page: (page, isCurrent) =>
|
|
286
|
+
isCurrent ? `Страница ${page}, текущая` : `Перейти на страницу ${page}`,
|
|
287
|
+
},
|
|
288
|
+
});
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
The full key list is on `GogGlobalConfig['labels']`. Strings that describe *one* control rather
|
|
292
|
+
than library chrome — a field's `label`, a button's `ariaLabel` — are deliberately not in here;
|
|
293
|
+
those stay per instance.
|
|
294
|
+
|
|
295
|
+
## Components
|
|
296
|
+
|
|
297
|
+
| Group | Components |
|
|
298
|
+
| --- | --- |
|
|
299
|
+
| Form controls | `gog-inputfield`, `gog-textarea`, `gog-select`, `gog-multiselect`, `gog-autocomplete`, `gog-checkbox`, `gog-radio-group`, `gog-toggle`, `gog-slider`, `gog-datepicker`, `gog-calendar`, `gog-button-toggle-group` |
|
|
300
|
+
| Actions | `gog-button`, `gog-chip` |
|
|
301
|
+
| Data | `gog-table` (+ `gog-column`), `gog-paginator`, `gog-tag` |
|
|
302
|
+
| Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-divider`, `gog-scroll` |
|
|
303
|
+
| Overlays | `gog-dialog`, `gog-confirmation-dialog`, `gog-toast` (+ `gog-toast-container`) |
|
|
304
|
+
| Feedback | `gog-spinner`, `gog-spinner-overlay`, `gog-progressbar`, `gog-skeleton` |
|
|
305
|
+
| Content | `gog-icon` |
|
|
306
|
+
|
|
307
|
+
Directives: `gogTooltip`, `gogBadge`, `gogCollapsibleTrigger`, `gogCollapsibleContent`.
|
|
308
|
+
|
|
309
|
+
Slot directives, for replacing a component's markup rather than configuring it:
|
|
310
|
+
`gogAccordionHeader`, `gogAccordionContent`, `gogAccordionChevron`, `gogButtonToggleOption`,
|
|
311
|
+
`gogCheckboxIcon`, `gogColumnBody`, `gogColumnHeader`, `gogDropdownOption`,
|
|
312
|
+
`gogDropdownChevron`, `gogInputAddonStart`, `gogInputAddonEnd`, `gogMultiselectClearIcon`,
|
|
313
|
+
`gogTabHeader`, `gogTabContent`, `gogTagIcon`.
|
|
314
|
+
|
|
315
|
+
`gog-dialog` and `gog-toast-container` are the host elements the two services render into —
|
|
316
|
+
see [Services need a host element](#services-need-a-host-element).
|
|
317
|
+
|
|
318
|
+
Services: `DialogService`, `ToastService`, `ThemeService`.
|
|
319
|
+
|
|
320
|
+
`gog-collapsible` is a headless expand/collapse primitive — no owned markup, no portal.
|
|
321
|
+
Project any element as the trigger via `gogCollapsibleTrigger` and any element as the
|
|
322
|
+
panel via `gogCollapsibleContent`; `[(open)]` is two-way bindable. Useful for anything
|
|
323
|
+
that needs an inline expanding region without the overlay behavior of `gog-select`/
|
|
324
|
+
`gog-multiselect` — e.g. a collapsible group of links in a nav sidebar.
|
|
325
|
+
|
|
326
|
+
### Options come from your own objects
|
|
327
|
+
|
|
328
|
+
`gog-select` and `gog-multiselect` do not require a `{ id, name }` shape. `optionLabel`,
|
|
329
|
+
`optionValue` and `optionDisabled` each take a property path — dot-paths included — or a
|
|
330
|
+
function:
|
|
331
|
+
|
|
332
|
+
```html
|
|
333
|
+
<gog-select
|
|
334
|
+
[options]="members"
|
|
335
|
+
optionLabel="profile.fullName"
|
|
336
|
+
optionValue="uuid"
|
|
337
|
+
optionDisabled="suspended"
|
|
338
|
+
[(value)]="memberId"
|
|
339
|
+
/>
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
Set `[optionValue]="null"` and the control emits the option object itself, so a selection round-trips
|
|
343
|
+
without a lookup table:
|
|
344
|
+
|
|
345
|
+
```html
|
|
346
|
+
<gog-select [options]="members" [optionLabel]="nameOf" [optionValue]="null" [(value)]="member">
|
|
347
|
+
<ng-template gogDropdownOption let-m let-label="label">
|
|
348
|
+
{{ label }} — {{ $any(m).profile.role }}
|
|
349
|
+
</ng-template>
|
|
350
|
+
</gog-select>
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
The defaults are `'name'` / `'id'` / `'disabled'`, which is what `GogDropdownOption` describes —
|
|
354
|
+
so code written against that shape keeps working unchanged.
|
|
355
|
+
|
|
356
|
+
`gogTooltip` is a hover/focus tooltip directive, not a component — drop it on any element,
|
|
357
|
+
a `gog-*` component's own host tag or a plain native one
|
|
358
|
+
(`<button gogTooltip="Save changes">`, `<gog-chip [gogTooltip]="hint">`). Content is a
|
|
359
|
+
string or a `TemplateRef`; `gogTooltipPosition` (`'auto'` default, or an explicit side),
|
|
360
|
+
`gogTooltipShowDelay` (`300`ms default), `gogTooltipHideDelay` (`100`ms default) and
|
|
361
|
+
`gogTooltipDisabled` inputs, the first three also configurable app-wide via
|
|
362
|
+
`GOG_CONFIG.tooltip`.
|
|
363
|
+
|
|
364
|
+
`gog-inputfield` and `gog-textarea` forward the native attribute space of the element they
|
|
365
|
+
wrap, so nothing is out of reach because it is hidden inside a component: `readonly`,
|
|
366
|
+
`maxlength`, `minlength`, `spellcheck`, plus `pattern` and `inputMode` on the input, and the
|
|
367
|
+
`type` values that render as a text field (`text`, `password`, `email`, `number`, `search`,
|
|
368
|
+
`tel`, `url`, `date`, `time`, `datetime-local` — see `GogInputType`). `readonly` keeps the
|
|
369
|
+
value focusable and submitted but blocks edits, so the clear button and a number field's
|
|
370
|
+
stepper both stand down while it is on. `autofocus` is deliberately **not** forwarded: moving
|
|
371
|
+
focus without the user asking is disorienting for keyboard and screen-reader users, and an app
|
|
372
|
+
that genuinely needs it can focus the element itself.
|
|
373
|
+
|
|
374
|
+
Every field also generates its own `id` when you don't pass `inputId`, so the label is always
|
|
375
|
+
associated with the control and the error message is always reachable through
|
|
376
|
+
`aria-describedby`. Pass `inputId` only when something outside the component has to reference
|
|
377
|
+
the field by a known id.
|
|
378
|
+
|
|
379
|
+
`gog-checkbox`, `gog-inputfield`, `gog-select`, `gog-multiselect`, `gog-slider` and
|
|
380
|
+
`gog-textarea` implement `ControlValueAccessor` and are built for Reactive Forms — use
|
|
381
|
+
`[formControl]` or `formControlName`. The library itself never imports `FormsModule` or
|
|
382
|
+
uses `ngModel`; `[(ngModel)]` is not tested against these components and isn't a
|
|
383
|
+
supported usage path. With a form control attached, the error message appears once the
|
|
384
|
+
control is both touched and invalid; without one it shows for as long as `errorMessage`
|
|
385
|
+
is non-empty, and the consumer decides when to clear it.
|
|
386
|
+
|
|
387
|
+
`gog-inputfield`, `gog-select`, `gog-multiselect` and `gog-textarea` all accept a
|
|
388
|
+
`floatLabel` input — `'in'` (floats up but stays inside the border), `'on'` (floats to sit
|
|
389
|
+
centered on the top border line) or `'over'` (floats fully above the field, outside the
|
|
390
|
+
border) — plus `floatLabelShowPlaceholder` to reveal the field's own `placeholder` once the
|
|
391
|
+
label has floated out of the way (it stays hidden the whole time otherwise, since the
|
|
392
|
+
resting label already sits where it would). Both default to off/`false` and are settable
|
|
393
|
+
per instance or app-wide via `GOG_CONFIG.floatLabel`.
|
|
394
|
+
|
|
395
|
+
## License
|
|
396
|
+
|
|
397
|
+
Apache-2.0 © Roman Malitskyi
|