@sentropic/design-system-angular 0.36.59 → 0.36.61

package/dist/PanelStack.d.ts

@@ -0,0 +1,270 @@
+import { ElementRef, EventEmitter } from "@angular/core";
+import type { AfterContentInit, AfterViewInit, OnChanges, OnDestroy, OnInit, SimpleChanges } from "@angular/core";
+import * as i0 from "@angular/core";
+export type PanelStackShape = "split-primary" | "sticky-item";
+/**
+ * Bound ratified by the chat consumer lane: beyond 4 sections, stacking
+ * collapsible regions in a pane capped at 640px makes scrolling unmanageable
+ * and the single-owner rule becomes untenable. Enforced as a dev-time
+ * `console.warn` in `register()` (this package's established convention —
+ * see NavActionStack/WaterfallChart — is to warn and degrade, never throw or
+ * silently truncate); exported here so the bound is also visible through
+ * types/docs to a consumer reading `PanelStackProps`. Mirrors
+ * `PanelStack.svelte`'s constant of the same name/value 1:1.
+ */
+export declare const PANEL_STACK_MAX_SECTIONS = 4;
+export type PanelStackProps = {
+    /** "sticky-item" (default): one section expanded at a time, all headers stay visible.
+        "split-primary": the `primary` section is always expanded and owns the scroll;
+        the others are content-sized disclosures. */
+    shape?: PanelStackShape;
+    /** Accessible name for the stack region. */
+    label?: string;
+    /** sticky-item, controlled: id of the expanded section. */
+    expanded?: string | null;
+    /** sticky-item, uncontrolled seed. */
+    defaultExpanded?: string | null;
+    onExpandedChange?: (id: string | null) => void;
+    /**
+     * split-primary: id of the section that owns the scroll. Falls back to the
+     * first EXPANDED section (registration order) when unset or stale, and —
+     * if nothing is expanded — to the first registered section, so the stack
+     * never degrades to zero scroll owners.
+     */
+    primary?: string;
+    /** Usable floor for the primary section, in px. While the primary sits above it the
+        primary absorbs overflow; once it would drop below, a secondary auto-collapses
+        instead of compressing the primary further. Default 160. */
+    primaryMinHeight?: number;
+    /**
+     * At most {@link PANEL_STACK_MAX_SECTIONS} `PanelSection` children are
+     * supported — see that constant's doc comment for why.
+     */
+    class?: string;
+};
+/**
+ * Pure fallback-chain resolver for split-primary's scroll owner — mirrors
+ * `PanelStack.svelte`'s `effectivePrimary` derivation so it is unit-testable
+ * without any component/DOM machinery (see MenuPopover's
+ * `computeMenuPopoverPosition` for the established pattern).
+ *
+ * Tier 1: a `designatedPrimary` that matches a currently-registered id always
+ * wins. Tier 2: otherwise the first EXPANDED id in `orderedIds` (registration
+ * order is the tiebreak, never click order). Tier 3 (last resort): the first
+ * registered id, so the stack never degrades to zero scroll owners.
+ */
+export declare function resolvePanelStackPrimary(designatedPrimary: string | undefined, orderedIds: readonly string[], openIds: ReadonlySet<string>): string | null;
+/**
+ * Pure resolver for sticky-item's effective expanded/scroll-owner id — a
+ * SINGLE resolved value deliberately reused by the class for both
+ * `isExpanded` and `isScrollOwner` in that shape (see `effectiveExpandedId`).
+ * Splitting these into two different values would let a section render as
+ * the (visible, `overflow:auto`) scroll owner while its trigger reports
+ * `aria-expanded="false"` — a screen reader announcing "collapsed" for
+ * on-screen, scrolling content. sticky-item's contract is that "expanded"
+ * and "owns the scroll" are the same fact about the same section by
+ * definition, so this resolver is the one place that fact is decided, for
+ * both.
+ *
+ * The controlled counterpart to `effectiveExpandedId`'s uncontrolled
+ * fallback (which already resolves to the first registered id on its own).
+ * Mirrors `resolvePanelStackPrimary`'s last-resort tier so this package's
+ * Node test environment can exercise the decision without any
+ * component/DOM machinery.
+ *
+ * Ratified cross-framework rule: a controlled `expanded` is NEVER silently
+ * corrected — the caller must still expose the raw, possibly-invalid value
+ * back to the consumer (never rewritten, never fed through
+ * `onExpandedChange`) — that is about the PROP, not about what gets
+ * rendered: ARIA still has to describe the actual DOM, so the resolved
+ * (possibly healed) value below is what both `isExpanded` and
+ * `isScrollOwner` read. Two distinct controlled inputs are told apart here:
+ *
+ * - `expandedId` is a non-null id that names NO id in `orderedIds`: this is
+ *   a MISTAKE (a stale/typo'd controlled value) — the consumer intended a
+ *   section open and silently got none, which is exactly the "content
+ *   unreachable by the wheel" state the stack must never reach. Falls back
+ *   to the first registered id, identically to `resolvePanelStackPrimary`'s
+ *   own tier 3.
+ * - `expandedId` is explicitly `null`: this is a DELIBERATE "everything
+ *   collapsed" — honoured as-is, no fallback. An all-collapsed stack shows
+ *   no content at all, so nothing is unreachable; zero scroll owners is the
+ *   correct, legitimate outcome here.
+ */
+export declare function resolvePanelStackExpanded(expandedId: string | null, orderedIds: readonly string[]): string | null;
+export type PanelStackAutoCollapseMeasurements = {
+    /** Id of the section currently resolved as primary (never a collapse candidate). */
+    primaryId: string;
+    /** Latest observed height of the stack container. 0 means "not measured yet". */
+    stackHeight: number;
+    /** Latest observed height of the primary's own header. */
+    primaryHeaderHeight: number;
+    /** Ids of every non-primary (secondary) registered section. */
+    secondaryIds: readonly string[];
+    /** Latest observed ROOT (header + current body) height per registered id. */
+    rootHeights: ReadonlyMap<string, number>;
+    /** Ids the user explicitly opened (their INTENT, independent of what's actually visible). */
+    openSecondary: ReadonlySet<string>;
+    /** Ids force-collapsed by this algorithm on an earlier pass. */
+    autoCollapsed: ReadonlySet<string>;
+    /** MRU order (oldest first) of ids the user explicitly opened — drives
+     *  "collapse the least-recently-expanded secondary first". */
+    expansionOrder: readonly string[];
+};
+/**
+ * THE auto-collapse decision, factored out as a pure function (per
+ * MenuPopover's `computeMenuPopoverPosition` precedent) so it is testable
+ * without ResizeObserver/DOM: this package's Node test environment has
+ * neither. Mirrors `PanelStack.svelte`'s decision `$effect` body exactly.
+ *
+ * Returns the id of AT MOST ONE new secondary to auto-collapse this pass, or
+ * `null` if nothing needs to (either it already fits, or nothing is left to
+ * collapse — the degenerate "pane too small even fully collapsed" case).
+ *
+ * Convergence / no-avalanche contract: this function is a pure read of the
+ * measurements and state PASSED IN — it never reads or writes any component
+ * field itself, and it never returns more than one id per call. A caller
+ * that re-invokes it once per REAL measurement update (the pattern used by
+ * `PanelStack`'s ResizeObserver callback and `toggle()`) therefore collapses
+ * at most one NEW secondary per pass, using measurements that are always
+ * either accurate (untouched by this pass) or correctly reflect an EARLIER
+ * pass once the observer catches up — never a same-tick avalanche. Calling
+ * it again with IDENTICAL inputs (e.g. a duplicate/no-op resize delivery)
+ * always returns `null` once the fixed point is reached: `autoCollapsed`
+ * already contains every viable candidate, so the `.find()` below yields
+ * nothing new — no oscillation.
+ */
+export declare function computePanelStackAutoCollapse(measurements: PanelStackAutoCollapseMeasurements, floorPx?: number): string | null;
+/**
+ * Stacks several `PanelSection` contents inside ONE panel so a docked chat
+ * can share a pane with other content. The invariant is the whole point:
+ * exactly one section's body has `overflow: auto` at any moment, and the
+ * stack itself NEVER scrolls — see `PanelSection.ts` for the single scrolling
+ * declaration in this component pair.
+ *
+ * Faithful Angular port of `PanelStack.svelte`. See that file for the
+ * ratified contract this mirrors; the notable Angular-specific departures,
+ * all forced by this platform (documented in depth at each site below):
+ *
+ * - Coordination with `PanelSection` children is NOT Svelte-style context
+ *   (`setContext`/`getContext`). Angular constructor DI would be the direct
+ *   analog, but it needs `@Optional()`/`@Inject()` PARAMETER decorators,
+ *   which this package's tsconfig cannot compile (no `experimentalDecorators`
+ *   — the whole package already relies on standard/Ivy decorators for
+ *   class/property positions only). Instead `PanelStack` discovers its
+ *   sections via `@ContentChildren` and pushes `isPrimary`/`expanded`/
+ *   `scrollOwner` directly onto each instance — the SAME "parent owns
+ *   projected children's state" idiom `SelectableList` already established
+ *   for its `SelectableRow` children in this exact package.
+ * - Registration order substitutes for Svelte's DOM-order-via-
+ *   `compareDocumentPosition` fallback: `@ContentChildren` (and this
+ *   package's Node test environment, which has no DOM at all) both already
+ *   hand entries over in call/DOM order, so no separate re-sort is needed.
+ * - No `ChangeDetectorRef`/`markForCheck` — matching this package's existing
+ *   idiom of relying on zone.js's default full-tree change detection (same
+ *   as `MenuPopover`'s window-listener-driven position updates).
+ */
+export declare class PanelStack implements OnInit, AfterContentInit, AfterViewInit, OnChanges, OnDestroy {
+    private readonly host;
+    static readonly stComponentName = "PanelStack";
+    readonly componentName = "PanelStack";
+    shape: PanelStackShape;
+    label?: string;
+    /** sticky-item, controlled: id of the expanded section. Presence (including
+     *  an explicit `null`) is what makes the stack controlled — same
+     *  undefined-vs-set idiom as `AppShell.panelWidths`. */
+    expanded?: string | null;
+    defaultExpanded: string | null;
+    /** Svelte-canonical callback. */
+    onExpandedChange?: (id: string | null) => void;
+    /** Angular-idiom addition (not in the Svelte contract): enables
+     *  `[(expanded)]` two-way binding alongside `onExpandedChange`. */
+    readonly expandedChange: EventEmitter<string | null>;
+    primary?: string;
+    primaryMinHeight?: number;
+    classInput?: string;
+    private sectionsQuery?;
+    private entries;
+    private internalExpanded;
+    private openSecondary;
+    private autoCollapsed;
+    private expansionOrder;
+    private rootHeights;
+    private stackHeight;
+    private primaryHeaderHeight;
+    private resizeObserver;
+    private observedPrimaryHeaderEl;
+    /** Dev-time "warned once" latch for a controlled `expanded` naming no
+     *  registered section — see `effectiveExpandedId`. Guards the
+     *  `console.warn` only, never the fallback resolution itself (which must
+     *  always resolve a scroll owner). Never reset: the contract is "a
+     *  console.warn once" (per instance), not "once per distinct bad id". */
+    private warnedInvalidExpanded;
+    private childUnregister;
+    private childToggleSub;
+    private sectionsChangesSub;
+    constructor(host: ElementRef<HTMLElement>);
+    ngOnInit(): void;
+    ngAfterContentInit(): void;
+    ngAfterViewInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    get hostClass(): string;
+    get controlled(): boolean;
+    /**
+     * sticky-item: the controlled branch NEVER rewrites `this.expanded` (the
+     * controlled contract is absolute — no self-correction, no synthetic
+     * `onExpandedChange`/`expandedChange` call), but it DOES resolve through
+     * `resolvePanelStackExpanded` so every DERIVED read (`isExpanded`,
+     * `isScrollOwner`) sees a healed value: a non-null `expanded` naming no
+     * registered section falls back to the first registered id (with a
+     * one-time dev warning below); an explicit `null` is a deliberate
+     * "everything collapsed" and is returned as-is. Guarded by
+     * `this.entries.length > 0` so a controlled value isn't flagged as
+     * "invalid" before any `PanelSection` has had a chance to register yet.
+     */
+    get effectiveExpandedId(): string | null;
+    get effectivePrimary(): string | null;
+    /** Resolved floor fed to `computePanelStackAutoCollapse`'s `floorPx` —
+     *  falls back to `PRIMARY_MIN_BLOCK_SIZE_PX` (the same value as the CSS
+     *  fallback) when `primaryMinHeight` is unset. */
+    get resolvedPrimaryMinHeight(): number;
+    /** Inline value for the host's `--st-component-panelStack-primaryMinBlockSize`
+     *  custom property — see the `host` binding in the `@Component` decorator.
+     *  `resolvedPrimaryMinHeight` is the single source of truth this is
+     *  derived from, so the JS threshold and the CSS floor can never drift
+     *  apart. */
+    get primaryMinHeightStyle(): string;
+    isPrimary(id: string): boolean;
+    isExpanded(id: string): boolean;
+    isScrollOwner(id: string): boolean;
+    toggle(id: string): void;
+    /** Register a section's root AND header element, in registration order;
+     *  returns an unregister callback. NOT just bookkeeping — the stack falls
+     *  back to the first registered section as the scroll owner whenever
+     *  nothing else designates one (unset/stale `expanded` or `primary`), so
+     *  the invariant "exactly one scroll owner whenever the stack has >=1
+     *  section" holds even for a misconfigured or dynamically-changing stack.
+     *  Plain, DOM-agnostic bookkeeping — safe to call directly from tests with
+     *  fake element objects (no real DOM required: `el`/`headerEl` are only
+     *  ever compared by identity or handed to `ResizeObserver.observe`, which
+     *  is itself guarded for absence below). */
+    register(id: string, el: HTMLElement, headerEl: HTMLElement): () => void;
+    private setExpanded;
+    private syncSections;
+    private applyStateToChildren;
+    private ensureResizeObserver;
+    /** Retarget the header observer whenever the primary changes (designation,
+     *  fallback resolution, or a section registering/unregistering). */
+    private syncPrimaryHeaderObserver;
+    /** THE decision, driven off whatever measurements are CURRENTLY known.
+     *  Called after every event that could change what "fits" means (a fresh
+     *  ResizeObserver delivery, a toggle, a register/unregister, a `primary`/
+     *  `shape` input change) — safe to over-call: `computePanelStackAutoCollapse`
+     *  is a pure, idempotent read that returns `null` once nothing more needs
+     *  to collapse, so redundant calls are no-ops. */
+    private runAutoCollapseDecision;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PanelStack, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PanelStack, "st-panel-stack", never, { "shape": { "alias": "shape"; "required": false; }; "label": { "alias": "label"; "required": false; }; "expanded": { "alias": "expanded"; "required": false; }; "defaultExpanded": { "alias": "defaultExpanded"; "required": false; }; "onExpandedChange": { "alias": "onExpandedChange"; "required": false; }; "primary": { "alias": "primary"; "required": false; }; "primaryMinHeight": { "alias": "primaryMinHeight"; "required": false; }; "classInput": { "alias": "class"; "required": false; }; }, { "expandedChange": "expandedChange"; }, ["sectionsQuery"], ["*"], true, never>;
+}
+//# sourceMappingURL=PanelStack.d.ts.map

package/dist/PanelStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PanelStack.d.ts","sourceRoot":"","sources":["../src/PanelStack.ts"],"names":[],"mappings":"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"}