@cdevhub/ngx-tw 0.2.1 → 0.3.0

package/types/cdevhub-ngx-tw-tree.d.ts

@@ -0,0 +1,189 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef, TrackByFunction } from '@angular/core';
+import { TwSize } from '@cdevhub/ngx-tw/core';
+
+/** Tri-state selection status of a tree node. */
+type TwTreeSelectionState = 'checked' | 'unchecked' | 'indeterminate';
+/** Configuration for node selection behavior. Pass any subset; unset keys fall back to the defaults. */
+interface TwTreeSelectionConfig {
+    /** Selection mode. `'single'` is scalar (one node, no cascade/indeterminate); `'multiple'` supports cascade + tri-state. `'none'` disables selection. Defaults to `'none'`. */
+    mode: 'none' | 'single' | 'multiple';
+    /** In `'multiple'` mode, selecting a branch selects all its leaf descendants and a branch renders `'indeterminate'` when only some are selected. Ignored in `'single'`/`'none'`. Defaults to `true`. */
+    cascade?: boolean;
+    /** Pre-selected node keys (matched via `trackBy`). In cascade mode these are leaf-node keys. Defaults to `[]`. */
+    initialKeys?: readonly unknown[];
+}
+/** Display configuration for the tree. Pass any subset; unset keys fall back to the defaults. */
+interface TwTreeDisplayConfig {
+    /** Row vertical density. Defaults to `'md'`. */
+    size?: TwSize;
+    /** Indentation per level, in pixels. Defaults to `16`. */
+    indent?: number;
+    /** Render connecting guide lines down the indent gutter. Defaults to `false`. */
+    showLines?: boolean;
+}
+/** Context surfaced to a `*twTreeNode` template. Generic over the node type `T`. */
+interface TwTreeNodeContext<T> {
+    /** The node data (implicit `let-node`). */
+    $implicit: T;
+    /** The node data, aliased for readability. */
+    node: T;
+    /** Zero-based depth of the node. */
+    level: number;
+    /** Whether the node is currently expanded. Always `false` for leaf nodes. */
+    expanded: boolean;
+    /** Whether the node has children (is a branch, not a leaf). */
+    hasChildren: boolean;
+    /** Tri-state selection status of this node. `'unchecked'` when selection is disabled. */
+    selectionState: TwTreeSelectionState;
+    /** Toggles this node's expand/collapse state. No-op on leaf nodes. */
+    toggle: () => void;
+    /** Expands this node. No-op on leaf nodes or when already expanded. */
+    expand: () => void;
+    /** Collapses this node. No-op when already collapsed. */
+    collapse: () => void;
+    /** Toggles this node's selection (cascades in `'multiple'` mode with `cascade` on). No-op when selection is disabled. */
+    toggleSelection: () => void;
+}
+/** Structural directive (`*twTreeNode="let node"`) declaring the per-node template. Typed as `TwTreeNodeContext<T>`. */
+declare class TreeNodeDefDirective<T = unknown> {
+    /** @internal Consumer-projected per-node template. */
+    readonly template: TemplateRef<any>;
+    /** @internal */
+    static ngTemplateContextGuard<T>(_dir: TreeNodeDefDirective<T>, _ctx: unknown): _ctx is TwTreeNodeContext<T>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreeNodeDefDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TreeNodeDefDirective<any>, "[twTreeNode]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * A hierarchical, keyboard-navigable tree-view wrapping `@angular/cdk/tree`
+ * (children-accessor model). Consumers supply the per-node template via the
+ * `*twTreeNode` structural directive and receive a typed context exposing the
+ * node, its depth/expansion/children flags, its selection state, and action
+ * functions (`toggle`, `expand`, `collapse`, `toggleSelection`).
+ *
+ * Selection is optional and managed internally (`'none' | 'single' | 'multiple'`).
+ * In `'multiple'` mode with `cascade`, selecting a branch selects all its leaf
+ * descendants and the branch reports `'indeterminate'` when partially selected.
+ * This is NOT a form control — selection is exposed via the `selectionChange`
+ * output and the public `toggleSelection` / `selectionState` methods.
+ */
+declare class TreeComponent<T = unknown> {
+    /** Root nodes of the tree. Each node's children are resolved via `childrenAccessor`. Defaults to `[]`. */
+    readonly data: _angular_core.InputSignal<readonly T[]>;
+    /** Resolves a node's direct children; return an empty array for leaf nodes. Required. */
+    readonly childrenAccessor: _angular_core.InputSignal<(node: T) => readonly T[]>;
+    /** Identifies a node across data changes and keys both expansion and selection state. When unset, node identity is used. */
+    readonly trackBy: _angular_core.InputSignal<((node: T) => unknown) | undefined>;
+    /** Node-selection behavior — `mode`, `cascade`, `initialKeys`. Accepts a partial; unset keys fall back to the defaults. Defaults to selection disabled. */
+    readonly selection: _angular_core.InputSignal<Partial<TwTreeSelectionConfig>>;
+    /** Display configuration — `size`, `indent`, `showLines`. Accepts a partial; unset keys fall back to the defaults. */
+    readonly display: _angular_core.InputSignal<Partial<TwTreeDisplayConfig>>;
+    /** Two-way bound list of expansion key values (resolved via `trackBy`) for currently-expanded nodes. Set a new array on every change; do not mutate in place. Changes when a node is expanded or collapsed. Defaults to `[]` (all collapsed). */
+    readonly expandedKeys: _angular_core.ModelSignal<readonly unknown[]>;
+    /** Fires after the selection changes by user interaction. Payload is every node whose `selectionState` is `'checked'` (selected leaves plus fully-checked branches in cascade mode). */
+    readonly selectionChange: _angular_core.OutputEmitterRef<readonly T[]>;
+    /** Fires after a node is expanded or collapsed by user interaction. Payload identifies the node and its new expansion state. */
+    readonly expandedChange: _angular_core.OutputEmitterRef<{
+        node: T;
+        expanded: boolean;
+    }>;
+    /** @internal Consumer-projected per-node template (`*twTreeNode`). */
+    readonly nodeTemplate: _angular_core.Signal<TreeNodeDefDirective<any> | undefined>;
+    /** @internal The CDK tree inside our view. */
+    private readonly cdkTree;
+    /** @internal Selected node keys. In cascade mode this holds leaf keys only; branch state is derived. */
+    private readonly selectedKeys;
+    /** @internal One-shot guard so `initialKeys` seeds selection exactly once. */
+    private seeded;
+    /** @internal Resolved selection configuration. */
+    private readonly resolvedSelection;
+    /** @internal Resolved display configuration. */
+    private readonly resolvedDisplay;
+    /** @internal Indentation width in px per level. */
+    readonly indentWidth: _angular_core.Signal<number>;
+    /** @internal Snapshot of the root nodes as a mutable array (CDK's `dataSource` rejects `readonly T[]`). */
+    readonly dataArray: _angular_core.Signal<T[]>;
+    private readonly variants;
+    readonly rootClasses: _angular_core.Signal<string>;
+    readonly spacerClasses: _angular_core.Signal<string>;
+    readonly contentClasses: _angular_core.Signal<string>;
+    constructor();
+    /** @internal Resolves a node's identity key via `trackBy`, falling back to the node itself. */
+    private keyOf;
+    /** @internal Direct children of a node (always a fresh mutable array). */
+    private childrenOf;
+    /** Whether the node has at least one child (is a branch). */
+    hasChildren(node: T): boolean;
+    /** @internal Depth-first list of every node in the tree (under collapsed parents too). */
+    private flattenAll;
+    /** @internal All leaf descendants of a node (the node itself if it is a leaf). */
+    private leavesOf;
+    /** @internal Array of length `level` used to render per-level indent spacers. */
+    indentMarkers(level: number): readonly number[];
+    /** @internal Per-node row classes (incorporates the selected state). */
+    nodeClasses(node: T): string;
+    /** @internal Builds the typed context handed to the consumer's `*twTreeNode` template. */
+    buildContext(node: T, level: number): TwTreeNodeContext<T>;
+    /**
+     * @internal `aria-selected` for `'single'` mode (boolean selection), or `null`
+     * otherwise. Multiple mode uses `aria-checked` instead so the tri-state
+     * `'mixed'` value is exposed to assistive tech on the focusable treeitem.
+     */
+    ariaSelected(node: T): 'true' | 'false' | null;
+    /**
+     * @internal Tri-state `aria-checked` for `'multiple'` mode (`'mixed'` for a
+     * partially-selected branch), or `null` otherwise. APG exposes checkbox-tree
+     * selection on the treeitem via `aria-checked`; `aria-selected` cannot carry
+     * the indeterminate state.
+     */
+    ariaChecked(node: T): 'true' | 'false' | 'mixed' | null;
+    /** @internal Adapts the consumer's `readonly`-returning accessor to CDK's mutable-array contract. */
+    readonly cdkChildrenAccessor: (node: T) => T[];
+    /** @internal CDK row-tracking function keyed via `trackBy`. */
+    readonly cdkTrackBy: TrackByFunction<T>;
+    /** @internal Keys CDK's expansion model via `trackBy`. */
+    readonly cdkExpansionKey: (node: T) => unknown;
+    /** Whether the node is currently expanded. */
+    isExpanded(node: T): boolean;
+    /** Expands the node if collapsed. Emits `expandedChange` and updates `expandedKeys` via the CDK callback. */
+    expand(node: T): void;
+    /** Collapses the node if expanded. Emits `expandedChange` and updates `expandedKeys` via the CDK callback. */
+    collapse(node: T): void;
+    /** Toggles the node's expand/collapse state. No-op on leaf nodes. */
+    toggle(node: T): void;
+    /**
+     * @internal Bridges CDK's per-node `(expandedChange)` to the `expandedKeys`
+     * model. Compare-before-write: only mutates the model and emits when the
+     * key's membership actually changes, so the model→CDK effect cannot loop.
+     */
+    onCdkExpandedChange(node: T, expanded: boolean): void;
+    /**
+     * Returns the tri-state selection status of a node. `'unchecked'` when
+     * selection is disabled.
+     *
+     * For cascade branches this walks the node's leaf descendants on each call and
+     * is invoked a few times per node per change-detection pass (row class, ARIA,
+     * context). This assumes small-to-medium trees; the component has no
+     * virtualization and is not tuned for very large data sets.
+     */
+    selectionState(node: T): TwTreeSelectionState;
+    /** Toggles selection for a node (cascades to leaf descendants in `'multiple'` mode with `cascade` on). No-op when `selection.mode === 'none'`. */
+    toggleSelection(node: T): void;
+    /** @internal Every node currently reporting `selectionState() === 'checked'`. */
+    private selectedNodes;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreeComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TreeComponent<any>, "tw-tree", ["twTree"], { "data": { "alias": "data"; "required": false; "isSignal": true; }; "childrenAccessor": { "alias": "childrenAccessor"; "required": true; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; "selection": { "alias": "selection"; "required": false; "isSignal": true; }; "display": { "alias": "display"; "required": false; "isSignal": true; }; "expandedKeys": { "alias": "expandedKeys"; "required": false; "isSignal": true; }; }, { "expandedKeys": "expandedKeysChange"; "selectionChange": "selectionChange"; "expandedChange": "expandedChange"; }, ["nodeTemplate"], never, true, never>;
+}
+/** Attribute directive (`[twTreeNodeToggle]="node"`) that toggles the given node's expansion on click. */
+declare class TreeNodeToggleDirective<T = unknown> {
+    private readonly tree;
+    /** The node whose expansion this control toggles. */
+    readonly node: _angular_core.InputSignal<T>;
+    /** @internal Toggles the node and stops the click from bubbling to row activation. */
+    onClick(event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TreeNodeToggleDirective<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<TreeNodeToggleDirective<any>, "[twTreeNodeToggle]", never, { "node": { "alias": "twTreeNodeToggle"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { TreeComponent, TreeNodeDefDirective, TreeNodeToggleDirective };
+export type { TwTreeDisplayConfig, TwTreeNodeContext, TwTreeSelectionConfig, TwTreeSelectionState };

package/types/cdevhub-ngx-tw.d.ts

@@ -19,6 +19,7 @@ export * from '@cdevhub/ngx-tw/popover';
 export * from '@cdevhub/ngx-tw/dialog';
 export * from '@cdevhub/ngx-tw/command-palette';
 export * from '@cdevhub/ngx-tw/toast';
+export * from '@cdevhub/ngx-tw/transfer';
 export * from '@cdevhub/ngx-tw/form-field';
 export * from '@cdevhub/ngx-tw/switch';
 export * from '@cdevhub/ngx-tw/checkbox';
@@ -26,6 +27,9 @@ export * from '@cdevhub/ngx-tw/radio';
 export * from '@cdevhub/ngx-tw/select';
 export * from '@cdevhub/ngx-tw/input';
 export * from '@cdevhub/ngx-tw/textarea';
+export * from '@cdevhub/ngx-tw/file-upload';
+export * from '@cdevhub/ngx-tw/number-input';
+export * from '@cdevhub/ngx-tw/tags-input';
 export * from '@cdevhub/ngx-tw/spinner';
 export * from '@cdevhub/ngx-tw/progress-bar';
 export * from '@cdevhub/ngx-tw/skeleton';
@@ -47,3 +51,6 @@ export * from '@cdevhub/ngx-tw/stat';
 export * from '@cdevhub/ngx-tw/combobox';
 export * from '@cdevhub/ngx-tw/empty-state';
 export * from '@cdevhub/ngx-tw/sheet';
+export * from '@cdevhub/ngx-tw/aspect-ratio';
+export * from '@cdevhub/ngx-tw/tree';
+export * from '@cdevhub/ngx-tw/theme';