@guildofgleks/ui 21.5.2 → 21.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guildofgleks/ui",
-  "version": "21.5.2",
+  "version": "21.6.0",
   "engines": {
     "node": ">=20.19.0"
   },

package/styles/button.css

@@ -67,7 +67,24 @@
     color var(--gog-button-transition-duration) var(--gog-easing);
 }
 
-.gog-btn:focus-visible {
+/*
+ * The doubled class on this rule and the disabled one below is deliberate, and the only two
+ * rules in this file that need it.
+ *
+ * `[gogButton]` goes on the *consumer's* own element, which is the element they style — and
+ * Angular's emulated encapsulation stamps `[_ngcontent-…]` onto every rule in a component
+ * stylesheet, so an ordinary `.my-btn { cursor: pointer }` is (0,2,0). That exactly ties
+ * `.gog-btn:disabled` and wins on source order, because this file loads before the app's own
+ * styles. Measured in the showcase: a disabled button went from `not-allowed`/`0.4` to
+ * `pointer`/`1` under a single-class consumer rule — it looked and felt enabled while disabled.
+ *
+ * `:hover` and `:active` below need no help: their `:not(:disabled)` already makes them (0,3,0).
+ * The base `.gog-btn` is left beatable on purpose — restyling the look is the consumer's call.
+ * These two are not look, they are state and focus visibility, and losing them silently is a
+ * correctness and accessibility regression rather than a taste one. A consumer who genuinely
+ * wants to restyle them can still do it by being specific about it.
+ */
+.gog-btn.gog-btn:focus-visible {
   outline: var(--gog-button-focus-ring-width) solid
     var(
       --gog-button-hover-bg,
@@ -114,7 +131,7 @@
   }
 }
 
-.gog-btn:disabled {
+.gog-btn.gog-btn:disabled {
   opacity: var(--gog-button-disabled-opacity);
   cursor: not-allowed;
 }

package/styles/menu.css

@@ -74,18 +74,28 @@
   transition: background-color var(--gog-menu-transition-duration) var(--gog-easing);
 }
 
+/*
+ * Doubled class on the `:focus-visible` and `:disabled` rules, for the reason spelled out in
+ * `button.css`: a menu item is the consumer's own `<button>`, so an ordinary single-class rule
+ * in their component stylesheet ties these at (0,2,0) and wins on source order. The `:hover`
+ * selector is already (0,3,0) through its `:not(:disabled)` and is left alone.
+ *
+ * It matters more here than for a button. The arrow keys step over a disabled item, so an item
+ * that has lost its disabled styling is one the pointer can still see as ordinary while the
+ * keyboard refuses to reach it — the two input methods disagreeing about what exists.
+ */
 .gog-menu__item:hover:not(:disabled),
-.gog-menu__item:focus-visible {
+.gog-menu__item.gog-menu__item:focus-visible {
   background-color: var(--gog-menu-item-hover-bg);
   color: var(--gog-menu-item-hover-color);
 }
 
-.gog-menu__item:focus-visible {
+.gog-menu__item.gog-menu__item:focus-visible {
   outline: var(--gog-menu-focus-ring-width) solid var(--gog-menu-focus-ring);
   outline-offset: calc(var(--gog-menu-focus-ring-width) * -1);
 }
 
-.gog-menu__item:disabled {
+.gog-menu__item.gog-menu__item:disabled {
   color: var(--gog-menu-item-disabled-color);
   opacity: var(--gog-menu-item-disabled-opacity);
   cursor: not-allowed;

package/styles/utilities.css

@@ -19,6 +19,31 @@
   --gog-direction-sign: 1;
 }
 
+/*
+ * Every element the library renders sizes itself border-box, so the package does not depend on
+ * the consumer having a `* { box-sizing: border-box }` reset.
+ *
+ * It used to. `.gog-input__field` is `width: 100%` plus horizontal padding plus a border, so
+ * under the CSS default of `content-box` it overflowed its own container by exactly that much —
+ * measured 20px at `xsm` rising to 48px at `slg`. It stayed invisible for the life of the
+ * package because both apps that render it (`ui-showcase`, and `gleks-ui-lab` since later) carry
+ * a global reset of their own, so the library was only ever *looked at* under border-box.
+ *
+ * Matched on the class prefix rather than by listing elements, because the set that needs it is
+ * exactly "things the library painted" — including the ones that live on a consumer's own
+ * element (`.gog-btn`, `.gog-menu__item`, `.gog-collapsible__trigger`) and would be missed by a
+ * `gog-*` tag list. A consumer's own elements are untouched.
+ *
+ * Specificity is a single class, deliberately: this is a default the library needs, not a
+ * decision it should win. `:where()` would drop it to zero and lose to the UA's own
+ * `content-box`… which is not a thing, but it would also lose to a consumer's `*` reset setting
+ * `content-box` back, and matching that intent is right.
+ */
+[class^='gog-'],
+[class*=' gog-'] {
+  box-sizing: border-box;
+}
+
 [dir='rtl'] {
   --gog-inline-start-side: right;
   --gog-inline-end-side: left;
@@ -171,7 +196,18 @@
   cursor: pointer;
 }
 
-.gog-collapsible__trigger[aria-disabled='true'] {
+/*
+ * Scoped through the host on purpose, for one point of specificity the plain
+ * `.gog-collapsible__trigger[aria-disabled='true']` (0,2,0) does not have.
+ *
+ * The trigger is the *consumer's* element, and Angular's emulated encapsulation stamps
+ * `[_ngcontent-…]` onto every rule in a component stylesheet — so an ordinary
+ * `.my-trigger { cursor: pointer }` in the consumer's own component is also (0,2,0) and wins on
+ * source order, since this file loads before their app's styles. Measured: a disabled trigger
+ * reading `cursor: pointer` while this rule's `opacity` applied, in the showcase's own demo.
+ * A disabled state the consumer has to know to opt out of is not a disabled state.
+ */
+gog-collapsible .gog-collapsible__trigger[aria-disabled='true'] {
   cursor: not-allowed;
   opacity: var(--gog-collapsible-disabled-opacity);
 }

package/types/guildofgleks-ui.d.ts

@@ -282,7 +282,7 @@ declare class AccordionComponent {
      * Left unset by default since not every accordion instance represents document structure
      * (e.g. one nested inside a card).
      */
-    readonly headingLevel: _angular_core.InputSignal<2 | 3 | 4 | 5 | 6 | undefined>;
+    readonly headingLevel: _angular_core.InputSignal<2 | 4 | 3 | 5 | 6 | undefined>;
     /**
      * Two-way bindable set of currently open item ids. Exposed as a model so consumers
      * can drive the accordion externally (e.g. `[(openIds)]="mySet"`) instead of only
@@ -310,6 +310,15 @@ declare class AccordionComponent {
      */
     private readonly autoExpanded;
     protected readonly skeletonRows: _angular_core.Signal<number[]>;
+    /**
+     * Placeholder title widths, cycled by row index.
+     *
+     * Every bar used to be 55%, which reads as a repeating progress artifact rather than as text
+     * that has not arrived — real titles are not all the same length. Cycled rather than random:
+     * a random width would differ between the server-rendered pass and hydration, and would make
+     * every snapshot of this component unstable.
+     */
+    protected skeletonWidth(index: number): string;
     constructor();
     protected isOpen(id: string | number): boolean;
     protected toggle(item: GogAccordionItem): void;
@@ -935,6 +944,18 @@ declare class AutocompleteComponent<TOption = GogDropdownOption, TValue = string
     protected readonly visibleOptions: _angular_core.Signal<TOption[]>;
     protected readonly activeOptionId: _angular_core.Signal<string | null>;
     private searchTimer;
+    /**
+     * True from the first keystroke until the edit is resolved — by blur, Escape, picking an
+     * option, or the clear button. Deliberately a plain field, not a signal: the sync effect below
+     * must not re-run when it changes, only consult it.
+     *
+     * It exists because the effect used to use `!isOpen()` to mean "the user is not mid-edit", and
+     * the panel closes for reasons that are not that. Backspacing the last character takes the text
+     * under `minLength`, which closes the panel — so the effect fired and wrote the selected label
+     * straight back into the field. Nine backspaces on "Amsterdam" left "Amsterdam": the field
+     * could not be cleared at all while a selection was held.
+     */
+    private editing;
     constructor();
     protected isSelected(option: TOption): boolean;
     protected onInput(event: Event): void;
@@ -3671,8 +3692,34 @@ declare class TableComponent<T extends object> {
     readonly loading: _angular_core.InputSignal<boolean>;
     /** Show vertical borders between columns */
     readonly showColumnBorders: _angular_core.InputSignal<boolean>;
-    /** Stick header row to the top of the viewport while scrolling */
+    /**
+     * Stick the header row to the top of the table's own scroll viewport.
+     *
+     * **Needs `maxHeight` to be reliable.** A sticky element resolves against its nearest scroll
+     * container, and the table wraps itself in a `gog-scroll`; the moment that scroller starts
+     * scrolling sideways it is a scroll container on both axes — CSS coerces `overflow-y: visible`
+     * to `auto` beside a scrolling `overflow-x`, and `clip` to `hidden`, so there is no value that
+     * scrolls one axis and stays out of the sticky chain on the other. Without `maxHeight` that
+     * viewport is exactly as tall as its content and never scrolls vertically, so a header pinned
+     * to it rides out of view along with everything else.
+     *
+     * With `maxHeight` set the viewport is the vertical scrollport, and the header pins to it.
+     */
     readonly stickyHeader: _angular_core.InputSignal<boolean>;
+    /**
+     * Caps the table's own scroll viewport, in any CSS length — `'420px'`, `'60vh'`. The table then
+     * owns its vertical scrolling instead of growing to its content and letting an ancestor scroll
+     * it, which is what makes `stickyHeader` work (see above).
+     *
+     * An input rather than a `--gog-table-*` token, even though the value only ever lands in CSS:
+     * it also decides whether the internal scroller handles the vertical axis at all. A capped
+     * viewport has to scroll vertically; an uncapped one must *not* become a scroll container,
+     * because that would put every table in the sticky chain of its own descendants and take the
+     * consumer's own scrolling region out of it. That is behaviour, not appearance.
+     *
+     * `null` leaves the table exactly as it was: viewport at content height, vertical axis inert.
+     */
+    readonly maxHeight: _angular_core.InputSignal<string | null>;
     /** Row density: lg (default) / md (compact) / sm (dense) */
     readonly size: _angular_core.InputSignal<GogSize>;
     /**
@@ -3782,7 +3829,7 @@ declare class TableComponent<T extends object> {
     /** CSS grid-area for the pagination block */
     readonly paginatorGridArea: _angular_core.Signal<"left" | "right" | "center">;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TableComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TableComponent<any>, "gog-table", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "fullWidth": { "alias": "fullWidth"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "showPageSizeSelect": { "alias": "showPageSizeSelect"; "required": false; "isSignal": true; }; "pageSizeOptions": { "alias": "pageSizeOptions"; "required": false; "isSignal": true; }; "lazy": { "alias": "lazy"; "required": false; "isSignal": true; }; "totalRecords": { "alias": "totalRecords"; "required": false; "isSignal": true; }; "interactiveRows": { "alias": "interactiveRows"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "dataKey": { "alias": "dataKey"; "required": false; "isSignal": true; }; "showSelectionColumn": { "alias": "showSelectionColumn"; "required": false; "isSignal": true; }; "showRowNumbers": { "alias": "showRowNumbers"; "required": false; "isSignal": true; }; "showTotal": { "alias": "showTotal"; "required": false; "isSignal": true; }; "emptyPlaceholder": { "alias": "emptyPlaceholder"; "required": false; "isSignal": true; }; "paginatorPosition": { "alias": "paginatorPosition"; "required": false; "isSignal": true; }; "totalPosition": { "alias": "totalPosition"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "showColumnBorders": { "alias": "showColumnBorders"; "required": false; "isSignal": true; }; "stickyHeader": { "alias": "stickyHeader"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, { "pageSize": "pageSizeChange"; "selection": "selectionChange"; "gogSortChange": "gogSortChange"; "gogPageChange": "gogPageChange"; "gogRowClick": "gogRowClick"; }, ["columns"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TableComponent<any>, "gog-table", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "fullWidth": { "alias": "fullWidth"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "showPageSizeSelect": { "alias": "showPageSizeSelect"; "required": false; "isSignal": true; }; "pageSizeOptions": { "alias": "pageSizeOptions"; "required": false; "isSignal": true; }; "lazy": { "alias": "lazy"; "required": false; "isSignal": true; }; "totalRecords": { "alias": "totalRecords"; "required": false; "isSignal": true; }; "interactiveRows": { "alias": "interactiveRows"; "required": false; "isSignal": true; }; "selectionMode": { "alias": "selectionMode"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "dataKey": { "alias": "dataKey"; "required": false; "isSignal": true; }; "showSelectionColumn": { "alias": "showSelectionColumn"; "required": false; "isSignal": true; }; "showRowNumbers": { "alias": "showRowNumbers"; "required": false; "isSignal": true; }; "showTotal": { "alias": "showTotal"; "required": false; "isSignal": true; }; "emptyPlaceholder": { "alias": "emptyPlaceholder"; "required": false; "isSignal": true; }; "paginatorPosition": { "alias": "paginatorPosition"; "required": false; "isSignal": true; }; "totalPosition": { "alias": "totalPosition"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "showColumnBorders": { "alias": "showColumnBorders"; "required": false; "isSignal": true; }; "stickyHeader": { "alias": "stickyHeader"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; }, { "pageSize": "pageSizeChange"; "selection": "selectionChange"; "gogSortChange": "gogSortChange"; "gogPageChange": "gogPageChange"; "gogRowClick": "gogRowClick"; }, ["columns"], never, true, never>;
 }
 
 declare class SpinnerComponent {