@guildofgleks/ui 21.10.0 → 21.12.0
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 +72 -41
- package/CHANGELOG.md +533 -17
- package/README.md +503 -402
- package/TOKENS.md +51 -49
- package/fesm2022/guildofgleks-ui.mjs +151 -58
- package/fesm2022/guildofgleks-ui.mjs.map +1 -1
- package/package.json +1 -1
- package/styles/button.css +434 -401
- package/styles/presets/bevel.css +110 -87
- package/styles/presets/ledger.css +22 -2
- package/styles/presets/material.css +157 -122
- package/styles/presets/one-dark.css +101 -82
- package/styles/presets/one-light.css +99 -73
- package/styles/presets/parchment.css +25 -2
- package/styles/presets/primeng.css +175 -139
- package/styles/presets/slate.css +21 -1
- package/styles/presets/terminal.css +102 -72
- package/styles/theme.css +599 -195
- package/types/guildofgleks-ui.d.ts +3 -3
package/AGENTS.md
CHANGED
|
@@ -175,6 +175,19 @@ Full model is in `README.md`'s Theming section; short version:
|
|
|
175
175
|
everything) → **component** (`--gog-button-primary-bg`, …, one block per component, named after
|
|
176
176
|
the component's own element) → **instance** (`--gog-button-bg`, …, deliberately undeclared
|
|
177
177
|
escape hatch for one element).
|
|
178
|
+
- **`--gog-control-boundary-color` is the edge that identifies a control** (since 21.12.0), and
|
|
179
|
+
it is not `--gog-border-color`, which is the decorative hairline for dividers, table rules and
|
|
180
|
+
panel outlines. `gog-chip`, `gog-toggle` and `gog-button-toggle` read it. A theme sets both.
|
|
181
|
+
- **Shadows are an elevation ladder** (since 21.12.0): `--gog-elevation-0` … `-5`, Z doubling
|
|
182
|
+
0/1/2/4/8/16. Step 1 is a thumb riding on a control, 2 an `elevated` card or panel, 3 anything
|
|
183
|
+
anchored to a control (dropdown panel, tooltip, menu), 4 a toast, 5 a modal dialog. The steps are
|
|
184
|
+
generated from ten per-theme knobs (`--gog-elevation-ink`, the two alphas, `-contact-blur`, the
|
|
185
|
+
three per-Z multipliers `-key-x`/`-key-y`/`-key-blur` that carry the style, `-ring-width`, and
|
|
186
|
+
the two `-highlight-*`). **A theme declares all ten or none** — they inherit, so a partial set
|
|
187
|
+
borrows the enclosing theme's weight. `--gog-panel-shadow`, `--gog-dialog-shadow`,
|
|
188
|
+
`--gog-toast-shadow`, `--gog-menu-shadow`, `--gog-toggle-thumb-shadow` and the `*-elevated-shadow`
|
|
189
|
+
pair are still the names to override for one surface; their default is now a step. Never
|
|
190
|
+
hand-write a shadow in a theme block — `npm run check:elevation` fails on it.
|
|
178
191
|
- **Foundation includes a small character layer** (since 21.7.0, `docs/themes.md` iteration 1):
|
|
179
192
|
`--gog-radius` (corner rounding), `--gog-control-border-*`/`--gog-panel-border-*`/`--gog-border-*`
|
|
180
193
|
(border weight — form fields, raised surfaces, everything smaller and inline, respectively),
|
|
@@ -195,11 +208,16 @@ Full model is in `README.md`'s Theming section; short version:
|
|
|
195
208
|
the library above your own chrome without disturbing its internal order.
|
|
196
209
|
|
|
197
210
|
- **`--gog-density` is the character layer for spacing** (since 21.7.0, `docs/themes.md`
|
|
198
|
-
iteration 6). It multiplies the
|
|
211
|
+
iteration 6). It multiplies the ten-step scale `--gog-space-4` … `--gog-space-48`, named
|
|
199
212
|
for their pixel value at density 1, and every padding and gap in the library derives from a
|
|
200
213
|
step. `--gog-density: 0.9` in a `[data-theme]` block makes the whole library tighter; nothing
|
|
201
214
|
else needs to be named. `--gog-space-xs|sm|md|lg|2xl` are aliases for steps 4/8/16/24/48 and
|
|
202
|
-
still work.
|
|
215
|
+
still work. **Every step is a multiple of 4** (since 21.11.0): the five 2px-granular steps came
|
|
216
|
+
out once the last of their 102 readers moved, so "on the grid" is a fact about the scale rather
|
|
217
|
+
than a habit. Three lengths stay off it on purpose and say so in their own comments — a toggle
|
|
218
|
+
thumb's inset, a scrollbar thumb's, and the resize grip's hairline gap — because a length inside
|
|
219
|
+
a single painted mark defines that mark's shape rather than spacing two things apart.
|
|
220
|
+
Icon offsets, dropdown panel gaps, error-line offsets and the badge's overhang
|
|
203
221
|
follow density; the glyph box, the focus-ring offset, the float-label reserve and the
|
|
204
222
|
scrollbar/toggle thumb insets deliberately do not — those are legibility or geometry fitted to
|
|
205
223
|
a fixed-width track, not spacing. Since 21.9.0 the split is enforced rather than trusted:
|
|
@@ -280,24 +298,24 @@ Precedence, always: **instance input → `GOG_CONFIG` → component's built-in d
|
|
|
280
298
|
`provideGogConfig(...)` (in a route's or component's own `providers`) **layers onto the
|
|
281
299
|
parent's config**, one level deep per key — it does not replace it.
|
|
282
300
|
|
|
283
|
-
| Key | Fields
|
|
284
|
-
| -------------- |
|
|
285
|
-
| `control` | `size`, `errorDisplay`, `clearable`
|
|
286
|
-
| `dropdown` | `appendToBody`, `direction`, `filter`, `filterPosition`
|
|
287
|
-
| `floatLabel` | `variant`, `showPlaceholder`
|
|
288
|
-
| `datepicker` | `locale`, `firstDayOfWeek`, `format`
|
|
289
|
-
| `autocomplete` | `searchDebounce`, `minLength`, `openOnFocus`
|
|
290
|
-
| `tooltip` | `position`, `showDelay`, `hideDelay`
|
|
291
|
-
| `spinner` | `component`, `variant`
|
|
292
|
-
| `scroll` | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`, `horizontalWheel` | `gog-scroll` (and every component that uses one internally).
|
|
293
|
-
| `button` | `debounce`
|
|
294
|
-
| `ripple` | `enabled`
|
|
295
|
-
| `inputfield` | `showSpinButtons`
|
|
296
|
-
| `textarea` | `resize`
|
|
297
|
-
| `paginator` | `showPageSizeSelect`, `pageSizeOptions`
|
|
298
|
-
| `toast` | `position`, `duration`
|
|
299
|
-
| `theme` | `storageKey`, `defaultTheme`, `followSystem`, `lightTheme`, `darkTheme`
|
|
300
|
-
| `labels` | every fixed string the library renders — see below
|
|
301
|
+
| Key | Fields | Applies to |
|
|
302
|
+
| -------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
303
|
+
| `control` | `size`, `errorDisplay`, `clearable` | `size`: button, `[gogButton]`, button-toggle-group, checkbox, toggle, radio-group, inputfield, textarea, select, multiselect, autocomplete, datepicker. `errorDisplay`: inputfield, textarea, select, multiselect, autocomplete, datepicker, radio-group, slider. `clearable`: inputfield, textarea, select, multiselect, autocomplete, datepicker. Not table/accordion/paginator (density, not form size), not spinner/skeleton/tag/chip. |
|
|
304
|
+
| `dropdown` | `appendToBody`, `direction`, `filter`, `filterPosition` | `gog-select`, `gog-multiselect`. `gog-datepicker`/`gog-autocomplete` honour `appendToBody`/`direction` too (autocomplete has no `filter` box — it filters via the trigger's own text). |
|
|
305
|
+
| `floatLabel` | `variant`, `showPlaceholder` | inputfield, textarea, select, multiselect, autocomplete, datepicker. |
|
|
306
|
+
| `datepicker` | `locale`, `firstDayOfWeek`, `format` | `gog-datepicker`, `gog-calendar`. |
|
|
307
|
+
| `autocomplete` | `searchDebounce`, `minLength`, `openOnFocus` | `gog-autocomplete`. |
|
|
308
|
+
| `tooltip` | `position`, `showDelay`, `hideDelay` | the `gogTooltip` directive. |
|
|
309
|
+
| `spinner` | `component`, `variant` | every spinner the library draws — `gog-spinner`, `gog-spinner-overlay`, and the ones inside `gog-button`, `gog-autocomplete` and `gog-table`, which have no input of their own. `component` takes **your** component and renders it in place of the built-in look. The overlay honoured neither key until 21.10.0, and `gog-table` was simply never listed. |
|
|
310
|
+
| `scroll` | `autoHide`, `hideDelay`, `size`, `overscrollBehavior`, `showTrack`, `horizontalWheel` | `gog-scroll` (and every component that uses one internally). |
|
|
311
|
+
| `button` | `debounce` | `gog-button`. |
|
|
312
|
+
| `ripple` | `enabled` | the press ripple on `gog-button`, `[gogButton]`, `gog-button-toggle-group`, `gog-chip`, `gog-tabs`, `gog-accordion`, `gogCollapsibleTrigger`, `gogMenuItem` and the `gog-select`/`gog-multiselect`/`gog-autocomplete` options. **Off by default.** Each of those takes a `ripple` input that wins over it. Not the `gogRipple` directive — writing that attribute is already the per-element decision. |
|
|
313
|
+
| `inputfield` | `showSpinButtons` | `gog-inputfield`. |
|
|
314
|
+
| `textarea` | `resize` | `gog-textarea`. |
|
|
315
|
+
| `paginator` | `showPageSizeSelect`, `pageSizeOptions` | `gog-paginator`, and through it `gog-table`'s built-in pagination. |
|
|
316
|
+
| `toast` | `position`, `duration` | `ToastService`. |
|
|
317
|
+
| `theme` | `storageKey`, `defaultTheme`, `followSystem`, `lightTheme`, `darkTheme` | `ThemeService`. All off/neutral by default — see below. |
|
|
318
|
+
| `labels` | every fixed string the library renders — see below | inputfield, textarea, select, multiselect, autocomplete, datepicker, calendar, paginator, table, `DialogService`, `ToastService`. |
|
|
301
319
|
|
|
302
320
|
Anything visual does **not** belong here — override the `--gog-*` token instead.
|
|
303
321
|
|
|
@@ -483,22 +501,22 @@ Every component below is exported from `@guildofgleks/ui`'s root — `import { X
|
|
|
483
501
|
|
|
484
502
|
#### `gog-button`
|
|
485
503
|
|
|
486
|
-
| Input
|
|
487
|
-
|
|
|
488
|
-
| `variant`
|
|
489
|
-
| `severity`
|
|
490
|
-
| `size`
|
|
491
|
-
| `disabled`
|
|
492
|
-
| `fullWidth`
|
|
493
|
-
| `type`
|
|
494
|
-
| `loading`
|
|
495
|
-
| `debounce`
|
|
496
|
-
| `ariaLabel`
|
|
497
|
-
| `ariaPressed`
|
|
498
|
-
| `ariaExpanded` | `boolean \| null`
|
|
499
|
-
| `ariaControls` | `string \| null`
|
|
500
|
-
| `ariaHasPopup` | `GogAriaHasPopup \| null`
|
|
501
|
-
| `ripple`
|
|
504
|
+
| Input | Type | Default | Notes |
|
|
505
|
+
| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------- |
|
|
506
|
+
| `variant` | `GogVariant` | `'primary'` | |
|
|
507
|
+
| `severity` | `GogSeverity` | `'accent'` | what the action means; orthogonal to `variant` — see below |
|
|
508
|
+
| `size` | `GogSize \| undefined` | `'md'` | via `GOG_CONFIG.control.size` |
|
|
509
|
+
| `disabled` | `boolean` | `false` | |
|
|
510
|
+
| `fullWidth` | `boolean` | `false` | |
|
|
511
|
+
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | |
|
|
512
|
+
| `loading` | `boolean` | `false` | shows an inline `gog-spinner`, blocks clicks |
|
|
513
|
+
| `debounce` | `number \| undefined` | `300` | ms; via `GOG_CONFIG.button.debounce` — see note below |
|
|
514
|
+
| `ariaLabel` | `string \| null` | `null` | **use this, not a raw `aria-label` attribute** |
|
|
515
|
+
| `ariaPressed` | `boolean \| 'mixed' \| null` | `null` | toggle button; `false` renders `aria-pressed="false"` |
|
|
516
|
+
| `ariaExpanded` | `boolean \| null` | `null` | disclosure / popup trigger |
|
|
517
|
+
| `ariaControls` | `string \| null` | `null` | id of the controlled element; pairs with `ariaExpanded` |
|
|
518
|
+
| `ariaHasPopup` | `GogAriaHasPopup \| null` | `null` | `boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog'` |
|
|
519
|
+
| `ripple` | `boolean \| undefined` | `false` | press ripple; via `GOG_CONFIG.ripple.enabled` |
|
|
502
520
|
|
|
503
521
|
Outputs: `gogClick: MouseEvent`.
|
|
504
522
|
|
|
@@ -518,7 +536,7 @@ claim, so nothing has to opt out of a severity it does not have. `GogSeverity` i
|
|
|
518
536
|
Two colour rules are worth knowing before you override anything. A **filled** severity button's
|
|
519
537
|
label is `--gog-<status>-text-color`, which each theme states for its own hue — `material` and
|
|
520
538
|
`primeng` put near-black on their bright ones, the rest white — and hover and press deepen the
|
|
521
|
-
fill
|
|
539
|
+
fill _away_ from that label (`--gog-<status>-shade`), so a state always makes the label easier to
|
|
522
540
|
read rather than harder. A **transparent** one's label is `--gog-button-<status>-ink`: the status
|
|
523
541
|
hue mixed halfway toward the page's ink, because the raw hue is legible body text in only five of
|
|
524
542
|
the eleven shipped themes. Override `--gog-button-<status>-ink` if your own theme wants more
|
|
@@ -557,8 +575,13 @@ gogButton>`, as its own example shows, not on a `<gog-button>`.
|
|
|
557
575
|
```html
|
|
558
576
|
<gog-button [ariaPressed]="mirrored()" (gogClick)="toggleMirror()">Mirror</gog-button>
|
|
559
577
|
|
|
560
|
-
<gog-button
|
|
561
|
-
|
|
578
|
+
<gog-button
|
|
579
|
+
[ariaExpanded]="open()"
|
|
580
|
+
ariaControls="filters"
|
|
581
|
+
ariaHasPopup="dialog"
|
|
582
|
+
(gogClick)="open.set(!open())"
|
|
583
|
+
>Filters</gog-button
|
|
584
|
+
>
|
|
562
585
|
```
|
|
563
586
|
|
|
564
587
|
**The press is a colour, not only a movement.** `:active` deepens the button's background (and
|
|
@@ -725,6 +748,14 @@ CVA: yes, both. Slots (shared): `<ng-template gogDropdownChevron>` (custom chevr
|
|
|
725
748
|
`<ng-template gogDropdownOption let-opt let-selected="selected" let-label="label">` (custom
|
|
726
749
|
option row). Multiselect adds `<ng-template gogMultiselectClearIcon>`.
|
|
727
750
|
|
|
751
|
+
**Turn `filter` on past about seven options — or order them instead.** Choice time grows with the
|
|
752
|
+
log of the count (`T = b · log₂(n + 1)`), so beyond roughly seven a panel stops being scanned and
|
|
753
|
+
starts being read. The escape is not always the filter box: the law governs _unordered_ choices,
|
|
754
|
+
and a list the reader can predict — alphabetical countries, ascending amounts, a familiar fixed
|
|
755
|
+
sequence — is one they search rather than choose from, so ordering it well is worth as much as
|
|
756
|
+
filtering it. Both, for a long list of neither. `GOG_CONFIG.dropdown.filter` sets this once for
|
|
757
|
+
the app rather than per dropdown, which is usually the right place for it.
|
|
758
|
+
|
|
728
759
|
```html
|
|
729
760
|
<gog-select
|
|
730
761
|
label="Region"
|
|
@@ -1204,7 +1235,7 @@ defaults: neither has a config key to fall through to.
|
|
|
1204
1235
|
the value — `showValue` is off by default — and the fill and the track cannot carry it themselves:
|
|
1205
1236
|
in every shipped theme the five fills straddle mid-luminance, so no one track colour clears WCAG
|
|
1206
1237
|
1.4.11's 3:1 against all of them. Two tones always do, and `check:contrast` gates the pair. Retint
|
|
1207
|
-
them per theme if you like; keep them a
|
|
1238
|
+
them per theme if you like; keep them a _pair_ whose tones sit on opposite sides of the middle, or
|
|
1208
1239
|
the marker disappears on whichever fill it happens to match.
|
|
1209
1240
|
|
|
1210
1241
|
#### `gog-divider`
|
|
@@ -1712,7 +1743,7 @@ region — the library's official recommendation over a raw `overflow-x`/`overfl
|
|
|
1712
1743
|
| `horizontalWheel` | `boolean \| undefined` | `false`; via `GOG_CONFIG.scroll.horizontalWheel` |
|
|
1713
1744
|
|
|
1714
1745
|
**`horizontalWheel` turns a vertical wheel into horizontal scrolling** (21.9.0), for the case a
|
|
1715
|
-
consumer hits first: hover a horizontal-only row, turn the wheel, and the
|
|
1746
|
+
consumer hits first: hover a horizontal-only row, turn the wheel, and the _page_ moves. That is
|
|
1716
1747
|
the browser's own behaviour and the component deliberately did nothing about it until now.
|
|
1717
1748
|
|
|
1718
1749
|
It is off by default because it changes what an existing instance does with a gesture it
|