ng-hub-ui-accordion
Version:
A flexible, accessible, and customizable accordion component for Angular 19, part of the ng-hub-ui family.
489 lines (482 loc) • 17.3 kB
TypeScript
import * as _angular_core from '@angular/core';
import { TemplateRef, OnDestroy } from '@angular/core';
import { ControlValueAccessor } from '@angular/forms';
/**
* Represents the event emitted when an accordion or collapsible element changes its state.
*
* @template T - The type of value associated with the collapsible element.
*/
interface CollapseEvent<T = any> {
/**
* The index of the item within the collection of collapsible elements.
*/
index: number;
/**
* Indicates whether the item is currently collapsed (`true`) or not (`false`).
*/
collapsed: boolean;
/**
* Indicates whether the item is currently uncollapsed (`true`) or not (`false`).
* Useful when distinguishing explicitly expanded items.
*/
uncollapsed: boolean;
/**
* The value associated with the collapsible element.
*/
value: T;
}
/**
* A component that represents a single panel within an accordion.
* Each panel can be expanded or collapsed independently and contains a header and content section.
*
* @example
* ```html
* <hub-accordion-panel [title]="'Panel Title'" [value]="panelValue">
* <ng-template hubAccordionPanelHeader>Custom Header</ng-template>
* Panel Content
* </hub-accordion-panel>
* ```
*
* @implements {OnInit}
*
* @property {number} index - The position of this panel within its parent accordion
* @property {any} value - The value associated with this panel
* @property {WritableSignal<boolean>} collapsed - Signal controlling the panel's collapsed state
* @property {string} title - The title text displayed in the panel's header
* @property {TemplateRef<any>} headerTpt - Template reference for custom header content
*
* @emits {collapseEvent} collapsedChange - Fired when the panel's collapsed state changes
*/
declare class AccordionPanelComponent {
/**
* The position of this panel within its parent accordion.
*
* @type {number}
*/
index: number;
/**
* ElementRef for accessing the native element.
* @private
*/
private elementRef;
value: any;
/**
* Signal that controls the collapsed state of the accordion panel.
* When true, the panel is collapsed. When false, the panel is expanded.
* @default true
*/
collapsed: _angular_core.ModelSignal<boolean>;
/**
* The title of the accordion panel.
*
* @type {string}
*/
title: _angular_core.InputSignal<unknown>;
/**
* Reference to the header template of the accordion panel.
* Uses contentChild query to find a template marked with AccordionPanelHeaderDirective.
* The template reference is read using TemplateRef.
*/
headerTpt: _angular_core.Signal<TemplateRef<any> | undefined>;
/**
* Event emitter that fires when the panel's collapsed state changes.
* Emits a collapseEvent object containing the collapse state and animation details.
* @event
*/
collapsedChange: _angular_core.OutputEmitterRef<CollapseEvent<any>>;
/**
* Toggles the collapse state of the accordion panel and emits the change event.
* The event includes the panel's index and its new collapsed state.
*
* @emits collapsedChange - Emits an object containing the panel index and collapsed state
*/
toggleCollapse(): void;
/**
* Handles keyboard navigation for the accordion panel.
* Supports Arrow keys, Home, End, Space, and Enter.
*
* @param event - The keyboard event
*/
onKeyDown(event: KeyboardEvent): void;
/**
* Focuses the next accordion panel button.
* @private
*/
private focusNextPanel;
/**
* Focuses the previous accordion panel button.
* @private
*/
private focusPreviousPanel;
/**
* Focuses the first accordion panel button.
* @private
*/
private focusFirstPanel;
/**
* Focuses the last accordion panel button.
* @private
*/
private focusLastPanel;
/**
* Gets all accordion panel buttons within the parent accordion.
* @private
* @returns Array of button elements
*/
private getAllPanelButtons;
/**
* Gets the current panel's index within all panel buttons.
* @private
* @param allPanels - Array of all panel buttons
* @returns Current panel index or 0 if not found
*/
private getCurrentPanelIndex;
static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionPanelComponent, never>;
static ɵcmp: _angular_core.ɵɵComponentDeclaration<AccordionPanelComponent, "hub-accordion-panel", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; "collapsedChange": "collapsedChange"; }, ["headerTpt"], ["*"], true, never>;
}
/**
* A component that implements an accordion UI pattern, allowing users to show and hide
* sections of related content. Supports single or multiple expanded panels and flush styling.
* Implements ControlValueAccessor for form integration.
*
* @example
* ```html
* <hub-accordion [multiple]="true" [options]="{flush: true}">
* <hub-accordion-panel>...</hub-accordion-panel>
* <hub-accordion-panel>...</hub-accordion-panel>
* </hub-accordion>
* ```
*
* @implements {ControlValueAccessor}
* @extends {SelectMultipleControlValueAccessor}
*/
declare class AccordionComponent implements ControlValueAccessor, OnDestroy {
/**
* The current value of the accordion component.
* An array that may contain any type of data.
*/
value: any[];
/**
* Input binding that configures the property or attribute to bind to.
* Defines the property that will be bound to the value of the accordion.
* @default undefined
*/
bindValue: _angular_core.InputSignal<string | undefined>;
/**
* Configuration options for the accordion component.
*
* @property {Object} options - The options object for configuring the accordion.
* @property {boolean} options.flush - When true, removes some borders and rounded corners to render
* accordions edge-to-edge with their parent container. Defaults to false.
*/
options: _angular_core.InputSignalWithTransform<{
flush: boolean;
}, any>;
/**
* Defines a comparison function to determine if two accordion items are equal.
* Used to track identity of objects in accordion selections.
*
* @param o1 First object to compare
* @param o2 Second object to compare
* @returns {boolean} True if objects are considered equal, false otherwise
* @defaultValue Default implementation uses strict equality (===)
*/
readonly compareWith: _angular_core.InputSignal<(o1: any, o2: any) => boolean>;
/**
* When true, expanding an accordion item will close all other expanded items.
* Defaults to false.
*/
multiple: _angular_core.InputSignal<boolean>;
/**
* Collection of child AccordionPanelComponent instances within this accordion.
* Uses Angular's contentChildren query to obtain all panel components.
* @type {QueryList<AccordionPanelComponent>}
*/
panels: _angular_core.Signal<readonly AccordionPanelComponent[]>;
/**
* Subject for managing component destruction and cleanup.
* @private
*/
private destroy$;
/**
* Map to track panel subscriptions for proper cleanup.
* @private
*/
private panelSubscriptions;
/**
* Effect that manages panel changes and their subscriptions.
* Initializes panel indices and subscribes to collapse events for each panel.
* This effect runs whenever the panels signal changes.
*
* Properly manages subscriptions to prevent memory leaks by:
* - Unsubscribing from previous panel subscriptions
* - Creating new subscriptions for current panels
* - Storing subscription references for cleanup
*/
panelsChangeEffect: _angular_core.EffectRef;
/**
* Gets whether the accordion has the flush styling option enabled
* @returns {boolean} True if the flush option is enabled, false otherwise
*/
get haveFlushClass(): boolean;
onChange: any;
onTouch: any;
/**
* Implements the ControlValueAccessor interface to write a new value to the form control.
* Validates and sanitizes the input value before setting it.
* @param obj The value to be written to the form control
*/
writeValue(obj: any): void;
/**
* Registers a callback function that is invoked when the control's value changes in the UI.
* This is part of the ControlValueAccessor interface implementation.
* @param fn - The callback function to register. This function will be called with the new value when the control's value changes.
*/
registerOnChange(fn: any): void;
/**
* Registers a callback function that is called when the control receives a touch event.
* Part of the ControlValueAccessor interface implementation.
* @param fn - The callback function to register. Gets called when the control is touched.
*/
registerOnTouched(fn: any): void;
/**
* Component cleanup method. Unsubscribes from all panel subscriptions and
* completes the destroy subject to prevent memory leaks.
*/
ngOnDestroy(): void;
/**
* Updates the collapse state of all panels based on the current value.
* Each panel is collapsed if its value is not found in the accordion's value array using the compareWith function.
* @internal
*/
handleValue(): void;
/**
* Handles the collapse/expand event of an accordion panel.
* Manages state consistently and handles both single and multiple selection modes.
*
* @param {CollapseEvent} collapseEvent - Object containing panel collapse event data
*/
handlePanelCollapse(collapseEvent: CollapseEvent): void;
/**
* Updates the accordion's value based on panel state changes.
* Maintains consistency between single and multiple selection modes.
*
* @param panelValue - The value of the panel being toggled
* @param collapsed - Whether the panel is being collapsed (true) or expanded (false)
* @private
*/
private updateAccordionValue;
/**
* Closes all panels except the one at the specified index.
* Used in single-selection mode to ensure only one panel is open at a time.
*
* @param excludeIndex - Index of the panel to keep open
* @private
*/
private closeOtherPanels;
/**
* Emits the current value in the appropriate format for the current mode.
* Single mode emits a single value or null, multiple mode emits an array.
*
* @private
*/
private emitValueChange;
/**
* Returns the value used by selection/comparison logic, applying `bindValue` when configured.
*
* @param sourceValue Raw panel value.
* @returns Comparable value used for internal selection state and emitted form value.
*/
private getComparableValue;
/**
* Reads a nested value from an object using dot notation path syntax.
*
* @param source Object to read from.
* @param path Dot notation path (e.g. `id`, `meta.key`).
* @returns Resolved value or `undefined` when the path cannot be resolved.
*/
private readByPath;
static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionComponent, never>;
static ɵcmp: _angular_core.ɵɵComponentDeclaration<AccordionComponent, "hub-accordion", never, { "bindValue": { "alias": "bindValue"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "compareWith": { "alias": "compareWith"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; }, {}, ["panels"], ["*"], true, never>;
}
declare class AccordionPanelHeaderDirective {
templateRef: TemplateRef<any>;
constructor(templateRef: TemplateRef<any>);
static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionPanelHeaderDirective, never>;
static ɵdir: _angular_core.ɵɵDirectiveDeclaration<AccordionPanelHeaderDirective, "[hubAccordionPanelHeader]", never, {}, {}, never, never, true, never>;
}
/**
* Global configuration interface for accordion components.
*/
interface AccordionGlobalConfig {
/**
* Default animation duration in milliseconds.
* @default 300
*/
animationDuration: number;
/**
* Whether multiple panels can be open by default.
* @default false
*/
multipleDefault: boolean;
/**
* Whether flush mode is enabled by default.
* @default false
*/
flushDefault: boolean;
/**
* Default theme for accordion styling.
* @default 'default'
*/
theme: 'default' | 'corporate' | 'vibrant' | 'dark' | string;
/**
* Whether to enable accessibility features by default.
* @default true
*/
accessibilityEnabled: boolean;
/**
* Whether to show warnings in development mode.
* @default true
*/
developmentWarnings: boolean;
/**
* Custom CSS class prefix for accordion components.
* @default 'hub-accordion'
*/
cssPrefix: string;
/**
* Whether animations are enabled globally.
* @default true
*/
animationsEnabled: boolean;
}
/**
* Global configuration service for accordion components.
* Provides centralized configuration management with type safety and validation.
*
* @example
* ```typescript
* // In your app config or module
* export const appConfig: ApplicationConfig = {
* providers: [
* // other providers...
* {
* provide: ACCORDION_CONFIG,
* useValue: {
* theme: 'corporate',
* animationDuration: 500,
* multipleDefault: true
* }
* }
* ]
* };
*
* // Or use the service directly
* constructor(private accordionConfig: AccordionConfigService) {
* this.accordionConfig.updateConfig({
* theme: 'dark',
* animationsEnabled: false
* });
* }
* ```
*/
declare class AccordionConfigService {
/**
* Signal containing the current global configuration.
* @private
*/
private config;
/**
* Updates the global configuration with partial values.
* Validates input values and provides warnings for invalid options.
*
* @param partialConfig - Partial configuration object to merge with current config
* @example
* ```typescript
* configService.updateConfig({
* theme: 'corporate',
* animationDuration: 500
* });
* ```
*/
updateConfig(partialConfig: Partial<AccordionGlobalConfig>): void;
/**
* Gets the current global configuration as a readonly signal.
*
* @returns Readonly signal with current configuration
* @example
* ```typescript
* const config = configService.getConfig();
* const animationDuration = config().animationDuration;
* ```
*/
getConfig(): _angular_core.Signal<AccordionGlobalConfig>;
/**
* Resets the configuration to default values.
*
* @example
* ```typescript
* configService.resetToDefaults();
* ```
*/
resetToDefaults(): void;
/**
* Gets a specific configuration value with type safety.
*
* @param key - Configuration key to retrieve
* @returns The configuration value
* @example
* ```typescript
* const duration = configService.getValue('animationDuration');
* ```
*/
getValue<K extends keyof AccordionGlobalConfig>(key: K): AccordionGlobalConfig[K];
/**
* Validates and sanitizes configuration values.
*
* @param config - Configuration object to validate
* @returns Validated and sanitized configuration
* @private
*/
private validateConfig;
/**
* Logs configuration updates in development mode.
*
* @param config - Updated configuration values
* @private
*/
private logConfigUpdate;
/**
* Logs warnings for invalid configuration values.
*
* @param message - Warning message
* @private
*/
private warn;
static ɵfac: _angular_core.ɵɵFactoryDeclaration<AccordionConfigService, never>;
static ɵprov: _angular_core.ɵɵInjectableDeclaration<AccordionConfigService>;
}
/**
* Injection token for providing global accordion configuration.
* Use this token to provide custom configuration at application startup.
*
* @example
* ```typescript
* import { ACCORDION_CONFIG } from 'ng-hub-ui-accordion';
*
* export const appConfig: ApplicationConfig = {
* providers: [
* {
* provide: ACCORDION_CONFIG,
* useValue: {
* theme: 'corporate',
* animationDuration: 500
* }
* }
* ]
* };
* ```
*/
declare const ACCORDION_CONFIG = "ACCORDION_CONFIG";
export { ACCORDION_CONFIG, AccordionComponent, AccordionConfigService, AccordionPanelComponent, AccordionPanelHeaderDirective };
export type { AccordionGlobalConfig, CollapseEvent };