npm - @truenas/ui-components - Versions diffs - 0.7.9 → 0.7.11 - Mend

@truenas/ui-components 0.7.9 → 0.7.11

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 (4) hide show

package/fesm2022/truenas-ui-components.mjs +640 -53
package/fesm2022/truenas-ui-components.mjs.map +1 -1
package/package.json +1 -1
package/types/truenas-ui-components.d.ts +296 -7

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/types/truenas-ui-components.d.ts CHANGED Viewed

@@ -562,12 +562,34 @@ declare class TnSelectComponent<T = unknown> implements ControlValueAccessor, On
      * - **Enter / Space** opens the dropdown if closed; if open and an option
      *   is highlighted, selects that option (in single mode) or toggles it
      *   (in multiple mode).
-     * - **Escape** closes the dropdown without changing the selection.
+     * - **Escape** is NOT here: it closes the dropdown without changing the
+     *   selection, from `onHostKeydown` on this component's host element,
+     *   because it also has to consume the key.
      *
      * All navigation keys call `event.preventDefault()` so the page does not
      * scroll while the user is moving through options.
      */
     onKeydown(event: KeyboardEvent): void;
+    /**
+     * Escape, which closes the dropdown and CONSUMES the key.
+     *
+     * Consuming matters because of what is usually underneath: since #322 a
+     * `tn-side-panel` is a CDK overlay listening for Escape through
+     * `OverlayKeyboardDispatcher`, which delivers to the top-most attached
+     * overlay that has subscribers. Closing the dropdown disposes this select's
+     * overlay mid-keystroke, taking it out of that stack — so an Escape left to
+     * carry on reached `<body>`, found the panel as the new top-most subscriber,
+     * and closed the whole form along with the dropdown (#324). A `tn-drawer` in
+     * `over` mode has a keydown handler of its own and closed the same way.
+     *
+     * Why this sits on the HOST rather than beside the other keys on the trigger:
+     * `stopPropagation()` stops ANCESTOR listeners, not other listeners on the
+     * same element. Called from the trigger it also hid Escape from a `tnTooltip`
+     * on this component, which dismisses a visible tooltip from a host listener —
+     * so the tooltip stayed up. From here, that directive still sees the key and
+     * only the containers ABOVE this select stop seeing it.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     private moveFocus;
     private activateFocusedOption;
     private scrollFocusedIntoView;
@@ -1146,6 +1168,31 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
      */
     private runAction;
     onKeydown(event: KeyboardEvent): void;
+    /**
+     * Escape, which cancels the draft, dismisses the panel, and — while the panel
+     * is open — CONSUMES the key.
+     *
+     * Consuming matters because of what is usually underneath: since #322 a
+     * `tn-side-panel` is a CDK overlay listening for Escape through
+     * `OverlayKeyboardDispatcher`, which delivers to the top-most attached
+     * overlay that has subscribers. Dismissing disposes this panel's overlay
+     * mid-keystroke, taking it out of that stack — so an Escape left to carry on
+     * reached `<body>`, found the side panel as the new top-most subscriber, and
+     * closed the whole form along with the panel (#324). A `tn-drawer` in `over`
+     * mode has a keydown handler of its own and closed the same way.
+     *
+     * With the panel already closed the key is NOT consumed: there is nothing to
+     * dismiss and it belongs to whatever contains this field. The draft still
+     * reverts, which is what the blur that follows would otherwise commit.
+     *
+     * Why this sits on the HOST rather than beside the other keys on the input:
+     * `stopPropagation()` stops ANCESTOR listeners, not other listeners on the
+     * same element. Called from the input it also hid Escape from a `tnTooltip`
+     * on this component, which dismisses a visible tooltip from a host listener —
+     * so the tooltip stayed up. From here, that directive still sees the key and
+     * only the containers ABOVE this field stop seeing it.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     /**
      * `loadMore` normally fires from a scroll event, which never happens when
      * the current page is too short to overflow the panel — pagination would
@@ -1264,6 +1311,13 @@ declare class TnAutocompleteComponent<T = unknown> implements ControlValueAccess
      * matches its width to the input. Mirrors TnSelectComponent's approach.
      */
     private attachOverlay;
+    /**
+     * Escape's effect on this field: cancel the draft, then close.
+     *
+     * Shared by the overlay subscription above and `onHostKeydown`, which is
+     * where Escape arrives while focus is in the field — open panel or closed.
+     */
+    private dismiss;
     private detachOverlay;
     private scrollToHighlighted;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnAutocompleteComponent<any>, never>;
@@ -4389,6 +4443,29 @@ declare class TnChipInputComponent<T = string> implements ControlValueAccessor,
     protected onFocus(): void;
     protected onBlur(): void;
     protected onKeydown(event: KeyboardEvent): void;
+    /**
+     * Escape, which dismisses the suggestion panel and CONSUMES the key.
+     *
+     * Consuming matters because of what is usually underneath: since #322 a
+     * `tn-side-panel` is a CDK overlay listening for Escape through
+     * `OverlayKeyboardDispatcher`, which delivers to the top-most attached
+     * overlay that has subscribers. Dismissing disposes this panel's overlay
+     * mid-keystroke, taking it out of that stack — so an Escape left to carry on
+     * reached `<body>`, found the side panel as the new top-most subscriber, and
+     * closed the whole form along with the panel (#324). A `tn-drawer` in `over`
+     * mode has a keydown handler of its own and closed the same way.
+     *
+     * With the panel already closed nothing happens here and the key belongs to
+     * whatever contains this field — which is what it did before #324 too.
+     *
+     * Why this sits on the HOST rather than beside the other keys on the input:
+     * `stopPropagation()` stops ANCESTOR listeners, not other listeners on the
+     * same element. Called from the input it also hid Escape from a `tnTooltip`
+     * on this component, which dismisses a visible tooltip from a host listener —
+     * so the tooltip stayed up. From here, that directive still sees the key and
+     * only the containers ABOVE this field stop seeing it.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     protected onSuggestionClick(option: TnChipInputOption<T>): void;
     /** Prevents the option `mousedown` from blurring the input before the click lands. */
     protected onSuggestionMousedown(event: MouseEvent): void;
@@ -4778,6 +4855,7 @@ declare class TnMenuComponent implements OnDestroy {
     contextMenuTemplate: _angular_core.Signal<TemplateRef<unknown>>;
     private contextOverlayRef?;
     private contextBackdropSub?;
+    private contextKeydownSub?;
     private overlay;
     private viewContainerRef;
     onMenuItemClick(item: TnMenuItem): void;
@@ -12639,6 +12717,25 @@ declare class TnDateRangeInputComponent implements ControlValueAccessor, OnInit,
     private updateDateFromSegments;
     private focusNextSegment;
     private focusPrevSegment;
+    /**
+     * Escape, which closes the calendar and CONSUMES the key. Same reasoning as
+     * `TnDateInputComponent.onHostKeydown`, which this mirrors: opening does not
+     * move focus into the overlay, so the real keystroke starts on a date
+     * segment inside this host, where an ancestor such as a `tn-drawer` in
+     * `over` mode would stop it before CDK's keyboard dispatcher ever ran — and
+     * a calendar waiting on the dispatcher stayed open while the drawer closed
+     * underneath it (#324).
+     *
+     * Consuming it also keeps a `tn-side-panel` from acting on the same key: the
+     * panel is a CDK overlay subscribed through that dispatcher (#322), and
+     * closing this calendar disposes its overlay mid-keystroke, leaving the
+     * panel as the top-most subscriber for an Escape allowed to carry on.
+     *
+     * Closed, the key is not consumed; it belongs to whatever contains this
+     * field. On the HOST rather than the segments so that `stopPropagation()`
+     * still leaves a `tnTooltip` on this component able to see the key.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     openDatepicker(): void;
     close(): void;
     private createOverlay;
@@ -13404,6 +13501,34 @@ declare class TnDateInputComponent implements ControlValueAccessor, OnInit, OnDe
     private updateDateFromSegments;
     private focusNextSegment;
     private focusPrevSegment;
+    /**
+     * Escape, which closes the calendar and CONSUMES the key.
+     *
+     * Opening the calendar does not move focus into it, so the keystroke a user
+     * actually makes starts on a date segment — inside this host, not inside the
+     * overlay. That is the path the `keydownEvents()` subscription in
+     * `createOverlay` cannot serve: CDK's `OverlayKeyboardDispatcher` listens on
+     * `<body>`, so any ancestor that stops the key first means it never runs.
+     * `tn-drawer` in `over` mode is exactly such an ancestor — it calls
+     * `stopPropagation()` on Escape from a handler on its own panel element — so
+     * a calendar left waiting for the dispatcher stayed open while the drawer
+     * closed underneath it (#324).
+     *
+     * Consuming it also keeps a `tn-side-panel` from acting on the same key:
+     * since #322 the panel is a CDK overlay subscribed through that dispatcher,
+     * and closing this calendar disposes its overlay mid-keystroke, leaving the
+     * panel as the top-most subscriber for an Escape allowed to carry on.
+     *
+     * With the calendar closed the key is NOT consumed: there is nothing to
+     * close and it belongs to whatever contains this field.
+     *
+     * Why the HOST rather than the segment inputs: `stopPropagation()` stops
+     * ANCESTOR listeners, not other listeners on the same element. From here a
+     * `tnTooltip` on this component still sees Escape and dismisses itself, and
+     * only the containers ABOVE this field stop seeing it — the same placement
+     * `tn-select` and `tn-autocomplete` use.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     openDatepicker(): void;
     close(): void;
     private createOverlay;
@@ -14831,15 +14956,89 @@ declare class TnSidePanelHeaderActionDirective {
  * own, focus it yourself once the panel is open; the component leaves focus
  * alone as soon as it is inside the panel. `lib/a11y/initial-focus.ts` holds
  * the reasoning for capturing the container rather than a control.
+ *
+ * WHERE IT RENDERS, AND WHY THAT DECIDES WHAT IT STACKS AGAINST
+ * ------------------------------------------------------------
+ * The panel renders through a CDK `OverlayRef` created WHEN IT OPENS (#322),
+ * which is what makes it stack with `TnDialog`, `tn-menu` and tooltips by open
+ * order: whatever attached last paints on top, in both directions. It used to
+ * append its overlay to `<body>` at construction time with a fixed `z-index`,
+ * and the CDK overlay container is a `<body>` child with the same one — so the
+ * winner was whichever element `<body>` happened to receive last, which follows
+ * nothing a caller can see. A panel opened FROM a dialog landed under that
+ * dialog's backdrop; on a browser with the popover API, where CDK puts its
+ * overlays in the top layer, no `z-index` on a `<body>` child could have won at
+ * all.
+ *
+ * Three things follow from being a CDK overlay, and each replaces something
+ * this component used to do for itself:
+ *
+ * - **Escape reaches the topmost overlay only**, through CDK's
+ *   `OverlayKeyboardDispatcher`, rather than through a `keydown` handler on the
+ *   panel that stopped propagation to keep a dialog underneath from closing too.
+ *   The panel therefore also closes on Escape pressed outside it, which is what
+ *   `TnDialog` does — `tn-drawer` still binds `keydown` on its own panel and
+ *   does not.
+ * - **A CDK dialog opened over an open panel hides the panel from assistive
+ *   technology.** CDK does this by sweeping the overlay container's SIBLINGS,
+ *   which no longer includes the panel, so the component tracks it — see
+ *   `dialogsAbove`.
+ * - **A consumer no longer re-homes the overlay or overrides its `z-index` and
+ *   `pointer-events`.** There is no `z-index` on it any more; the CDK pane it
+ *   lives in carries the stacking.
  */
 declare class TnSidePanelComponent implements OnDestroy {
     private iconRegistry;
     private document;
     private destroyRef;
+    private injector;
+    private dialog;
     private overlayRef;
     private panelRef;
     private contentRef;
     protected initialized: _angular_core.WritableSignal<boolean>;
+    /**
+     * The CDK overlay currently hosting `overlayRef`'s element, or `null` while
+     * the panel is closed (#322).
+     *
+     * **Created on open and disposed once the close has settled**, not once for
+     * the component's lifetime. That is the whole mechanism: CDK decides stacking
+     * by the order overlays ATTACH — `showPopover()` order in the top layer, and
+     * `_updateStackingOrder()`'s move to the end of the container where the
+     * popover API is missing — so an overlay created when the component was built
+     * would stack by construction order, which for a panel rendered inside a
+     * dialog is exactly backwards.
+     *
+     * Non-null is therefore also the answer to "is this panel currently one of
+     * the overlays on screen", which is what `dialogsAbove` keys off.
+     */
+    private cdkOverlay;
+    /** Escape handling for the overlay above, dropped with it. */
+    private keydowns;
+    /**
+     * The CDK dialogs currently covering this panel (#322).
+     *
+     * The panel is hidden from assistive technology while this is non-empty,
+     * which is what CDK's own `Dialog` does for everything outside the overlay
+     * container — it sweeps the container's SIBLINGS, and a panel that now lives
+     * INSIDE the container is not one. A dialog already open when the panel opens
+     * is underneath it and never joins this; only dialogs that arrive afterwards
+     * are above.
+     *
+     * A SET RATHER THAN A COUNT, and each dialog removes ITSELF. Nothing
+     * unsubscribes a dialog's `closed` when the panel closes underneath it — the
+     * panel cannot outlive its own release to do that — so with a count, a
+     * dialog opened during one open and closed during the NEXT one decremented a
+     * tally it had never contributed to, and put the panel back in the
+     * accessibility tree with a live modal still stacked over it. Removing a
+     * member that is not there is a no-op, which is the property a count does
+     * not have.
+     *
+     * Emptied only when the last one goes, on the same reasoning as CDK's
+     * `_removeOpenDialog`: two stacked dialogs closing one at a time must not
+     * un-hide the panel while one is still covering it.
+     */
+    private dialogsAbove;
     /**
      * Whether the content region carries the tab stop, its role and its name
      * (#248) — which is NOT the same question as whether it currently overflows.
@@ -14852,10 +15051,14 @@ declare class TnSidePanelComponent implements OnDestroy {
      * answer is held true while the region has focus, and why `role` and
      * `aria-label` are gated on the same signal as `tabindex` rather than left on.
      *
-     * Read in `afterNextRender`, which is where the helper takes its first
-     * measurement — before the overlay is portaled to `<body>` below, which does
-     * not affect it: `.tn-side-panel__overlay` is `position: fixed; inset: 0`, so
-     * its size comes from the viewport rather than from its parent.
+     * The helper's FIRST measurement reads a closed panel, which is
+     * `display: none` since #322 and so reads as not overflowing. That is the
+     * right answer for a panel nobody can reach yet, and it does not stick: the
+     * helper's `ResizeObserver` fires when the overlay attaches and the region
+     * gets a box, which is the same instrument that already answered a viewport
+     * resize. Once open, `.tn-side-panel__overlay` is `position: fixed;
+     * inset: 0`, so the region's size comes from the viewport rather than from
+     * whichever CDK pane is hosting it.
      */
     protected contentKeyboardReachable: _angular_core.Signal<boolean>;
     open: _angular_core.ModelSignal<boolean>;
@@ -14957,19 +15160,75 @@ declare class TnSidePanelComponent implements OnDestroy {
      * fallback and raises no warning.
      */
     protected resolvedAriaLabel: _angular_core.Signal<string | null>;
+    /**
+     * Whether the overlay is out of the accessibility tree: closed, or covered by
+     * a CDK dialog that opened over it (#322).
+     *
+     * The two are one attribute because they are one question, and rendering them
+     * from separate bindings would mean the second could clear the first.
+     */
+    protected hiddenFromAssistiveTech: _angular_core.Signal<boolean>;
     private previouslyFocusedElement;
     /**
      * Decides when an open or a close counts as finished, so that the outputs
      * above fire exactly once per change whether or not a transition ran. A field
      * initializer rather than the constructor, because it registers an `effect`
      * and so needs an injection context.
+     *
+     * It is also what times the overlay's release (#322). The CDK overlay has to
+     * outlive the CLOSE — disposing it puts the element back in this component's
+     * view, where it is `display: none`, so doing that the moment `open` goes
+     * false replaces the slide-out with a disappearance. "The close has settled"
+     * is exactly the question this helper already answers, for a transition that
+     * may never fire.
      */
     private lifecycle;
     constructor();
+    /**
+     * Put the overlay on screen, in a CDK overlay created now (#322).
+     *
+     * The three steps are ordered, and the order is the reason this is not two
+     * bindings:
+     *
+     * 1. **Attach**, which is what fixes where the panel sits in the stack.
+     * 2. **Read layout**, which forces the browser to compute the panel's closed
+     *    position in its new home. Without it the attach and the open class land
+     *    in one style update, the browser has no "before" to transition from, and
+     *    the panel appears rather than slides. A deliberate synchronous reflow,
+     *    and the only one: it happens once per open.
+     * 3. **Open**, which is the change the transition runs on.
+     *
+     * Re-entrant on purpose. A panel reopened while its close is still animating
+     * keeps the overlay it already has — the stack has not changed under it, and
+     * `tnTransitionLifecycle` has already cancelled the close that would have
+     * released it.
+     */
+    private showOverlay;
+    /**
+     * Give the CDK overlay back, once the close has finished animating.
+     *
+     * Disposing rather than detaching, so that the next open builds a new overlay
+     * and takes a new place in the stack — see `cdkOverlay`. It restores the
+     * element to this component's own view, where `display: none` keeps it out of
+     * the way until then.
+     */
+    private releaseOverlay;
     ngOnDestroy(): void;
     protected dismiss(): void;
     protected onBackdropClick(): void;
-    protected onKeydown(event: KeyboardEvent): void;
+    /**
+     * Escape, delivered by CDK's `OverlayKeyboardDispatcher` (#322).
+     *
+     * It arrives only while this panel is the topmost attached overlay, so
+     * nothing here has to decide whether the key was meant for something above or
+     * below — which is what the `stopPropagation` this replaced was standing in
+     * for, and it could only ever guard the direction it knew about.
+     *
+     * `preventDefault` rather than `stopPropagation`, matching CDK's own
+     * `DialogRef`: the key has already been routed, and swallowing it would hide
+     * it from a consumer listening at the document for their own reasons.
+     */
+    private onOverlayKeydown;
     protected onTransitionEnd(event: TransitionEvent): void;
     private restoreFocus;
     private registerMdiIcons;
@@ -14996,7 +15255,8 @@ declare class TnSidePanelHarness extends ComponentHarness {
     static hostSelector: string;
     static with(options?: SidePanelHarnessFilters): HarnessPredicate<TnSidePanelHarness>;
     /**
-     * Locate the overlay wrapper, which may be portaled to document.body.
+     * Locate the overlay wrapper, which is portaled into a CDK overlay while the
+     * panel is open and sits inside the host element while it is not.
      * Uses the data-tn-panel attribute to correlate the host with its overlay.
      */
     private getOverlay;
@@ -15333,6 +15593,35 @@ declare class TnFilePickerComponent implements ControlValueAccessor, OnInit, OnD
     onPathCommit(event: Event): void;
     /** `openOnClick` entry point. */
     onInputClick(): void;
+    /**
+     * Escape, which closes the popup and CONSUMES the key.
+     *
+     * Opening the popup does not move focus into it, so the keystroke a user
+     * actually makes starts on the path input — inside this host, not inside the
+     * overlay. That is the path the `keydownEvents()` subscription in
+     * `createOverlay` cannot serve: CDK's `OverlayKeyboardDispatcher` listens on
+     * `<body>`, so any ancestor that stops the key first means it never runs.
+     * `tn-drawer` in `over` mode is exactly such an ancestor — it calls
+     * `stopPropagation()` on Escape from a handler on its own panel element — so
+     * a picker left waiting for the dispatcher stayed open while the drawer
+     * closed underneath it (#324).
+     *
+     * Consuming it also keeps a `tn-side-panel` from acting on the same key:
+     * since #322 the panel is a CDK overlay subscribed through that dispatcher,
+     * and closing this popup disposes its overlay mid-keystroke, leaving the
+     * panel as the top-most subscriber for an Escape allowed to carry on.
+     *
+     * With the popup closed the key is NOT consumed: there is nothing to close
+     * and it belongs to whatever contains this field. The inline-creation row is
+     * unaffected either way — it lives in the popup, whose keydowns never reach
+     * this host.
+     *
+     * Why the HOST rather than the input: `stopPropagation()` stops ANCESTOR
+     * listeners, not other listeners on the same element. From here a `tnTooltip`
+     * on this component still sees Escape and dismisses itself, and only the
+     * containers ABOVE this field stop seeing it.
+     */
+    protected onHostKeydown(event: KeyboardEvent): void;
     openFilePicker(): void;
     close(): void;
     onItemClick(item: FileSystemItem): void;