@ngneers/controls 0.0.1-next.0

package/types/ngneers-controls-roving-focus.d.ts

@@ -0,0 +1,107 @@
+import * as _angular_core from '@angular/core';
+import { Signal, InjectionToken } from '@angular/core';
+
+type RovingOrientation = 'horizontal' | 'vertical';
+type RovingMode = 'tabindex' | 'activedescendant';
+interface RovingItemRef {
+    readonly id: string;
+    readonly element: HTMLElement;
+    /**
+     * Optional reactive disabled flag. When it reads `true`, the item is skipped
+     * by keyboard navigation (`next`/`prev`/`first`/`last`) and pointer
+     * `activate()`. Absent (undefined) is treated as enabled.
+     */
+    readonly disabled?: Signal<boolean>;
+}
+declare const ROVING_GROUP: InjectionToken<NgnRovingGroup>;
+declare class NgnRovingGroup {
+    /**
+     * Which arrow keys move the active item: `'horizontal'` uses Left/Right,
+     * `'vertical'` uses Up/Down. Home/End always jump to first/last.
+     * @default 'horizontal'
+     */
+    readonly orientation: _angular_core.InputSignal<RovingOrientation>;
+    /**
+     * How the active item is exposed. `'tabindex'` moves the tab stop (and DOM
+     * focus) between items; `'activedescendant'` keeps focus on the group and
+     * points `aria-activedescendant` at the active item.
+     * @default 'tabindex'
+     */
+    readonly rovingMode: _angular_core.InputSignal<RovingMode>;
+    /**
+     * Whether keyboard navigation wraps around the ends of the list instead of
+     * stopping at the first/last item.
+     * @default false
+     */
+    readonly rovingWrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Emits the index of the newly active item whenever it changes via keyboard,
+     * pointer, or {@link setActive}. Not emitted by {@link syncActiveIndex}.
+     */
+    readonly activeItemChange: _angular_core.OutputEmitterRef<number>;
+    private readonly _host;
+    private readonly _items;
+    /** Items in DOM order. */
+    readonly items: Signal<RovingItemRef[]>;
+    readonly activeIndex: _angular_core.WritableSignal<number>;
+    /**
+     * Tracks the previously active item's id so we can decide whether to call
+     * `.focus()`. Initialized to `null` — the first effect pass sets it without
+     * focusing; subsequent passes focus when the id actually changes.
+     */
+    private _prevActiveId;
+    /**
+     * When set, the next focus-mode effect pass updates the tab stop / attributes
+     * but does NOT move DOM focus. Consumed (reset) by that pass. Lets consumers
+     * sync the active item to a programmatic selection (e.g. a radio group's
+     * `value` change) without stealing focus into the group.
+     */
+    private _suppressFocus;
+    constructor();
+    register(item: RovingItemRef): void;
+    unregister(item: RovingItemRef): void;
+    activate(target: RovingItemRef): void;
+    next(): void;
+    prev(): void;
+    first(): void;
+    last(): void;
+    /** Set the active item by index (clamped to range); emits activeItemChange. */
+    setActive(index: number): void;
+    /**
+     * Move the tab stop to `index` WITHOUT moving DOM focus or emitting
+     * `activeItemChange`. For syncing the roving state to a programmatic
+     * selection (e.g. a radio group's `value` changing from code) where stealing
+     * focus into the group would be wrong.
+     */
+    syncActiveIndex(index: number): void;
+    private _onKeydown;
+    private _move;
+    private _setActive;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnRovingGroup, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgnRovingGroup, "[ngnRovingGroup]", ["ngnRovingGroup"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "rovingMode": { "alias": "rovingMode"; "required": false; "isSignal": true; }; "rovingWrap": { "alias": "rovingWrap"; "required": false; "isSignal": true; }; }, { "activeItemChange": "activeItemChange"; }, never, never, true, never>;
+}
+declare class NgnRovingItem implements RovingItemRef {
+    private readonly _injectedGroup;
+    /**
+     * The {@link NgnRovingGroup} this item belongs to. Pass a group reference when
+     * the item is not a DOM descendant of its group; leave empty/undefined to use
+     * the nearest ancestor group via dependency injection.
+     */
+    readonly ngnRovingItem: _angular_core.InputSignal<"" | NgnRovingGroup | undefined>;
+    readonly element: HTMLElement;
+    readonly id: string;
+    /**
+     * Reactive disabled flag for this item. Consumers (e.g. `ngn-radio`) set it
+     * so the group's keyboard navigation and pointer `activate()` skip the item.
+     */
+    readonly disabled: _angular_core.WritableSignal<boolean>;
+    private readonly _group;
+    /** Whether this item is currently the active item in its group. */
+    readonly isActive: Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnRovingItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgnRovingItem, "[ngnRovingItem]", ["ngnRovingItem"], { "ngnRovingItem": { "alias": "ngnRovingItem"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgnRovingGroup, NgnRovingItem, ROVING_GROUP };
+export type { RovingItemRef, RovingMode, RovingOrientation };

package/types/ngneers-controls-scroll-shadow.d.ts

@@ -0,0 +1,25 @@
+import * as _angular_core from '@angular/core';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+
+declare class NgnScrollShadow {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"scrollShadow", ["root", "scrolled-start", "scrolled-end", "scrolled-top", "scrolled-bottom"], readonly []>>;
+    private readonly _el;
+    private readonly _injector;
+    /**
+     * Which scroll axis to track and add shadow classes for.
+     * @default 'horizontal'
+     */
+    readonly ngnScrollShadow: _angular_core.InputSignal<"horizontal" | "vertical" | "both">;
+    /**
+     * Element that receives the shadow classes. Defaults to the host element (which
+     * is also the scroll container being observed).
+     * @default undefined
+     */
+    readonly scrollShadowTarget: _angular_core.InputSignal<HTMLElement | undefined>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnScrollShadow, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgnScrollShadow, "[ngnScrollShadow]", never, { "ngnScrollShadow": { "alias": "ngnScrollShadow"; "required": false; "isSignal": true; }; "scrollShadowTarget": { "alias": "scrollShadowTarget"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgnScrollShadow };

package/types/ngneers-controls-scroller.d.ts

@@ -0,0 +1,151 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef, AfterViewInit } from '@angular/core';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+import { AllKeysOfUnion } from '@ngneers/controls/utils';
+import { NgnBase } from '@ngneers/controls/base';
+import * as i1 from '@ngneers/controls/directives';
+
+declare abstract class ScrollerTemplates<T> extends NgnBase<'scroller'> {
+    /**
+     * The template to be used for rendering each item in the scroller.
+     * Can also be set using the `item` content child.
+     */
+    readonly templateItem: _angular_core.InputSignal<TemplateRef<{
+        $implicit: T;
+        index: number;
+    }> | null>;
+    private readonly _userItemTemplate;
+    protected readonly itemTemplate: _angular_core.Signal<TemplateRef<{
+        $implicit: T;
+        index: number;
+    }> | null>;
+    /**
+     * Template types for the scroller.
+     * Can be used with the {@link NgnTemplate} directive for type safe ng-templates.
+     */
+    readonly templateTypes: {
+        item: {
+            $implicit: T;
+            index: number;
+        };
+    } & {
+        $implicit: {
+            item: Partial<{
+                $implicit: T;
+                index: number;
+            }>;
+        };
+    };
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ScrollerTemplates<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ScrollerTemplates<any>, never, never, { "templateItem": { "alias": "templateItem"; "required": false; "isSignal": true; }; }, {}, ["_userItemTemplate"], never, true, never>;
+}
+
+/**
+ * @category control
+ */
+declare class NgnScroller<T> extends ScrollerTemplates<T> {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"scroller", ["root", "virtual", "item", "item-sticky"], readonly []>>;
+    private readonly _el;
+    private readonly _scrollAmount;
+    /**
+     * The items to be displayed in the scroller.
+     * This is a required input and should be an array of items of type {@link T}.
+     */
+    readonly items: _angular_core.InputSignal<readonly T[]>;
+    /**
+     * The field of the item that uniquely identifies it.
+     */
+    readonly fieldId: _angular_core.InputSignal<keyof T | undefined>;
+    /**
+     * Whether the scroller should use virtual scrolling.
+     * When set to true, the scroller will only render the items that are currently visible
+     * on the screen, improving performance for large lists.
+     *
+     * When virtual scrolling is enabled, {@link itemHeight} must be set to a non-zero value.
+     * @default `false`
+     */
+    readonly virtual: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When {@link virtual} scrolling is enabled, this input is required to define the height of each item in pixels.
+     */
+    readonly itemHeight: _angular_core.InputSignal<number | undefined>;
+    /**
+     * When {@link virtual} scrolling is enabled, this input defines the number of items to be rendered above and below the visible area.
+     * This can help to reduce flickering when scrolling.
+     * @default `2`
+     */
+    readonly virtualPadding: _angular_core.InputSignal<number>;
+    /**
+     * Determines whether the scroller should have a tab index and be focusable.
+     * @default `false`
+     */
+    readonly focusable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Determines whether an item is sticky or not.
+     * If set, the scroller will stick the items with a truthy value for the specified field to the top of the scroller.
+     */
+    readonly fieldSticky: _angular_core.InputSignal<AllKeysOfUnion<T> | null>;
+    /**
+     * Viewport size — tracks the scroll ancestor's dimensions so that virtual
+     * scrolling works when an outer element handles overflow (e.g. table wrapper).
+     */
+    private readonly _viewportSize;
+    private readonly _itemHeightPx;
+    /**
+     * Vertical offset between the scroll container's top and the scroller element.
+     * Non-zero when a parent (e.g. table wrapper) owns the scroll and the scroller
+     * is positioned below other content (e.g. a sticky header row).
+     */
+    private readonly _scrollOffset;
+    private readonly _visibleItemCount;
+    private readonly _scrollTop;
+    /**
+     * The index of the first item that is rendered in the (virtual) scroller.
+     */
+    readonly itemStartIndex: _angular_core.Signal<number>;
+    private readonly _itemEndIndex;
+    protected readonly paddingTop: _angular_core.Signal<number>;
+    protected readonly paddingBottom: _angular_core.Signal<number>;
+    protected readonly visibleItems: _angular_core.Signal<{
+        item: T;
+        index: number;
+    }[]>;
+    /**
+     * Returns the last sticky item that is not rendered regularly in the list.
+     * Required because sticky items might need to be rendered longer than they would.
+     * Only applicable when virtual scrolling is enabled.
+     */
+    protected readonly latestStickyItem: _angular_core.Signal<{
+        item: T;
+        index: number;
+    } | null>;
+    constructor();
+    /**
+     * Scrolls the item with the given index into view.
+     * @param index The index of the item to scroll to.
+     */
+    scrollToIndex(index: number, position?: ScrollLogicalPosition): void;
+    protected track(item: {
+        item: T;
+        index: number;
+    }): unknown;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnScroller<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnScroller<any>, "ngn-scroller, [ngn-scroller]", never, { "items": { "alias": "items"; "required": true; "isSignal": true; }; "fieldId": { "alias": "fieldId"; "required": false; "isSignal": true; }; "virtual": { "alias": "virtual"; "required": false; "isSignal": true; }; "itemHeight": { "alias": "itemHeight"; "required": false; "isSignal": true; }; "virtualPadding": { "alias": "virtualPadding"; "required": false; "isSignal": true; }; "focusable": { "alias": "focusable"; "required": false; "isSignal": true; }; "fieldSticky": { "alias": "fieldSticky"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.NgnScrollAmount; inputs: { "ngnScrollAmountContainer": "scrollContainer"; }; outputs: {}; }]>;
+}
+
+declare class NgnScrollerItem implements AfterViewInit {
+    private readonly _el;
+    /**
+     * The item bound to this element. Used to resolve its sticky state and apply
+     * the scroller's item classes from the enclosing {@link NgnScroller}.
+     */
+    readonly ngnScrollerItem: _angular_core.InputSignal<object>;
+    private readonly _scroller;
+    ngAfterViewInit(): void;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnScrollerItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgnScrollerItem, "[ngnScrollerItem]", never, { "ngnScrollerItem": { "alias": "ngnScrollerItem"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgnScroller, NgnScrollerItem };

package/types/ngneers-controls-select-button.d.ts

@@ -0,0 +1,51 @@
+import * as _angular_core from '@angular/core';
+import * as _ngneers_controls_api_ng from '@ngneers/controls/api/ng';
+import * as _ngneers_controls_themes from '@ngneers/controls-themes';
+import { ValueControlBase } from '@ngneers/controls/base';
+import { maybeCallback } from '@ngneers/controls/utils';
+import { NgnActionItemFlat, NgnItem } from '@ngneers/controls/api';
+
+/**
+ * @category control
+ */
+declare class NgnSelectButton<V> extends ValueControlBase<'selectButton', V> {
+    protected readonly theme: _ngneers_controls_api_ng.ControlTemplateInfo<_ngneers_controls_themes.ControlTemplate<"select-button", ["root", "invalid"], readonly [{
+        readonly class: "group";
+        readonly template: _ngneers_controls_themes.ControlTemplate<"button-group", ["root", "vertical", "horizontal"], readonly [{
+            readonly class: "button";
+            readonly template: _ngneers_controls_themes.ControlTemplate<"button", ["root", "inline", "loading", `kind-${string}`, `color-${string}`], readonly []>;
+            readonly projected: true;
+        }, {
+            readonly class: "toggle-button";
+            readonly template: _ngneers_controls_themes.ControlTemplate<"toggle-button", ["root", "invalid", "button", "label", "active", "placeholder", "placeholder-active"], readonly []>;
+            readonly projected: true;
+        }]>;
+    }, {
+        readonly class: "button";
+        readonly template: _ngneers_controls_themes.ControlTemplate<"toggle-button", ["root", "invalid", "button", "label", "active", "placeholder", "placeholder-active"], readonly []>;
+    }]>>;
+    /**
+     * Defines the orientation of the select buttons.
+     * - 'auto' - The orientation is determined based on the available space.
+     * - 'horizontal' - The buttons are arranged horizontally. (Default for `auto` if enough space)
+     * - 'vertical' - The buttons are arranged vertically.
+     * @default 'auto'
+     */
+    readonly orientation: _angular_core.InputSignal<"vertical" | "horizontal" | "auto">;
+    /**
+     * Defines the options for the select button.
+     */
+    readonly options: _angular_core.InputSignal<readonly NgnActionItemFlat<NgnItem<unknown, V>>[]>;
+    /**
+     * When `true`, allows unselecting the currently selected option by clicking on it again.
+     * If `false`, clicking on the selected option will not change the selection.
+     * @default false
+     */
+    readonly allowUnselect: _angular_core.InputSignal<boolean>;
+    protected readonly maybeCallback: typeof maybeCallback;
+    protected valueChange(value: V): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgnSelectButton<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgnSelectButton<any>, "ngn-select-button", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": true; "isSignal": true; }; "allowUnselect": { "alias": "allowUnselect"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { NgnSelectButton };