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

@truenas/ui-components 0.7.9 → 0.7.10

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 +260 -15
package/fesm2022/truenas-ui-components.mjs.map +1 -1
package/package.json +1 -1
package/types/truenas-ui-components.d.ts +141 -6

package/package.json CHANGED Viewed

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

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

@@ -14831,15 +14831,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 +14926,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 +15035,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 +15130,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;