ngx-json-treeview/types/ngx-json-treeview.d.ts

Display object data in an expandable JSON tree view.

import * as _angular_core from '@angular/core';
import * as _angular_cdk_testing from '@angular/cdk/testing';
import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';

/**
 * Represents a segment (node) within the JSON tree structure.
 * Each segment corresponds to a key-value pair in an object, an item in an
 * array, or the root value itself, providing context and state for rendering.
 */
interface Segment {
    /** The key (for objects) or index (for arrays). */
    key: string;
    /** The actual JavaScript value represented by this segment. */
    value: any;
    /** The JavaScript data type of the value. */
    type?: string;
    /** A string representation of the value, used for display purposes. */
    description: string;
    /** Indicates whether the segment is expanded in the UI. */
    expanded: boolean;
    /** A reference to the parent segment in the JSON tree. Undefined for root. */
    parent?: Segment;
    /**
     * A dot/bracket notation path string to this specific segment
     * (e.g., 'settings.notifications.email', 'items[1].value').
     */
    path: string;
}
/**
 * A function that determines whether a given segment's value should be
 * clickable.
 * @param segment The segment to evaluate.
 * @returns `true` if the value is clickable, `false` otherwise.
 */
type IsClickableValueFn = (segment: Segment) => boolean;
/**
 * Represents a handler for value click events, containing both the logic to
 * determine if a value is clickable and the handler function itself.
 *
 * This approach allows for a more modular and self-contained way to define
 * click behaviors. Each handler can specify its own criteria for being active
 * and the action to take, making it easier to manage and extend different
 * click functionalities.
 */
interface ValueClickHandler {
    /**
     * A function that determines whether this handler should be active for a
     * given segment.
     * @param segment The segment to evaluate.
     * @returns `true` if the handler is applicable, `false` otherwise.
     */
    canHandle: IsClickableValueFn;
    /**
     * The function to execute when a clickable value is clicked.
     * @param segment The segment that was clicked.
     * @param event The mouse event that triggered the click.
     */
    handler: (segment: Segment, event?: MouseEvent) => void;
}

/**
 * A handler that checks if a segment's value is a string that looks like an
 * HTTP/HTTPS link. If it is, it opens the link in a new tab.
 */
declare const followLinkHandler: ValueClickHandler;
/**
 * A collection of built-in value click handlers.
 * This array can be used to easily apply all default handlers.
 */
declare const VALUE_CLICK_HANDLERS: readonly ValueClickHandler[];
/**
 * A namespace for individual value click handlers.
 * This allows for easy discovery and individual import of handlers.
 */
declare const ValueClickHandlers: {
    followLinkHandler: ValueClickHandler;
};

/**
 * Renders JSON data in an expandable and collapsible tree structure.
 * Allows users to navigate complex data hierarchies visually.
 */
declare class NgxJsonTreeviewComponent {
    /**
     * The JSON object or array to display in the tree view.
     * @required
     */
    readonly json: _angular_core.InputSignal<any>;
    /**
     * Controls the default expansion state for all expandable segments
     * i.e. objects and arrays.
     * - If `true`, nodes are expanded down to the specified `depth`.
     * - If `false`, all nodes start collapsed.
     * @default true
     */
    readonly expanded: _angular_core.InputSignal<boolean>;
    /**
     * Determines the maximum nesting level automatically expanded when `expanded`
     * is `true`.
     * - `-1`: Infinite depth (all levels expanded).
     * - `0`: Only the root node is expanded (if applicable).
     * - `n`: Root and nodes down to `n` levels are expanded.
     * @default -1
     */
    readonly depth: _angular_core.InputSignal<number>;
    /**
     * If `true`, values are clickable when there is a corresponding handler
     * in the `valueClickHandlers` array that can process it.
     *
     * This allows for use cases such as:
     * - Following hyperlinks.
     * - Copying a value to the clipboard.
     * - Triggering custom actions based on the value's content or type.
     * @default false
     */
    readonly enableClickableValues: _angular_core.InputSignal<boolean>;
    /**
     * A flag to control whether click events on nodes propagate up the DOM tree.
     *
     * By default, click events are stopped from propagating. This is useful when
     * the tree view is embedded within other clickable elements to avoid
     * unintended side effects.
     *
     * Set to `false` to allow events to propagate.
     *
     * @default true
     */
    readonly stopClickPropagation: _angular_core.InputSignal<boolean>;
    /**
     * @deprecated Use `valueClickHandlers` instead. This input will be removed
     * in a future version.
     *
     * A function that determines if a specific value node should be considered
     * clickable. This provides more granular control than the global
     * `enableClickableValues` flag.
     *
     * The function receives the `Segment` object and should return `true` if the
     * value is clickable, `false` otherwise. This check is only performed if
     * `enableClickableValues` is also `true`.
     *
     * @param segment - The segment being evaluated.
     * @returns `true` if the segment's value should be clickable, `false`
     * otherwise.
     */
    readonly isClickableValue: _angular_core.InputSignal<IsClickableValueFn | undefined>;
    /**
     * @deprecated Use `valueClickHandlers` instead. This output will be removed
     * in a future version.
     *
     * If `enableClickableValues` is set to `true`, emits a `Segment` object when
     * a value node is clicked. The emitted `Segment` contains details about the
     * clicked node (key, value, type, path, etc.).
     */
    readonly onValueClick: _angular_core.OutputEmitterRef<Segment>;
    /**
     * An array of handler functions to be executed when a value node is clicked.
     * Only the first handler in the array for which `isClickable` returns `true`
     * will be executed.
     *
     * If `enableClickableValues` is set to true, but `valueClickHandlers` is
     * omitted, the built-in `VALUE_CLICK_HANDLERS` will be used as the default.
     */
    readonly valueClickHandlers: _angular_core.InputSignal<ValueClickHandler[] | undefined>;
    /**
     * *Internal* input representing the parent segment in the tree hierarchy.
     * Primrily used for calculating paths.
     * @internal
     */
    protected readonly _parent: _angular_core.InputSignal<Segment | undefined>;
    /**
     * *Internal* input representing the current nesting depth. Used in
     * conjunction with the `depth` input to control expansion.
     * @internal
     */
    protected readonly _currentDepth: _angular_core.InputSignal<number>;
    private internalValueClickHandlers;
    private readonly rootType;
    protected readonly segments: _angular_core.Signal<Segment[]>;
    private readonly isExpanded;
    protected readonly openingBrace: _angular_core.Signal<string>;
    protected readonly closingBrace: _angular_core.Signal<string>;
    protected readonly asString: _angular_core.Signal<string>;
    protected readonly primitiveSegmentClass: _angular_core.Signal<string>;
    private readonly primitiveSegment;
    protected readonly isClickablePrimitive: _angular_core.Signal<boolean>;
    protected readonly isArrayElement: _angular_core.Signal<boolean>;
    /**
     * Tracks the expansion state of individual segments. Ensures user-toggled
     * states persist even when the underlying data or segments are re-generated.
     */
    private readonly expandedSegments;
    private readonly idGenerator;
    protected readonly id: string;
    constructor();
    protected isExpandable(segment: Segment): boolean;
    protected isEmpty(segment: Segment): boolean;
    protected isClickable(segment: Segment): boolean;
    protected toggle(segment: Segment): void;
    protected onPrimitiveClick(event?: MouseEvent): void;
    protected onValueClickHandler(segment: Segment, event?: MouseEvent): void;
    protected openingBraceForSegment(segment: Segment): "[" | "{" | undefined;
    protected closingBraceForSegment(segment: Segment): "]" | "}" | undefined;
    private getPath;
    private parseKeyValue;
    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxJsonTreeviewComponent, never>;
    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NgxJsonTreeviewComponent, "ngx-json-treeview", never, { "json": { "alias": "json"; "required": true; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; "depth": { "alias": "depth"; "required": false; "isSignal": true; }; "enableClickableValues": { "alias": "enableClickableValues"; "required": false; "isSignal": true; }; "stopClickPropagation": { "alias": "stopClickPropagation"; "required": false; "isSignal": true; }; "isClickableValue": { "alias": "isClickableValue"; "required": false; "isSignal": true; }; "valueClickHandlers": { "alias": "valueClickHandlers"; "required": false; "isSignal": true; }; "_parent": { "alias": "_parent"; "required": false; "isSignal": true; }; "_currentDepth": { "alias": "_currentDepth"; "required": false; "isSignal": true; }; }, { "onValueClick": "onValueClick"; }, never, never, true, never>;
}

interface NgxJsonTreeviewNodeHarnessFilters extends BaseHarnessFilters {
    key?: string | RegExp;
    value?: string | RegExp;
    type?: string | RegExp;
    expanded?: boolean;
}
declare class NgxJsonTreeviewNodeHarness extends ComponentHarness {
    static hostSelector: string;
    /**
     * Gets a `HarnessPredicate` that can be used to search for a
     * `NgxJsonTreeviewNodeHarness` that meets certain criteria.
     * @param options Options for filtering which node instances are considered a
     * match.
     * @return a `HarnessPredicate` configured with the given options.
     */
    static with(options?: NgxJsonTreeviewNodeHarnessFilters): HarnessPredicate<NgxJsonTreeviewNodeHarness>;
    protected toggleButton: () => Promise<_angular_cdk_testing.TestElement>;
    protected keyElement: () => Promise<_angular_cdk_testing.TestElement | null>;
    protected valueElement: () => Promise<_angular_cdk_testing.TestElement | null>;
    /** Gets the key of the node. */
    getKey(): Promise<string>;
    /** Gets the value description of the node. */
    getValue(): Promise<string>;
    /** Gets the type of the node. */
    getType(): Promise<string | null>;
    /** Whether the node is expanded. */
    isExpanded(): Promise<boolean>;
    /** Whether the node is expandable. */
    isExpandable(): Promise<boolean>;
    /** Expands the node if it is collapsed. */
    expand(): Promise<void>;
    /** Collapses the node if it is expanded. */
    collapse(): Promise<void>;
    /** Toggles the node. */
    toggle(): Promise<void>;
    /** Gets the child treeview harness, if expanded. */
    getChildTree(): Promise<NgxJsonTreeviewHarness | null>;
}
declare class NgxJsonTreeviewHarness extends ComponentHarness {
    static hostSelector: string;
    /**
     * Gets a list of nodes in this tree view level.
     * Note: This does not return nested nodes of children.
     */
    getNodes(filter?: NgxJsonTreeviewNodeHarnessFilters): Promise<NgxJsonTreeviewNodeHarness[]>;
    /** Gets a single node that matches the filter. */
    getNode(filter: NgxJsonTreeviewNodeHarnessFilters): Promise<NgxJsonTreeviewNodeHarness>;
}

export { NgxJsonTreeviewComponent, NgxJsonTreeviewHarness, NgxJsonTreeviewNodeHarness, VALUE_CLICK_HANDLERS, ValueClickHandlers, followLinkHandler };
export type { IsClickableValueFn, NgxJsonTreeviewNodeHarnessFilters, Segment, ValueClickHandler };