@memberjunction/ng-ui-components 5.51.0 → 6.1.0-edge.1

package/dist/lib/left-nav/left-nav.component.d.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from '@angular/core';
+import { EventEmitter, OnDestroy } from '@angular/core';
 import * as i0 from "@angular/core";
 /**
  * A single item in an `<mj-left-nav>`.
@@ -86,7 +86,12 @@ export interface MJLeftNavSection {
  * a `@media` override) so the in-flow section switcher stacks above the content
  * pane rather than competing with it for horizontal space.
  */
-export declare class MJLeftNavComponent {
+export declare class MJLeftNavComponent implements OnDestroy {
+    /**
+     * DOM id of the `<aside>`, so the collapse toggle's `aria-expanded` can name the region it
+     * expands via `aria-controls`. Per-instance because a page may host more than one rail.
+     */
+    readonly NavRegionId: string;
     /**
      * The sections + items that make up the rail. Sections render top-to-bottom
      * in array order; items inside each section render in array order.
@@ -103,6 +108,140 @@ export declare class MJLeftNavComponent {
      * the rail becomes a fixed-width off-canvas drawer.
      */
     Width: number;
+    /**
+     * Set by a consumer that has visually collapsed the rail to an icons-only strip (via `Width` plus
+     * its own CSS hiding the labels). When true, each item gains a native `title` tooltip AND an
+     * `aria-label` carrying its full text.
+     *
+     * Why it is opt-in rather than always-on:
+     *  - **Tooltip**: with labels visible, a tooltip that just repeats the label is redundant noise on
+     *    every hover. Icon-only rails everywhere (VS Code's activity bar, Slack, Linear, Jira, Figma)
+     *    show one; expanded rails do not.
+     *  - **aria-label**: when the label IS visible it already names the button, and adding an identical
+     *    aria-label is at best a no-op. When the consumer's CSS hides `.mj-left-nav__text`, the button's
+     *    accessible name goes EMPTY — a screen reader announces "button" with no destination. That is
+     *    the hole this closes.
+     *
+     * Leaving it false reproduces the previous markup exactly, so existing consumers are unaffected.
+     */
+    IconOnly: boolean;
+    /**
+     * Opt-in desktop collapse: renders a compact double-angle toggle chip at the top of the rail and,
+     * when {@link Collapsed}, presents the rail as an icons-only strip ({@link CollapsedWidth} wide) —
+     * labels visually hidden but kept in the a11y tree, section labels folded to divider lines,
+     * badges docked on the icon corner, and per-item tooltips/aria auto-enabled.
+     *
+     * The component owns the PRESENTATION only — the consumer owns the STATE (bind `[(Collapsed)]`
+     * and persist it however the app persists preferences), the same split as `ExpandedIds`.
+     * Desktop-only: ≤700px the rail is the off-canvas drawer and the toggle hides.
+     *
+     * Two things to know when the rail's content is richer than a flat icon list:
+     *  - **Tree sections fold to their top level while collapsed** (see {@link ShowTreeStructure});
+     *    a top-level item stands in as active for an active descendant, and the tree returns intact
+     *    on expand. Items with no `icon` render a monogram so they stay visible and hittable.
+     *  - **The `[header]` / `[footer]` slots are yours.** The rail can't restyle projected content,
+     *    so a wide header (logo lockup + wordmark, a filter box) will overflow a `CollapsedWidth`
+     *    strip. Bind the same collapsed flag in the consumer and project a compact variant.
+     *
+     * Deliberately NOT included: hover-to-peek (auto-expand on pointer hover) — removed by ruling
+     * (2026-07-30): a rail that expands when the pointer grazes it moves the target the user was
+     * aiming at. Deliberate toggling beats clever hovering.
+     */
+    Collapsible: boolean;
+    /** Whether the rail is currently collapsed to icons. Two-way bindable via `[(Collapsed)]`. */
+    Collapsed: boolean;
+    /** Emitted when the user clicks the collapse toggle. Consumer updates + persists the state. */
+    CollapsedChange: EventEmitter<boolean>;
+    /**
+     * Width of the collapsed icons-only strip. The default 60 is derived from the rail's own
+     * numbers — 8+8 container padding, 12+12 item padding, 18px icon, 1px border — so icons stay
+     * centred; retune it if those change.
+     */
+    CollapsedWidth: number;
+    /**
+     * True below the 701px breakpoint, where the rail stops being a rail and becomes the off-canvas
+     * drawer. Tracked in TS — not just CSS — because collapse is more than styling: it also decides
+     * whether tree sections fold and whether items are named by tooltip. The collapsed STYLES are
+     * gated to ≥701px, so without this the drawer would keep the collapsed BEHAVIOR while showing
+     * full labels: a flattened tree, and a monogram beside the very label it stands in for.
+     *
+     * Mirrors the matchMedia pattern in `mj-filter-popover` (same package).
+     */
+    private isMobileViewport;
+    private readonly zone;
+    private readonly cdr;
+    private readonly mediaQuery;
+    private readonly onMediaChange;
+    constructor();
+    ngOnDestroy(): void;
+    /**
+     * Whether the rail is collapsed *and* in a viewport where collapse means anything. Below 701px
+     * the rail is the off-canvas drawer — already dismissable, already showing full labels — so a
+     * persisted `Collapsed = true` must not follow the user down there.
+     */
+    get IsNativelyCollapsed(): boolean;
+    /** The width the rail actually renders at, honoring the collapse state. */
+    get EffectiveWidth(): number;
+    /**
+     * Icon-only presentation is on when the consumer forces it OR the rail is natively collapsed.
+     *
+     * `IconOnly` is deliberately NOT viewport-gated: that flag means the CONSUMER's own CSS has
+     * narrowed the rail, and we can't know which breakpoints they gated it to. Withdrawing the
+     * accessible names on their behalf could leave a genuinely icons-only rail unnamed — the exact
+     * hole `IconOnly` exists to close. Native collapse is ours to gate; theirs is theirs.
+     */
+    get EffectiveIconOnly(): boolean;
+    /**
+     * Whether tree structure (chevrons, depth indentation, expanded children) renders at all.
+     *
+     * An icons-only rail is ~60px wide and shows nothing but a centred glyph per row, which leaves a
+     * tree with no way to express itself: the chevron would eat a third of the width and shove the
+     * icon off-centre, each depth level would push its icon 14px further right until the rail clipped
+     * it, and a child's icon (optional, and usually absent on tree leaves) would say nothing about
+     * which branch it belongs to. So while icons-only, each section renders its TOP-LEVEL items only —
+     * the same choice every icon rail makes (VS Code's activity bar shows one icon per container and
+     * defers the tree to the expanded pane).
+     *
+     * Nothing is lost on the way back: `ExpandedIds` is consumer-owned and untouched here, so the tree
+     * returns exactly as the user left it the moment the rail expands.
+     */
+    get ShowTreeStructure(): boolean;
+    /**
+     * Whether an item paints as active. Normally an exact {@link ActiveId} match — but while the tree
+     * is suppressed (see {@link ShowTreeStructure}) the active item may be a child that isn't rendered,
+     * which would leave the collapsed rail with NOTHING highlighted and no sense of place. In that
+     * state a top-level item stands in for its active descendant.
+     */
+    IsItemActive(item: MJLeftNavItem): boolean;
+    /**
+     * `'page'` for the active item itself; `'true'` for a stand-in ancestor, which is current in the
+     * set but is not the page the user is on. Distinguishing them keeps the announcement honest.
+     */
+    AriaCurrentFor(item: MJLeftNavItem): 'page' | 'true' | null;
+    private hasActiveDescendant;
+    /**
+     * Monogram for an icon-less item in an icons-only rail. `Array.from` rather than `charAt` so a
+     * label starting with an emoji or an astral character yields that whole character instead of half
+     * a surrogate pair. Falls back to a bullet for a blank label so the button is never empty.
+     */
+    ItemInitial(item: MJLeftNavItem): string;
+    /**
+     * Left margin that pins the toggle chip at the collapsed band's centre in BOTH modes, so the
+     * chip never relocates on toggle (the user never re-aims). Derived, not magic:
+     * (CollapsedWidth − 38px chip)/2 from the rail edge, minus the rail's 8px container padding.
+     * 38 = the 18px icon box + 2×10px chip padding.
+     */
+    get CollapseToggleMarginPx(): number;
+    /** Reflects the collapsed state onto the host so the collapsed CSS can scope to it. */
+    get isCollapsedHost(): boolean;
+    /** Flip + announce. The consumer receives the new value and persists it. */
+    ToggleCollapsed(): void;
+    /**
+     * The text surfaced as an icon-only item's tooltip / accessible name. Folds in the description and
+     * badge because collapsing the rail hides both: the badge survives as an unlabeled corner count,
+     * so "Batch approvals (2)" is the only place a hovering user learns what the 2 counts.
+     */
+    ItemTooltip(item: MJLeftNavItem): string;
     /**
      * Label shown on the mobile drawer header and used as the switcher fallback
      * label when no item is active. Defaults to `'Menu'`. Set to something
@@ -159,6 +298,6 @@ export declare class MJLeftNavComponent {
      */
     HasExpandableItems(items: MJLeftNavItem[]): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<MJLeftNavComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<MJLeftNavComponent, "mj-left-nav", never, { "Sections": { "alias": "Sections"; "required": false; }; "ActiveId": { "alias": "ActiveId"; "required": false; }; "Width": { "alias": "Width"; "required": false; }; "MobileTitle": { "alias": "MobileTitle"; "required": false; }; "ExpandedIds": { "alias": "ExpandedIds"; "required": false; }; }, { "ItemClicked": "ItemClicked"; "ItemToggled": "ItemToggled"; }, never, ["[header]", "[footer]"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MJLeftNavComponent, "mj-left-nav", never, { "Sections": { "alias": "Sections"; "required": false; }; "ActiveId": { "alias": "ActiveId"; "required": false; }; "Width": { "alias": "Width"; "required": false; }; "IconOnly": { "alias": "IconOnly"; "required": false; }; "Collapsible": { "alias": "Collapsible"; "required": false; }; "Collapsed": { "alias": "Collapsed"; "required": false; }; "CollapsedWidth": { "alias": "CollapsedWidth"; "required": false; }; "MobileTitle": { "alias": "MobileTitle"; "required": false; }; "ExpandedIds": { "alias": "ExpandedIds"; "required": false; }; }, { "CollapsedChange": "CollapsedChange"; "ItemClicked": "ItemClicked"; "ItemToggled": "ItemToggled"; }, never, ["[header]", "[footer]"], true, never>;
 }
 //# sourceMappingURL=left-nav.component.d.ts.map

package/dist/lib/left-nav/left-nav.component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"left-nav.component.d.ts","sourceRoot":"","sources":["../../../src/lib/left-nav/left-nav.component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,YAAY,EAA4C,MAAM,eAAe,CAAC;;AAGlG;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,EAAE,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBA8ba,kBAAkB;IAC7B;;;OAGG;IACM,QAAQ,EAAE,gBAAgB,EAAE,CAAM;IAE3C;;;OAGG;IACM,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAExC;;;;OAIG;IACM,KAAK,EAAE,MAAM,CAAO;IAE7B;;;;OAIG;IACM,WAAW,EAAE,MAAM,CAAU;IAEtC;;;;;;;OAOG;IACM,WAAW,EAAE,MAAM,EAAE,CAAM;IAEpC;;OAEG;IACO,WAAW,8BAAqC;IAE1D;;;OAGG;IACO,WAAW,8BAAqC;IAE1D;;;OAGG;IACI,aAAa,UAAS;IAE7B,gFAAgF;IAChF,IACI,eAAe,IAAI,OAAO,CAE7B;IAED,aAAa,IAAI,IAAI;IAIrB,cAAc,IAAI,IAAI;IAItB,uEAAuE;IAEvE,QAAQ,IAAI,IAAI;IAMhB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAOtC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;IAMrD;;;;OAIG;IACH,IAAI,iBAAiB,IAAI,aAAa,GAAG,SAAS,CAGjD;IAED,OAAO,CAAC,YAAY;IAWpB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;;;;;OAQG;IACH,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO;yCA3HxC,kBAAkB;2CAAlB,kBAAkB;CAiI9B"}
+{"version":3,"file":"left-nav.component.d.ts","sourceRoot":"","sources":["../../../src/lib/left-nav/left-nav.component.ts"],"names":[],"mappings":"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"}