@guildofgleks/ui 21.4.4 → 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.
Files changed (22) hide show
  1. package/AGENTS.md +135 -21
  2. package/CHANGELOG.md +251 -17
  3. package/README.md +73 -26
  4. package/TOKENS.md +44 -44
  5. package/fesm2022/guildofgleks-ui.mjs +2068 -376
  6. package/fesm2022/guildofgleks-ui.mjs.map +1 -1
  7. package/package.json +9 -10
  8. package/styles/button.css +112 -79
  9. package/styles/index.css +2 -0
  10. package/styles/menu.css +104 -0
  11. package/styles/theme.css +301 -235
  12. package/styles/utilities.css +27 -0
  13. package/types/guildofgleks-ui.d.ts +285 -138
  14. package/src/styles/button.css +0 -193
  15. package/src/styles/fonts.css +0 -16
  16. package/src/styles/index.css +0 -19
  17. package/src/styles/presets/one-dark.css +0 -48
  18. package/src/styles/presets/one-light.css +0 -47
  19. package/src/styles/presets/slate.css +0 -55
  20. package/src/styles/theme.css +0 -1702
  21. package/src/styles/typography.css +0 -15
  22. package/src/styles/utilities.css +0 -185
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**. 27 components, 5 directives and
10
- 3 services, all standalone, all signal-based, themed entirely through CSS custom properties.
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
 
@@ -56,9 +59,6 @@ use — without it they render unstyled.
56
59
  ]
57
60
  ```
58
61
 
59
- > Up to 21.3.1 these files shipped under `@guildofgleks/ui/src/styles/…`. That path keeps working
60
- > until 21.5.0; new setups should use the shorter one.
61
-
62
62
  **2. Import components where you use them** — each is standalone:
63
63
 
64
64
  ```ts
@@ -96,6 +96,18 @@ export class App {}
96
96
  One `<gog-dialog />` hosts every dialog (they stack); one `<gog-toast-container />` hosts all
97
97
  four toast corners.
98
98
 
99
+ ## Right-to-left
100
+
101
+ **RTL is supported.** Set `dir="rtl"` on `<html>` (or on any subtree) and every component
102
+ mirrors: stylesheets use logical properties, portaled panels and tooltip bubbles copy a scoped
103
+ `dir` onto themselves, a tooltip's `position="auto"` prefers the mirrored horizontal side, and
104
+ the calendar's month arrows turn around.
105
+
106
+ Two things stay physical on purpose, because they are physical words in the API: a tooltip's
107
+ explicit `position="left"`/`"right"`, and a toast's `top-left`/`top-right`/`bottom-left`/
108
+ `bottom-right` corner. `"auto"` is the direction-aware tooltip placement; pick the corner you
109
+ want for a toast.
110
+
99
111
  ## Theming
100
112
 
101
113
  Every value the components paint with lives in `styles/theme.css`, in three layers:
@@ -103,13 +115,13 @@ Every value the components paint with lives in `styles/theme.css`, in three laye
103
115
  **Foundation** — palette, type scale, spacing, motion. Override these to restyle everything at
104
116
  once; component tokens derive from them, so a palette swap carries through on its own.
105
117
 
106
- **Component** — `--gog-<block>-*`, one block per component, to restyle a single component
107
- app-wide:
118
+ **Component** — `--gog-<component>-*`, one block per component, named after the component you
119
+ write in markup (`gog-button` → `--gog-button-*`), to restyle a single component app-wide:
108
120
 
109
121
  ```css
110
122
  :root[data-theme='mine'] {
111
- --gog-btn-font-family: var(--gog-font-body);
112
- --gog-btn-ghost-hover-bg: color-mix(in srgb, var(--gog-accent-color) 20%, transparent);
123
+ --gog-button-font-family: var(--gog-font-body);
124
+ --gog-button-ghost-hover-bg: color-mix(in srgb, var(--gog-accent-color) 20%, transparent);
113
125
  --gog-table-hover-bg: var(--gog-hover-color);
114
126
  }
115
127
  ```
@@ -119,10 +131,21 @@ variant and size classes:
119
131
 
120
132
  ```css
121
133
  .my-form gog-button {
122
- --gog-btn-bg: rebeccapurple; /* wins over .gog-btn--primary */
134
+ --gog-button-bg: rebeccapurple; /* wins over .gog-btn--primary */
123
135
  }
124
136
  ```
125
137
 
138
+ > **Renamed in 21.5.0.** Three prefixes were abbreviated and are now spelled out:
139
+ > `--gog-btn-*` → `--gog-button-*`, `--gog-confirm-*` → `--gog-confirmation-dialog-*`, and
140
+ > `--gog-ms-*` → `--gog-multiselect-*` (that one since 21.3.0). **The old spellings still work**
141
+ > — every new name derives from its old twin — and are **removed in 21.7.0**. A CSS override that
142
+ > stops being read fails silently, which is why the window is two minors rather than one.
143
+ >
144
+ > One prefix that looks abbreviated and is not: **`--gog-input-*`**. It names the shared
145
+ > text-field block that both `gog-inputfield` and `gog-textarea` render (`.gog-input__field`), not
146
+ > the `gog-inputfield` component — the two are meant to restyle together from one token set, so
147
+ > there is no `--gog-inputfield-*` and there will not be one.
148
+
126
149
  Every group and token name is in **[`TOKENS.md`](./TOKENS.md)**, generated from `theme.css` so it
127
150
  cannot drift, and available at runtime as `GOG_TOKEN_GROUPS`.
128
151
 
@@ -186,24 +209,48 @@ provideGogIcons({ cart: '<svg viewBox="0 0 24 24">…</svg>' });
186
209
  <gog-icon name="cart" /> <gog-tag iconName="cart">In basket</gog-tag>
187
210
  ```
188
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
+
189
235
  ## Components
190
236
 
191
- | Group | Components |
192
- | --- | --- |
193
- | 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` |
194
- | Actions | `gog-button`, `gog-chip` |
195
- | Data | `gog-table` (+ `gog-column`), `gog-paginator`, `gog-tag` |
196
- | Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-divider`, `gog-scroll` |
197
- | Overlays | `gog-dialog`, `gog-confirmation-dialog`, `gog-toast` (+ `gog-toast-container`) |
198
- | Feedback | `gog-spinner`, `gog-spinner-overlay`, `gog-progressbar`, `gog-skeleton` |
199
- | Content | `gog-icon` |
237
+ | Group | Components |
238
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
239
+ | 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` |
240
+ | Actions | `gog-button`, `gog-chip` |
241
+ | Data | `gog-table` (+ `gog-column`), `gog-paginator`, `gog-tag` |
242
+ | Layout & disclosure | `gog-accordion`, `gog-tabs` (+ `gog-tab`), `gog-collapsible`, `gog-divider`, `gog-scroll` |
243
+ | Overlays | `gog-dialog`, `gog-confirmation-dialog`, `gog-toast` (+ `gog-toast-container`), `gog-menu` (+ `gogMenuTrigger` / `gogMenuItem`) |
244
+ | Feedback | `gog-spinner`, `gog-spinner-overlay`, `gog-progressbar`, `gog-skeleton` |
245
+ | Content | `gog-icon` |
200
246
 
201
247
  **Directives:** `gogButton` (a link that looks like a button), `gogTooltip`, `gogBadge`,
202
248
  `gogCollapsibleTrigger`, `gogCollapsibleContent`.
203
249
  **Services:** `DialogService`, `ToastService`, `ThemeService`.
204
250
 
205
- Fifteen more slot directives replace a component's markup rather than configuring it —
206
- `gogColumnBody`, `gogInputAddonStart`, `gogDropdownOption` and friends.
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`.
207
254
 
208
255
  A few things worth knowing before you reach for a workaround:
209
256
 
@@ -223,11 +270,11 @@ A few things worth knowing before you reach for a workaround:
223
270
 
224
271
  ## Documentation
225
272
 
226
- | | |
227
- | --- | --- |
228
- | **[`AGENTS.md`](./AGENTS.md)** | the full API reference — every input, output, slot, type and default, per component. Ships in this package. |
229
- | **[`TOKENS.md`](./TOKENS.md)** | every `--gog-*` token, generated from `theme.css` |
230
- | [CHANGELOG](https://github.com/GuildOfGleks/gleks_web_ui/blob/master/projects/gleks/ui/CHANGELOG.md) | release history |
273
+ | | |
274
+ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
275
+ | **[`AGENTS.md`](./AGENTS.md)** | the full API reference — every input, output, slot, type and default, per component. Ships in this package. |
276
+ | **[`TOKENS.md`](./TOKENS.md)** | every `--gog-*` token, generated from `theme.css` |
277
+ | [CHANGELOG](https://github.com/GuildOfGleks/gleks_web_ui/blob/master/projects/gleks/ui/CHANGELOG.md) | release history |
231
278
 
232
279
  `AGENTS.md` is written for an AI coding assistant working in your project, but it is the most
233
280
  complete API reference either way — point your assistant at it and it will stop guessing.