ngx-com 0.0.1 → 0.0.4

package/types/ngx-com-components-spinner.d.ts

@@ -0,0 +1,120 @@
+import * as i0 from '@angular/core';
+import { InputSignal, Signal } from '@angular/core';
+
+/** Spinner size variants. */
+type SpinnerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Spinner color variants. */
+type SpinnerColor = 'current' | 'primary' | 'accent' | 'warn' | 'success' | 'muted';
+/** Label position relative to spinner. */
+type SpinnerLabelPosition = 'right' | 'bottom';
+/**
+ * CVA variants for the spinning circle element.
+ *
+ * Creates a circular track with a faded ring and a colored arc that rotates.
+ * Uses `border` for the track and `border-t-*` for the spinning arc.
+ *
+ * @tokens `--color-primary`, `--color-accent`, `--color-warn`, `--color-success`, `--color-muted-foreground`
+ */
+declare const spinnerVariants: (props?: {
+    size?: SpinnerSize;
+    color?: SpinnerColor;
+}) => string;
+/**
+ * CVA variants for the spinner container layout.
+ *
+ * Controls flex direction and gap based on label position.
+ * Only applies when a visible label is present.
+ *
+ * @tokens none (layout only)
+ */
+declare const spinnerContainerVariants: (props?: {
+    labelPosition?: SpinnerLabelPosition;
+}) => string;
+/** Label font size classes mapped to spinner size. */
+declare const SPINNER_LABEL_SIZES: Record<SpinnerSize, string>;
+
+/**
+ * A minimal, CSS-only loading indicator.
+ *
+ * Drop-in anywhere: inside buttons, next to inline text, centered in cards,
+ * or as a page-level overlay. The animation is fast (0.6s) for a snappy feel.
+ *
+ * @tokens `--color-primary`, `--color-accent`, `--color-warn`, `--color-success`, `--color-muted-foreground`
+ *
+ * @example Simplest usage (inherits parent text color)
+ * ```html
+ * <com-spinner />
+ * ```
+ *
+ * @example Inside a button (inline, inherits button text color)
+ * ```html
+ * <button class="btn-primary" [disabled]="saving">
+ *   @if (saving) {
+ *     <com-spinner size="xs" />
+ *   }
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example With visible label
+ * ```html
+ * <com-spinner label="Loading results..." />
+ * ```
+ *
+ * @example Centered in a card
+ * ```html
+ * <div class="flex items-center justify-center p-8">
+ *   <com-spinner size="lg" color="primary" label="Loading..." labelPosition="bottom" />
+ * </div>
+ * ```
+ *
+ * @example Inline with text
+ * ```html
+ * <p class="text-muted-foreground">
+ *   <com-spinner size="xs" /> Checking availability...
+ * </p>
+ * ```
+ *
+ * @example Color variants
+ * ```html
+ * <com-spinner color="primary" />
+ * <com-spinner color="accent" />
+ * <com-spinner color="warn" />
+ * ```
+ *
+ * @example Large page-level
+ * ```html
+ * <com-spinner size="xl" color="primary" label="Preparing your dashboard..." labelPosition="bottom" />
+ * ```
+ */
+declare class ComSpinner {
+    /**
+     * Optional loading text (e.g., "Loading...", "Saving...").
+     * When omitted, "Loading" is rendered for screen readers only (sr-only).
+     * When provided, the label is visible next to or below the spinner.
+     */
+    readonly label: InputSignal<string | undefined>;
+    /**
+     * Position of the label relative to the spinner.
+     * Only relevant when a visible `label` is provided.
+     */
+    readonly labelPosition: InputSignal<SpinnerLabelPosition>;
+    /** Size of the spinner. */
+    readonly size: InputSignal<SpinnerSize>;
+    /**
+     * Color of the spinner.
+     * `current` inherits from `currentColor` to match surrounding text.
+     */
+    readonly color: InputSignal<SpinnerColor>;
+    /** @internal Computed classes for the spinning circle. */
+    protected readonly spinnerClasses: Signal<string>;
+    /** @internal Computed classes for the container/host. */
+    protected readonly containerClasses: Signal<string>;
+    /** @internal Computed label font size class. */
+    protected readonly labelSizeClass: Signal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComSpinner, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ComSpinner, "com-spinner", ["comSpinner"], { "label": { "alias": "label"; "required": false; "isSignal": true; }; "labelPosition": { "alias": "labelPosition"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { ComSpinner, SPINNER_LABEL_SIZES, spinnerContainerVariants, spinnerVariants };
+export type { SpinnerColor, SpinnerLabelPosition, SpinnerSize };

package/types/ngx-com-components-tabs.d.ts

@@ -0,0 +1,396 @@
+import * as i0 from '@angular/core';
+import { TemplateRef, InputSignal, InputSignalWithTransform, OutputEmitterRef, Signal, WritableSignal, ModelSignal, ElementRef } from '@angular/core';
+import { VariantProps } from 'class-variance-authority';
+
+/**
+ * Marker directive for custom tab label templates.
+ *
+ * Provides a custom label template for rich tab headers (icons, badges, counters).
+ * Applied to an `<ng-template>` inside `<ui-tab>`.
+ *
+ * @example
+ * ```html
+ * <com-tab>
+ *   <ng-template comTabLabel>
+ *     <svg class="w-4 h-4">...</svg>
+ *     <span>Settings</span>
+ *     <span class="bg-warn text-warn-foreground text-xs rounded-pill px-1.5">3</span>
+ *   </ng-template>
+ *   <p>Tab content here.</p>
+ * </com-tab>
+ * ```
+ */
+declare class TabLabelDirective {
+    readonly templateRef: TemplateRef<void>;
+    static ngTemplateContextGuard(_dir: TabLabelDirective, ctx: unknown): ctx is void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TabLabelDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TabLabelDirective, "ng-template[comTabLabel]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Marker directive for lazy tab content rendering.
+ *
+ * Content wrapped in `<ng-template comTabContent>` is only instantiated
+ * when the tab becomes active for the first time.
+ *
+ * @example Lazy loaded content
+ * ```html
+ * <com-tab label="Analytics">
+ *   <ng-template comTabContent>
+ *     <app-analytics-dashboard />
+ *   </ng-template>
+ * </com-tab>
+ * ```
+ *
+ * @example Combined with @defer
+ * ```html
+ * <com-tab label="Reports">
+ *   <ng-template comTabContent>
+ *     &#64;defer {
+ *       <app-report-builder />
+ *     } &#64;loading {
+ *       <p>Loading reports...</p>
+ *     }
+ *   </ng-template>
+ * </com-tab>
+ * ```
+ */
+declare class TabContentDirective {
+    readonly templateRef: TemplateRef<void>;
+    static ngTemplateContextGuard(_dir: TabContentDirective, ctx: unknown): ctx is void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TabContentDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TabContentDirective, "ng-template[comTabContent]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Individual tab definition component.
+ *
+ * This is a **definition component** — it doesn't render anything itself.
+ * It provides a label and content template to the parent `TabGroupComponent`.
+ *
+ * @example Basic usage
+ * ```html
+ * <com-tab label="Overview">
+ *   <p>Overview content.</p>
+ * </com-tab>
+ * ```
+ *
+ * @example Custom label with icon
+ * ```html
+ * <com-tab>
+ *   <ng-template comTabLabel>
+ *     <svg class="w-4 h-4"><!-- icon --></svg>
+ *     <span>Settings</span>
+ *   </ng-template>
+ *   <p>Settings content.</p>
+ * </com-tab>
+ * ```
+ *
+ * @example Lazy loaded content
+ * ```html
+ * <com-tab label="Analytics">
+ *   <ng-template comTabContent>
+ *     <app-heavy-dashboard />
+ *   </ng-template>
+ * </com-tab>
+ * ```
+ *
+ * @example Closable tab
+ * ```html
+ * <com-tab label="Document" [closable]="true" (closed)="onClose()">
+ *   <p>Document content.</p>
+ * </com-tab>
+ * ```
+ */
+declare class TabComponent {
+    /** Plain text label; ignored if `[comTabLabel]` template is provided. */
+    readonly label: InputSignal<string>;
+    /** Prevents selection when true. */
+    readonly disabled: InputSignalWithTransform<boolean, unknown>;
+    /** Shows a close/remove button on the tab. */
+    readonly closable: InputSignalWithTransform<boolean, unknown>;
+    /** Emitted when the close button is clicked. */
+    readonly closed: OutputEmitterRef<void>;
+    /** Custom label template (queried from content). */
+    readonly customLabel: Signal<TabLabelDirective | undefined>;
+    /** Lazy content template (queried from content). */
+    readonly lazyContent: Signal<TabContentDirective | undefined>;
+    /** Implicit content template from ng-content. */
+    readonly implicitContent: Signal<TemplateRef<unknown> | undefined>;
+    /** Whether this tab is currently active. Set by TabGroupComponent. */
+    readonly isActive: WritableSignal<boolean>;
+    /** Whether this tab content has been rendered at least once. */
+    readonly hasBeenActivated: WritableSignal<boolean>;
+    /**
+     * Returns the label template if provided, otherwise null.
+     * Parent uses this to decide between string label or template.
+     */
+    readonly labelTemplate: Signal<TemplateRef<void> | null>;
+    /**
+     * Returns the content template: lazy template if present, else implicit content.
+     */
+    readonly contentTemplate: Signal<TemplateRef<unknown> | undefined>;
+    /**
+     * Whether this tab uses lazy loading.
+     */
+    readonly isLazy: Signal<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TabComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<TabComponent, "com-tab", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "closable": { "alias": "closable"; "required": false; "isSignal": true; }; }, { "closed": "closed"; }, ["customLabel", "lazyContent"], ["*"], true, never>;
+}
+
+type TabVariant = 'underline' | 'pill' | 'outline' | 'solid';
+type TabSize = 'sm' | 'md' | 'lg';
+type TabColor = 'primary' | 'accent' | 'muted';
+type TabAlignment = 'start' | 'center' | 'end' | 'stretch';
+declare const tabItemVariants: (props?: {
+    variant?: TabVariant;
+    size?: TabSize;
+    color?: TabColor;
+    active?: boolean;
+}) => string;
+type TabItemVariants = VariantProps<typeof tabItemVariants>;
+declare const tabHeaderVariants: (props?: {
+    alignment?: TabAlignment;
+    variant?: TabVariant;
+}) => string;
+type TabHeaderVariants = VariantProps<typeof tabHeaderVariants>;
+declare const tabScrollButtonVariants: (props?: {
+    direction?: 'left' | 'right';
+    variant?: TabVariant;
+}) => string;
+type TabScrollButtonVariants = VariantProps<typeof tabScrollButtonVariants>;
+declare const tabCloseButtonVariants: (props?: {
+    size?: TabSize;
+}) => string;
+type TabCloseButtonVariants = VariantProps<typeof tabCloseButtonVariants>;
+declare const tabPanelVariants: (props?: {
+    animated?: boolean;
+}) => string;
+type TabPanelVariants = VariantProps<typeof tabPanelVariants>;
+
+/** Event emitted when the selected tab changes. */
+interface TabChangeEvent {
+    index: number;
+    tab: TabComponent;
+}
+/**
+ * Tab group component — orchestrates tab state and renders header + panels.
+ *
+ * @tokens `--color-primary`, `--color-primary-foreground`, `--color-accent`, `--color-accent-foreground`,
+ *         `--color-muted`, `--color-muted-foreground`, `--color-border`, `--color-ring`,
+ *         `--color-disabled`, `--color-disabled-foreground`
+ *
+ * @example Basic usage
+ * ```html
+ * <com-tab-group>
+ *   <com-tab label="Overview">
+ *     <p>Overview content.</p>
+ *   </com-tab>
+ *   <com-tab label="Settings">
+ *     <p>Settings content.</p>
+ *   </com-tab>
+ * </com-tab-group>
+ * ```
+ *
+ * @example With variants
+ * ```html
+ * <com-tab-group variant="pill" color="accent">
+ *   <com-tab label="Tab 1"><p>Pill style.</p></com-tab>
+ *   <com-tab label="Tab 2"><p>Content.</p></com-tab>
+ * </com-tab-group>
+ * ```
+ *
+ * @example Two-way binding
+ * ```html
+ * <com-tab-group [(selectedIndex)]="currentTab">
+ *   <com-tab label="One"><p>First.</p></com-tab>
+ *   <com-tab label="Two"><p>Second.</p></com-tab>
+ * </com-tab-group>
+ * ```
+ *
+ * @example Lazy loaded content
+ * ```html
+ * <com-tab-group>
+ *   <com-tab label="Summary"><p>Loads immediately.</p></com-tab>
+ *   <com-tab label="Analytics">
+ *     <ng-template comTabContent>
+ *       <app-analytics-dashboard />
+ *     </ng-template>
+ *   </com-tab>
+ * </com-tab-group>
+ * ```
+ */
+declare class TabGroupComponent {
+    /** Unique ID for this tab group instance. */
+    readonly baseId: string;
+    /** Visual treatment of tab buttons. */
+    readonly variant: InputSignal<TabVariant>;
+    /** Controls tab button padding and font size. */
+    readonly size: InputSignal<TabSize>;
+    /** Active tab color. */
+    readonly color: InputSignal<TabColor>;
+    /** Tab alignment within the header. */
+    readonly alignment: InputSignal<TabAlignment>;
+    /** Two-way bindable selected tab index. */
+    readonly selectedIndex: ModelSignal<number>;
+    /** Enable/disable panel transition animation. */
+    readonly animationEnabled: InputSignalWithTransform<boolean, unknown>;
+    /** When true, keeps inactive tab DOM alive (hidden); when false, destroys inactive tab content. */
+    readonly preserveContent: InputSignalWithTransform<boolean, unknown>;
+    /** Emits when the selected tab changes with index and tab reference. */
+    readonly selectedTabChange: OutputEmitterRef<TabChangeEvent>;
+    /** Emits the index of the focused (not yet selected) tab for keyboard navigation feedback. */
+    readonly focusChange: OutputEmitterRef<number>;
+    /** All TabComponent children. */
+    readonly tabs: Signal<readonly TabComponent[]>;
+    /** The currently active tab. */
+    readonly activeTab: Signal<TabComponent | undefined>;
+    /** ID of the active tab button. */
+    readonly activeTabId: Signal<string>;
+    /** ID of the active panel. */
+    readonly activePanelId: Signal<string>;
+    /** Classes for panel container. */
+    readonly panelClasses: Signal<string>;
+    constructor();
+    getTabId(index: number): string;
+    getPanelId(index: number): string;
+    /**
+     * Determines whether a tab's content should be rendered.
+     * For lazy tabs, content is only rendered after first activation.
+     */
+    shouldRenderTab(tab: TabComponent, index: number): boolean;
+    protected onTabSelected(index: number): void;
+    protected onTabFocused(index: number): void;
+    protected onTabClosed(index: number): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TabGroupComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<TabGroupComponent, "com-tab-group", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "alignment": { "alias": "alignment"; "required": false; "isSignal": true; }; "selectedIndex": { "alias": "selectedIndex"; "required": false; "isSignal": true; }; "animationEnabled": { "alias": "animationEnabled"; "required": false; "isSignal": true; }; "preserveContent": { "alias": "preserveContent"; "required": false; "isSignal": true; }; }, { "selectedIndex": "selectedIndexChange"; "selectedTabChange": "selectedTabChange"; "focusChange": "focusChange"; }, ["tabs"], never, true, never>;
+}
+
+/**
+ * Tab link directive for route-driven navigation tabs.
+ *
+ * Applied to anchor or button elements inside `com-tab-nav-bar`.
+ * Automatically detects active state from `routerLinkActive` if present.
+ *
+ * @example Basic usage with router
+ * ```html
+ * <nav com-tab-nav-bar>
+ *   <a comTabLink routerLink="overview" routerLinkActive>Overview</a>
+ *   <a comTabLink routerLink="settings" routerLinkActive>Settings</a>
+ * </nav>
+ * ```
+ *
+ * @example Manual active state control
+ * ```html
+ * <a comTabLink [active]="isOverviewActive">Overview</a>
+ * ```
+ *
+ * @example Disabled link
+ * ```html
+ * <a comTabLink [disabled]="true">Coming Soon</a>
+ * ```
+ */
+declare class TabLinkDirective {
+    private readonly routerLinkActive;
+    private readonly elementRef;
+    /** Manual active state control. */
+    readonly active: InputSignalWithTransform<boolean, unknown>;
+    /** Prevents interaction when true. */
+    readonly disabled: InputSignalWithTransform<boolean, unknown>;
+    /** Visual variant (inherited from parent nav bar or set directly). */
+    readonly variant: InputSignal<TabVariant>;
+    /** Size (inherited from parent nav bar or set directly). */
+    readonly size: InputSignal<TabSize>;
+    /** Color (inherited from parent nav bar or set directly). */
+    readonly color: InputSignal<TabColor>;
+    /** Additional CSS classes. */
+    readonly userClass: InputSignal<string>;
+    /**
+     * Reactive signal from RouterLinkActive.isActiveChange.
+     * Converts the EventEmitter to a signal for proper reactivity.
+     */
+    private readonly routerLinkActiveState;
+    /**
+     * Resolved active state — uses routerLinkActive if available, otherwise input.
+     */
+    readonly isActive: Signal<boolean>;
+    /** Computed host class from CVA + consumer overrides. */
+    readonly computedClass: Signal<string>;
+    /** Focus this tab link element. */
+    focus(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TabLinkDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TabLinkDirective, "a[comTabLink], button[comTabLink]", never, { "active": { "alias": "active"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Tab navigation bar component for route-driven tabs.
+ *
+ * Renders a styled, scrollable row of links that map to routes.
+ * Content is handled by `<router-outlet>`.
+ *
+ * @tokens `--color-primary`, `--color-accent`, `--color-muted`, `--color-muted-foreground`,
+ *         `--color-border`, `--color-ring`, `--color-disabled`, `--color-disabled-foreground`
+ *
+ * @example Basic usage
+ * ```html
+ * <nav com-tab-nav-bar>
+ *   <a comTabLink routerLink="overview" routerLinkActive>Overview</a>
+ *   <a comTabLink routerLink="settings" routerLinkActive>Settings</a>
+ * </nav>
+ * <router-outlet />
+ * ```
+ *
+ * @example With variants
+ * ```html
+ * <nav com-tab-nav-bar variant="pill" color="accent" size="sm">
+ *   <a comTabLink routerLink="grid" routerLinkActive>Grid</a>
+ *   <a comTabLink routerLink="list" routerLinkActive>List</a>
+ * </nav>
+ * ```
+ */
+declare class TabNavBarComponent {
+    private readonly destroyRef;
+    /** Unique ID for this nav bar instance. */
+    readonly baseId: string;
+    /** Visual treatment of tab links. */
+    readonly variant: InputSignal<TabVariant>;
+    /** Controls tab link padding and font size. */
+    readonly size: InputSignal<TabSize>;
+    /** Active tab color. */
+    readonly color: InputSignal<TabColor>;
+    /** Tab alignment within the bar. */
+    readonly alignment: InputSignal<TabAlignment>;
+    /** All TabLinkDirective children. */
+    readonly tabLinks: Signal<readonly TabLinkDirective[]>;
+    readonly scrollContainer: Signal<ElementRef<HTMLElement> | undefined>;
+    private readonly scrollLeftValue;
+    private readonly containerWidth;
+    private readonly scrollWidth;
+    protected readonly indicatorLeft: WritableSignal<number>;
+    protected readonly indicatorWidth: WritableSignal<number>;
+    private keyManager;
+    private resizeObserver;
+    /** The currently active link. */
+    readonly activeLink: Signal<TabLinkDirective | undefined>;
+    readonly hasOverflow: Signal<boolean>;
+    readonly showScrollLeft: Signal<boolean>;
+    readonly showScrollRight: Signal<boolean>;
+    readonly headerClasses: Signal<string>;
+    readonly scrollLeftClasses: Signal<string>;
+    readonly scrollRightClasses: Signal<string>;
+    readonly indicatorColorClass: Signal<string>;
+    constructor();
+    scrollLeft(): void;
+    scrollRight(): void;
+    protected onScroll(): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    private setupResizeObserver;
+    private updateScrollState;
+    private setupKeyManager;
+    private createKeyManagerItems;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TabNavBarComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<TabNavBarComponent, "com-tab-nav-bar, nav[com-tab-nav-bar]", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "alignment": { "alias": "alignment"; "required": false; "isSignal": true; }; }, {}, ["tabLinks"], ["*"], true, never>;
+}
+
+export { TabComponent, TabContentDirective, TabGroupComponent, TabLabelDirective, TabLinkDirective, TabNavBarComponent, tabCloseButtonVariants, tabHeaderVariants, tabItemVariants, tabPanelVariants, tabScrollButtonVariants };
+export type { TabAlignment, TabChangeEvent, TabCloseButtonVariants, TabColor, TabHeaderVariants, TabItemVariants, TabPanelVariants, TabScrollButtonVariants, TabSize, TabVariant };