ng-hub-ui-panels 21.2.0

package/types/ng-hub-ui-panels.d.ts

@@ -0,0 +1,399 @@
+import * as _angular_core from '@angular/core';
+import { ElementRef, OnDestroy, TemplateRef } from '@angular/core';
+import { Params } from '@angular/router';
+import { ControlValueAccessor } from '@angular/forms';
+
+/**
+ * Marks an `<ng-template>` inside a `hub-panel` as that panel's custom header
+ * (strip link in `tabs`/`pills` view, disclosure button in `accordion` view),
+ * replacing the plain-text `heading` input.
+ *
+ * @example
+ * ```html
+ * <hub-panel>
+ *   <ng-template hubPanelHeading><em>Rich</em> heading</ng-template>
+ *   Panel content
+ * </hub-panel>
+ * ```
+ */
+declare class PanelHeadingDirective {
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PanelHeadingDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<PanelHeadingDirective, "[hubPanelHeading]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an element inside a `hub-panel` as the panel's content **header** band,
+ * projected at the top of the panel body (above `<ng-content>`).
+ *
+ * Unlike `hubPanelHeading` — which renders the navigational label in the
+ * `tabs`/`pills` strip or the `accordion` disclosure button — this header lives
+ * inside the panel body and renders in **every** view (`tabs`, `pills`,
+ * `accordion`, `card`). It is the natural title slot for the `card` format.
+ *
+ * @example
+ * ```html
+ * <hub-panel>
+ *   <div hubPanelHeader>Card title</div>
+ *   Card content
+ *   <div hubPanelFooter>Actions</div>
+ * </hub-panel>
+ * ```
+ */
+declare class PanelHeaderDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PanelHeaderDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<PanelHeaderDirective, "[hubPanelHeader]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Marks an element inside a `hub-panel` as the panel's content **footer** band,
+ * projected at the bottom of the panel body (below `<ng-content>`).
+ *
+ * Renders in **every** view (`tabs`, `pills`, `accordion`, `card`); it is the
+ * natural actions/footer slot for the `card` format.
+ *
+ * @example
+ * ```html
+ * <hub-panel>
+ *   <div hubPanelHeader>Card title</div>
+ *   Card content
+ *   <div hubPanelFooter>Actions</div>
+ * </hub-panel>
+ * ```
+ */
+declare class PanelFooterDirective {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PanelFooterDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<PanelFooterDirective, "[hubPanelFooter]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Visualization of the panels container: classic underlined/boxed `tabs`,
+ * rounded `pills`, stacked disclosure panels (`accordion`), or chromeless
+ * always-visible cards (`card`) with no navigation strip.
+ */
+type PanelsType = 'tabs' | 'pills' | 'accordion' | 'card';
+/**
+ * Event emitted by {@link PanelsComponent.panelChange} when the user
+ * activates (opens) a panel.
+ */
+interface PanelChangeEvent {
+    /** The newly selected panel. */
+    current: PanelComponent;
+    /**
+     * The panel that was active before the change, if any. Not provided in
+     * accordion view with `multiple`, where several panels stay open.
+     */
+    prev?: PanelComponent;
+}
+
+/**
+ * Injectable defaults for every `<hub-panels>` in the application.
+ *
+ * Override at any injector level to change the defaults globally or for a
+ * feature subtree:
+ *
+ * ```ts
+ * providers: [{ provide: PanelsConfig, useValue: { ...new PanelsConfig(), type: 'pills' } }]
+ * ```
+ */
+declare class PanelsConfig {
+    /** Default navigation style — `'tabs'`, `'pills'` or `'accordion'`. */
+    type: PanelsType;
+    /** Whether keyboard navigation (arrows / Home / End / Delete) is enabled. */
+    isKeysAllowed: boolean;
+    /** Accessible label announced for the panel list. */
+    ariaLabel: string;
+    /** Accessible label for the backward scroll button (scrollable mode). */
+    scrollBackwardAriaLabel: string;
+    /** Accessible label for the forward scroll button (scrollable mode). */
+    scrollForwardAriaLabel: string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PanelsConfig, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<PanelsConfig>;
+}
+
+interface MultipleHeaderGroup {
+    activePanel?: PanelComponent;
+    headers: PanelComponent[];
+}
+/**
+ * Content-panels container — the hub `panels` primitive.
+ *
+ * Projects `<hub-panel>` panes and renders them in one of three views:
+ *
+ * - **`tabs` / `pills`** — an accessible `tablist` of clickable headers
+ *   (roving tabindex, arrow/Home/End/Delete keys) above the active pane.
+ *   Panels with a `routerLink` switch the content area to a `<router-outlet>`
+ *   and the active panel follows the URL. With `scrollable`, overflowing
+ *   headers get backward/forward scroll buttons.
+ * - **`accordion`** — each panel renders as a stacked disclosure panel with an
+ *   animated collapse: clicking an open header closes it, `multiple` allows
+ *   several panels open at once and `flush` removes the outer chrome. All
+ *   panels start collapsed unless a panel is marked `[active]` or a form value
+ *   is bound. Routed panels are not supported in this view.
+ *
+ * The container implements `ControlValueAccessor`, so the active panel(s) can
+ * be bound as a form value (`ngModel` / `formControl`): each panel contributes
+ * its `value` (or its `id` by default), optionally narrowed with `bindValue`
+ * and compared with `compareWith`. With `multiple` the form value is an array.
+ *
+ * Theming is driven entirely by the `--hub-panels-*` CSS custom properties
+ * (see `panels.variables.scss`); the accordion view also honours the
+ * `--hub-accordion-*` ng-hub-ui contract as a compatibility fallback.
+ *
+ * @example
+ * ```html
+ * <hub-panels type="accordion" multiple [formControl]="openPanels">
+ *   <hub-panel heading="Fields" value="fields">…</hub-panel>
+ *   <hub-panel heading="Validations" value="validations">…</hub-panel>
+ * </hub-panels>
+ * ```
+ */
+declare class PanelsComponent implements ControlValueAccessor {
+    #private;
+    /** Container-wide defaults (aria labels, default type, keyboard toggle). */
+    protected readonly config: PanelsConfig;
+    /** Scrollable container hosting the panel headers (`tabs` / `pills` views). */
+    readonly navScroller: _angular_core.Signal<ElementRef<HTMLElement> | undefined>;
+    /** Backward scroll button (only rendered while it can scroll back). */
+    readonly prevBtn: _angular_core.Signal<ElementRef<HTMLElement> | undefined>;
+    /** Forward scroll button (only rendered while it can scroll forward). */
+    readonly nextBtn: _angular_core.Signal<ElementRef<HTMLElement> | undefined>;
+    /** Parking lot that owns the projected panel hosts before they are placed. */
+    readonly contentRoot: _angular_core.Signal<ElementRef<HTMLElement> | undefined>;
+    /** Visible block hosts used by `multiple` tabs / pills. */
+    readonly multiplePaneHosts: _angular_core.Signal<readonly ElementRef<HTMLElement>[]>;
+    /** Visible grouped blocks used by `multiple` tabs / pills. */
+    readonly multipleBlocks: _angular_core.Signal<readonly ElementRef<HTMLElement>[]>;
+    /** Emitted when the user activates (opens) a different panel. */
+    readonly panelChange: _angular_core.OutputEmitterRef<PanelChangeEvent>;
+    /** Whether the panel list is stacked beside the content (`tabs` / `pills`). */
+    readonly vertical: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether panel headers stretch to share the available width equally. */
+    readonly justified: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Visualization — `'tabs'` (default), `'pills'` or `'accordion'`. */
+    readonly type: _angular_core.InputSignal<PanelsType>;
+    /** Whether keyboard navigation is enabled. */
+    readonly isKeysAllowed: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether overflowing headers get backward/forward scroll buttons. */
+    readonly scrollable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accordion view: whether several panels may be expanded at once. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accordion view: edge-to-edge panels without outer borders or radius. */
+    readonly flush: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Dot-notation path applied to each panel's `value` to obtain the emitted
+     * form value (e.g. `'meta.key'`). Empty by default — the raw value is used.
+     */
+    readonly bindValue: _angular_core.InputSignal<string | undefined>;
+    /** Equality used to match form values against panel values. `===` by default. */
+    readonly compareWith: _angular_core.InputSignal<(a: unknown, b: unknown) => boolean>;
+    /** Registered panels, in projection order. */
+    readonly panels: _angular_core.WritableSignal<PanelComponent[]>;
+    /** Currently active panel, if any (the first one, under `multiple`). */
+    readonly activePanel: _angular_core.Signal<PanelComponent | undefined>;
+    /** Panel index lookup used by the strip templates and keyboard navigation. */
+    readonly panelIndexMap: _angular_core.Signal<Map<PanelComponent, number>>;
+    /** Whether the container renders the accordion visualization. */
+    readonly isAccordionView: _angular_core.Signal<boolean>;
+    /**
+     * Whether the container renders the chromeless `card` visualization: no
+     * navigation strip and every panel always visible, each styled as a card.
+     */
+    readonly isCardView: _angular_core.Signal<boolean>;
+    /**
+     * Whether more than one panel may be active at once. Driven by `multiple`
+     * for every view, and always enabled in the `card` view, where all panels
+     * stay visible at once and must not deactivate one another.
+     */
+    readonly allowsMultipleActive: _angular_core.Signal<boolean>;
+    /** Whether the bound form control disabled the whole container. */
+    readonly formDisabled: _angular_core.WritableSignal<boolean>;
+    /**
+     * Whether the active panel routes its content through a `<router-outlet>`.
+     * Never true in the accordion view, where routed panels are not supported.
+     */
+    protected readonly activePanelHasRouter: _angular_core.Signal<boolean>;
+    /**
+     * In `multiple` tabs/pills, headers are partitioned into blocks. Every
+     * active panel starts a block; following inactive headers stay visible in
+     * that same block until the next active panel starts a new one.
+     */
+    protected readonly multipleHeaderGroups: _angular_core.Signal<MultipleHeaderGroup[]>;
+    /** Whether the strip cannot scroll further backward. */
+    readonly backwardIsDisabled: _angular_core.WritableSignal<boolean>;
+    /** Whether the strip cannot scroll further forward. */
+    readonly forwardIsDisabled: _angular_core.WritableSignal<boolean>;
+    constructor();
+    /**
+     * Registers a panel in the container. Called by `PanelComponent` on
+     * construction — not meant for manual use.
+     */
+    registerPanel(panel: PanelComponent): void;
+    /**
+     * Removes a panel from the container. `reselect` activates the closest
+     * enabled neighbour when the removed panel was active; `emit` fires the
+     * panel's `removed` output.
+     */
+    removePanel(panel: PanelComponent, options?: {
+        reselect?: boolean;
+        emit?: boolean;
+    }): void;
+    /**
+     * Activates a panel on behalf of the user (`tabs` / `pills` views): marks it
+     * active, navigates when routed, and emits `panelChange`. In `multiple` mode
+     * clicking an active panel toggles it off (the panes render side by side);
+     * otherwise an already-active panel no-ops. Disabled panels always no-op.
+     */
+    selectPanel(panel: PanelComponent): void;
+    /**
+     * Toggles a panel on behalf of the user (accordion view): an open panel
+     * closes, a closed one opens — closing the others unless `multiple`.
+     * Emits `panelChange` when a panel opens.
+     */
+    togglePanel(panel: PanelComponent): void;
+    /**
+     * Marks the routed panel matching the current URL as active. Does not
+     * navigate — activation through this path is URL-driven. No-op in the
+     * accordion view, where routed panels are not supported.
+     */
+    setActivePanel(): void;
+    /**
+     * Writes the form value into the container: panels whose (`bindValue`-mapped)
+     * value matches are activated, the rest are deactivated. With `multiple` an
+     * array is expected; otherwise a single value.
+     */
+    writeValue(value: unknown): void;
+    /** Registers the form-control change callback. */
+    registerOnChange(onChange: (value: unknown) => void): void;
+    /** Registers the form-control touched callback. */
+    registerOnTouched(onTouched: () => void): void;
+    /** Enables/disables every panel header on behalf of the form control. */
+    setDisabledState(isDisabled: boolean): void;
+    /** Keyboard navigation for the panel strip (arrows / Home / End / Delete). */
+    protected onPanelKeydown(event: KeyboardEvent, index: number): void;
+    /**
+     * Keyboard navigation between accordion headers (arrows / Home / End /
+     * Delete). Enter and Space toggle natively through the button click.
+     */
+    onAccordionKeydown(event: KeyboardEvent, panel: PanelComponent): void;
+    /** Recomputes the enabled/disabled state of the scroll buttons. */
+    protected updateScrollButtons(): void;
+    /** Re-syncs scroll controls and multiple-block sizing on window resize. */
+    protected onWindowResize(): void;
+    /** Updates the scroll buttons as the strip scrolls. */
+    protected onScroll(): void;
+    /** Global index of a panel within the projected strip order. */
+    protected panelIndex(panel: PanelComponent): number;
+    /** Scrolls the panel headers one viewport backward. */
+    protected navBackward(): void;
+    /** Scrolls the panel headers one viewport forward. */
+    protected navForward(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PanelsComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PanelsComponent, "hub-panels", never, { "vertical": { "alias": "vertical"; "required": false; "isSignal": true; }; "justified": { "alias": "justified"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "isKeysAllowed": { "alias": "isKeysAllowed"; "required": false; "isSignal": true; }; "scrollable": { "alias": "scrollable"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "flush": { "alias": "flush"; "required": false; "isSignal": true; }; "bindValue": { "alias": "bindValue"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; }, { "panelChange": "panelChange"; }, never, ["*"], true, never>;
+}
+
+/**
+ * One content panel inside a `<hub-panels>` container.
+ *
+ * In the `tabs` / `pills` views the host element is the tab *panel*
+ * (`role="tabpanel"`) and the clickable header is rendered by
+ * {@link PanelsComponent} in the strip. In the `accordion` view this component
+ * renders its own disclosure header plus an animated collapse wrapper around
+ * the projected content. In every view the header comes from `heading` or from
+ * a `<ng-template hubPanelHeading>` projected inside this element.
+ *
+ * Panels can be plain content panes or routed: when `routerLink` is set, the
+ * container renders a `<router-outlet>` instead of the projected panels and
+ * the active panel follows the current URL (`tabs` / `pills` views only).
+ *
+ * @example
+ * ```html
+ * <hub-panels>
+ *   <hub-panel heading="Fields">…</hub-panel>
+ *   <hub-panel>
+ *     <ng-template hubPanelHeading>Validations <span class="badge">3</span></ng-template>
+ *     …
+ *   </hub-panel>
+ * </hub-panels>
+ * ```
+ */
+declare class PanelComponent implements OnDestroy {
+    #private;
+    /** Host element reference — exposed so the container can detach removed panes. */
+    readonly elementRef: ElementRef<HTMLElement>;
+    /**
+     * Owning panels container, or `null` when the panel is used standalone
+     * (outside any `<hub-panels>`), in which case it renders as a card.
+     * Exposed to the template for the accordion header.
+     */
+    protected readonly tabset: PanelsComponent | null;
+    /** Plain-text panel header. Ignored when a `hubPanelHeading` template exists. */
+    readonly heading: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Unique id used for the `tab` / `tabpanel` (or accordion header / region)
+     * ARIA pairing. Auto-generated (`hub-panel-<n>`) when not provided.
+     */
+    readonly id: _angular_core.InputSignal<string>;
+    /** Whether the panel cannot be activated. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the panel shows a remove affordance (✕ and the Delete key). */
+    readonly removable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * URL comparison used to mark routed panels active: `'route'` compares the
+     * path only, `'full'` also compares query params.
+     */
+    readonly pathMatch: _angular_core.InputSignal<"route" | "full">;
+    /** Navigation target that turns this panel into a routed panel. */
+    readonly routerLink: _angular_core.InputSignal<string | string[] | null | undefined>;
+    /** Query params appended when navigating to `routerLink`. */
+    readonly queryParams: _angular_core.InputSignal<Params | null | undefined>;
+    /** Extra CSS classes applied to both the nav item and this pane. */
+    readonly customClass: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Value this panel contributes when the container is used as a form control
+     * (see {@link PanelsComponent} `ControlValueAccessor`). Defaults to `id`.
+     */
+    readonly value: _angular_core.InputSignal<unknown>;
+    /** Whether the panel is currently active (expanded, in the accordion view). */
+    readonly active: _angular_core.ModelSignal<boolean>;
+    /** Emitted when the panel becomes active. */
+    readonly selectPanel: _angular_core.OutputEmitterRef<PanelComponent>;
+    /** Emitted when the panel stops being active. */
+    readonly deselectPanel: _angular_core.OutputEmitterRef<PanelComponent>;
+    /** Emitted when the panel is removed through the ✕ button or the Delete key. */
+    readonly removed: _angular_core.OutputEmitterRef<PanelComponent>;
+    /** Custom header template registered by `PanelHeadingDirective`. */
+    readonly headingRef: _angular_core.WritableSignal<TemplateRef<unknown> | undefined>;
+    /** Whether the owning container renders the accordion visualization. */
+    protected readonly accordionView: _angular_core.Signal<boolean>;
+    /**
+     * Whether this panel renders as a card: either inside a `<hub-panels
+     * type="card">` container or standalone (no owning container at all).
+     */
+    protected readonly cardView: _angular_core.Signal<boolean>;
+    /** Form value resolved for this panel: the explicit `value` or the panel id. */
+    readonly formValue: _angular_core.Signal<unknown>;
+    /** `routerLink` normalised to a segments array, or `null` when not routed. */
+    readonly routerUrl: _angular_core.Signal<string[] | null>;
+    constructor();
+    ngOnDestroy(): void;
+    /** Route path plus query string, or `null` when the panel is not routed. */
+    getFullRoute(): string | null;
+    /** Normalised absolute route path, or `null` when the panel is not routed. */
+    getRoute(): string | null;
+    /** `queryParams` serialised as `key=value&…`, or `null` when empty. */
+    getQueryParamsString(): string | null;
+    /** Navigates to the panel's route. No-op for non-routed panels. */
+    navigate(): void;
+    /** Accordion header click — toggles this panel through the container. */
+    protected onAccordionHeaderClick(): void;
+    /** Accordion header keyboard navigation, delegated to the container. */
+    protected onAccordionHeaderKeydown(event: KeyboardEvent): void;
+    /** Removes this panel through the accordion header's ✕ affordance. */
+    protected removeSelf(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<PanelComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<PanelComponent, "hub-panel, [hub-panel]", ["hubPanel"], { "heading": { "alias": "heading"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "removable": { "alias": "removable"; "required": false; "isSignal": true; }; "pathMatch": { "alias": "pathMatch"; "required": false; "isSignal": true; }; "routerLink": { "alias": "routerLink"; "required": false; "isSignal": true; }; "queryParams": { "alias": "queryParams"; "required": false; "isSignal": true; }; "customClass": { "alias": "customClass"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "active": { "alias": "active"; "required": false; "isSignal": true; }; }, { "active": "activeChange"; "selectPanel": "selectPanel"; "deselectPanel": "deselectPanel"; "removed": "removed"; }, never, ["[hubPanelHeader]", "*", "[hubPanelFooter]"], true, never>;
+}
+
+export { PanelComponent, PanelFooterDirective, PanelHeaderDirective, PanelHeadingDirective, PanelsComponent, PanelsConfig };
+export type { PanelChangeEvent, PanelsType };