@guildofgleks/ui 21.5.0 → 21.5.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/AGENTS.md +20 -8
- package/CHANGELOG.md +54 -0
- package/README.md +31 -4
- package/fesm2022/guildofgleks-ui.mjs +78 -17
- package/fesm2022/guildofgleks-ui.mjs.map +1 -1
- package/package.json +1 -1
- package/styles/menu.css +10 -1
- package/types/guildofgleks-ui.d.ts +57 -6
package/AGENTS.md
CHANGED
|
@@ -5,10 +5,10 @@ an app that **consumes** the published `@guildofgleks/ui` npm package. It is not
|
|
|
5
5
|
authoring the library — if you are working inside the `gleks_web_ui` monorepo itself, read
|
|
6
6
|
`.github/instructions/*.md` instead.
|
|
7
7
|
|
|
8
|
-
Everything below reflects the library's actual source as of **`21.
|
|
9
|
-
|
|
10
|
-
and `CHANGELOG.md
|
|
11
|
-
theming, global configuration — and is accurate;
|
|
8
|
+
Everything below reflects the library's actual source as of **`21.5.1`**. 21.5.0 removed a batch
|
|
9
|
+
of deprecated API — see **Removed in 21.5.0** near the end of this file, which exists so code
|
|
10
|
+
written against 21.4.x can be migrated — and `CHANGELOG.md` has the rest. `README.md` covers the
|
|
11
|
+
same ground at a higher level — install, setup, theming, global configuration — and is accurate;
|
|
12
12
|
this file goes further, into per-component input tables, and is the one to trust for exact names,
|
|
13
13
|
types and defaults.
|
|
14
14
|
|
|
@@ -1322,6 +1322,14 @@ Methods (via template ref): `scrollTo(options)`, `scrollToTop()`, `scrollToBotto
|
|
|
1322
1322
|
|
|
1323
1323
|
### Overlays
|
|
1324
1324
|
|
|
1325
|
+
**Overlays and the viewport — the caveat that bites once per project.** `gog-dialog`'s backdrop,
|
|
1326
|
+
`gog-toast-container` and `gog-spinner [overlay]` are `position: fixed`, which covers the viewport
|
|
1327
|
+
only while no ancestor establishes a containing block. `contain`, `transform`, `filter`,
|
|
1328
|
+
`backdrop-filter` or `will-change` anywhere above retargets them to that element's box — and
|
|
1329
|
+
**`gog-scroll` sets `contain: layout style`**, so a dialog opened inside a scroller dims the
|
|
1330
|
+
scroller rather than the page. Place the dialog and toast outlets in the root component. The
|
|
1331
|
+
dropdown panels and `gog-menu` sidestep it by rendering into `<body>`.
|
|
1332
|
+
|
|
1325
1333
|
#### `gog-menu` + `gogMenuTrigger` / `gogMenuItem`
|
|
1326
1334
|
|
|
1327
1335
|
A command menu. The trigger is a directive on **your own button** — usually the icon button you
|
|
@@ -1371,10 +1379,14 @@ there is no input for it:
|
|
|
1371
1379
|
A disabled item stays in the list rather than disappearing (removing it would shift the others
|
|
1372
1380
|
under the pointer), the arrow keys step over it, and clicking it does nothing.
|
|
1373
1381
|
|
|
1374
|
-
**A long menu scrolls itself
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1382
|
+
**A long menu scrolls itself**, using `gog-scroll` — the same thin, auto-hiding scroller as
|
|
1383
|
+
everywhere else in the package, with `overscrollBehavior="contain"` so a wheel at the end of the
|
|
1384
|
+
list does not scroll the page behind it. Arrowing past the last visible item scrolls it into view.
|
|
1385
|
+
|
|
1386
|
+
The panel's height is the smallest of three: its own content, `--gog-menu-max-height` (320px by
|
|
1387
|
+
default), and the room between the trigger and the viewport edge. Lower the token to make a menu
|
|
1388
|
+
scroll sooner. **In 21.5.0 the token did nothing** — the measured room was written onto the panel
|
|
1389
|
+
as an inline `max-height`, which beat it; fixed in 21.5.1.
|
|
1378
1390
|
|
|
1379
1391
|
A closed menu renders nothing at all, so its commands are not in the accessibility tree until it
|
|
1380
1392
|
opens.
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,60 @@ All notable changes to `@guildofgleks/ui` are documented here. Format follows
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project has not yet
|
|
5
5
|
reached 1.0, so breaking changes may land in minor versions.
|
|
6
6
|
|
|
7
|
+
## [21.5.1] - planned
|
|
8
|
+
|
|
9
|
+
Two defects 21.5.0 shipped, both of the same shape: correct-looking CSS whose effect was cancelled
|
|
10
|
+
by something else in the box model, and neither visible to a test suite that runs without a style
|
|
11
|
+
engine. Both were found by opening the components in a browser while writing the documentation
|
|
12
|
+
site's pages for them. No input, output, type or public token changed, so upgrading from 21.5.0 is
|
|
13
|
+
a version bump with nothing to migrate.
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- **`--gog-menu-max-height` now caps the panel.** It never did: `gog-menu` measured the room
|
|
18
|
+
between its trigger and the viewport edge and wrote that onto the panel as an inline
|
|
19
|
+
`max-height`, which beats the stylesheet rule the token feeds. Setting
|
|
20
|
+
`--gog-menu-max-height: 150px` on a page with 500px of room changed nothing, and a menu of any
|
|
21
|
+
length simply grew until it ran out of screen.
|
|
22
|
+
|
|
23
|
+
The measured room is now handed to CSS as `--gog-menu-available-height` and `menu.css` takes the
|
|
24
|
+
smaller of the two, so a panel's height is the least of its content, the token, and the room
|
|
25
|
+
available. Lower the token to make a menu start scrolling sooner.
|
|
26
|
+
|
|
27
|
+
A menu that flips **up** is now anchored by its `bottom` rather than by a `top` computed from
|
|
28
|
+
its expected height. That is what makes the cap safe: with the old arithmetic, a panel the token
|
|
29
|
+
cut short would have floated away from its trigger by exactly the height it did not take.
|
|
30
|
+
|
|
31
|
+
- **Text no longer runs underneath a field's own icon in RTL.** `gog-inputfield`, `gog-select`,
|
|
32
|
+
`gog-autocomplete` and `gog-datepicker` each reserve a gutter for their leading or trailing
|
|
33
|
+
chrome. The chrome is placed with `inset-inline-start` / `inset-inline-end` — logical — but the
|
|
34
|
+
gutter was a physical `padding-left`/`padding-right`, so under `dir="rtl"` the two ended up on
|
|
35
|
+
opposite sides: the icon at one edge, the space kept for it stranded at the other, and the value
|
|
36
|
+
or placeholder rendering under the icon. A floating label offset itself by the wrong gutter for
|
|
37
|
+
the same reason, and a clearable `gog-select` was padded on both sides at once.
|
|
38
|
+
|
|
39
|
+
All four now use `padding-block` + `padding-inline`. `gog-inputfield`'s two internal properties
|
|
40
|
+
are renamed to match what they now mean — `--gog-input-pl`/`-pr` became `--gog-input-ps`/`-pe`
|
|
41
|
+
(inline **start** / **end**). Neither was ever public: they are not in `GogTokenName`, not in
|
|
42
|
+
`TOKENS.md` and not declared in `theme.css`, so nothing a consumer can have written changes.
|
|
43
|
+
Left-to-right rendering is byte-for-byte what it was.
|
|
44
|
+
|
|
45
|
+
**`npm run check:logical-properties` now fails the build** on a `padding`, `margin`,
|
|
46
|
+
`border-width` or `border-radius` shorthand that sets the two horizontal sides differently.
|
|
47
|
+
21.5.0 converted 16 stylesheets to logical properties and still missed these four, because the
|
|
48
|
+
sidedness lives in a value's *position inside a shorthand* rather than in a `left`/`right`
|
|
49
|
+
keyword — invisible to a grep, and invisible to a unit test with no style engine.
|
|
50
|
+
|
|
51
|
+
- **Documented the `position: fixed` containing-block caveat**, in one place plus a line on each
|
|
52
|
+
overlay it affects. `gog-dialog`'s backdrop, `gog-toast-container` and
|
|
53
|
+
`gog-spinner [overlay]` cover the viewport only while no ancestor establishes a containing
|
|
54
|
+
block — `contain`, `transform`, `filter`, `backdrop-filter` or `will-change` above them
|
|
55
|
+
retargets the overlay to that element's box, with no error and no warning. `gog-scroll` sets
|
|
56
|
+
`contain: layout style`, so this library can trigger it on its own: a dialog opened inside a
|
|
57
|
+
scroller dims the scroller. Nothing changed in behaviour; what changed is that the behaviour is
|
|
58
|
+
now written down where you meet it — README's "Overlays and the viewport", `AGENTS.md`, and the
|
|
59
|
+
TSDoc of each overlay.
|
|
60
|
+
|
|
7
61
|
## [21.5.0] - planned
|
|
8
62
|
|
|
9
63
|
**The breaking release** — the one version consumers have to read before upgrading into. It
|
package/README.md
CHANGED
|
@@ -6,8 +6,9 @@
|
|
|
6
6
|
|
|
7
7
|
# @guildofgleks/ui
|
|
8
8
|
|
|
9
|
-
An Angular 21 component library with **no CDK and no Material**.
|
|
10
|
-
3 services, all standalone, all signal-based, themed entirely through CSS custom
|
|
9
|
+
An Angular 21 and 22 component library with **no CDK and no Material**. 29 components, 5
|
|
10
|
+
directives and 3 services, all standalone, all signal-based, themed entirely through CSS custom
|
|
11
|
+
properties.
|
|
11
12
|
|
|
12
13
|
```bash
|
|
13
14
|
npm install @guildofgleks/ui
|
|
@@ -28,6 +29,8 @@ npm install @guildofgleks/ui
|
|
|
28
29
|
(`optionLabel="profile.fullName"`), not a mandated `{ id, name }` DTO.
|
|
29
30
|
- **Accessible by default.** Keyboard navigation, ARIA wiring and generated label associations
|
|
30
31
|
come with the components rather than with extra attributes.
|
|
32
|
+
- **Right-to-left included.** `dir="rtl"` on `<html>` or on any wrapper mirrors every component,
|
|
33
|
+
portaled overlays included. Nothing to configure per component, no second stylesheet.
|
|
31
34
|
|
|
32
35
|
## Setup
|
|
33
36
|
|
|
@@ -206,6 +209,29 @@ provideGogIcons({ cart: '<svg viewBox="0 0 24 24">…</svg>' });
|
|
|
206
209
|
<gog-icon name="cart" /> <gog-tag iconName="cart">In basket</gog-tag>
|
|
207
210
|
```
|
|
208
211
|
|
|
212
|
+
## Overlays and the viewport
|
|
213
|
+
|
|
214
|
+
Three things this library renders cover the **viewport** with `position: fixed`:
|
|
215
|
+
`<gog-dialog />`'s backdrop, `<gog-toast-container />`, and `<gog-spinner [overlay]="true" />`.
|
|
216
|
+
|
|
217
|
+
That is true only while nothing above them establishes a containing block. `contain`,
|
|
218
|
+
`transform`, `filter`, `backdrop-filter` and `will-change` on **any** ancestor silently retarget
|
|
219
|
+
a fixed element to that ancestor's box — a CSS rule with no error and no warning, and the usual
|
|
220
|
+
first sighting is "my modal only dims half the page".
|
|
221
|
+
|
|
222
|
+
It is not hypothetical here: **`gog-scroll` sets `contain: layout style`**, so a dialog opened
|
|
223
|
+
from inside a scroller dims the scroller, and a toast container nested in one corners its toasts
|
|
224
|
+
against the scroller. Two rules keep it simple:
|
|
225
|
+
|
|
226
|
+
- **Place the dialog and toast outlets in your root component**, not inside the section that
|
|
227
|
+
happens to use them. They are singletons anyway — one of each renders everything.
|
|
228
|
+
- **A spinner overlay covers whatever contains it**, which is often what you want inside a card.
|
|
229
|
+
For a genuinely full-screen one, render it at the root too.
|
|
230
|
+
|
|
231
|
+
The dropdown panels (`gog-select`, `gog-multiselect`, `gog-autocomplete`, `gog-datepicker`) and
|
|
232
|
+
`gog-menu` avoid the whole question by rendering into `<body>` — `appendToBody` for the
|
|
233
|
+
dropdowns, always for the menu.
|
|
234
|
+
|
|
209
235
|
## Components
|
|
210
236
|
|
|
211
237
|
| Group | Components |
|
|
@@ -222,8 +248,9 @@ provideGogIcons({ cart: '<svg viewBox="0 0 24 24">…</svg>' });
|
|
|
222
248
|
`gogCollapsibleTrigger`, `gogCollapsibleContent`.
|
|
223
249
|
**Services:** `DialogService`, `ToastService`, `ThemeService`.
|
|
224
250
|
|
|
225
|
-
|
|
226
|
-
`gogColumnBody`, `gogInputAddonStart
|
|
251
|
+
Seventeen more directives go on markup you own rather than configuring a component through an
|
|
252
|
+
input — slots like `gogColumnBody`, `gogInputAddonStart` and `gogDropdownOption`, and the menu's
|
|
253
|
+
`gogMenuTrigger` / `gogMenuItem`.
|
|
227
254
|
|
|
228
255
|
A few things worth knowing before you reach for a workaround:
|
|
229
256
|
|