@kaskad/component-tree 0.0.1

package/lib/parsers/parse-node-selector.d.ts

@@ -0,0 +1,87 @@
+import { NodeSelector } from './node-selector.types';
+export type PathPart = string | number;
+export type PathArray = PathPart[];
+/**
+ * Parse a path string into structured segments.
+ *
+ * ## Path Notation Rules
+ *
+ * **Dot notation (.)** - Access object properties
+ * - `user.profile.name` - Access nested object properties
+ * - `config.0` - Access object property named "0" (string key)
+ *
+ * **Bracket notation ([])** - Access array elements by numeric index
+ * - `items[0].name` - Access first array element, then its 'name' property
+ * - `matrix[0][1]` - Access multi-dimensional arrays
+ *
+ * **Optional chaining (?.)** - Safely access potentially missing properties
+ * - `user?.profile?.email` - Returns null if any segment is missing
+ *
+ * **Variable prefix ($)** - Access variables instead of properties
+ * - `$config.theme` - Access variable 'config', then its 'theme' property
+ * - `$items[0]` - Access variable 'items' array, then first element
+ *
+ * **Component selector (->)** - Access properties on other components
+ * - `&ref->prop.field` - Access 'prop.field' on component with ref
+ * - `:Button[disabled=true]->label` - Access 'label' on Button with condition
+ * - `^parent->config` - Access 'config' on parent component
+ *
+ * **Optional component selector (?->)** - Safely access components that might not exist
+ * - `&ref?->value` - Returns null if component with ref doesn't exist
+ * - `:OptionalType?->property` - Returns null if component type not found
+ * - `^Parent?->config` - Returns null if parent doesn't match
+ *
+ * ## Component Selector Syntax
+ *
+ * Component selectors support modifiers and conditions:
+ * - `&ref` - Select by ref
+ * - `:ComponentType` - Select by component type
+ * - `^parent` - Select parent component
+ * - `[prop=value]` - Filter by property value
+ * - Multiple conditions: `:Button[disabled=true][type=submit]`
+ *
+ * ## Notation Disambiguation
+ *
+ * The choice between dot and bracket notation determines the access type:
+ * ```typescript
+ * 'data.0'      // Object property named "0" (string key)
+ * 'data[0]'     // Array element at index 0 (numeric index)
+ * 'columns.1'   // Object property named "1"
+ * 'columns[1]'  // Array element at index 1
+ * ```
+ *
+ * @example
+ * parseNodeSelector('users[0].name')
+ * // => { kind: 'property', head: 'users', tail: [{ key: 0, optional: false }, { key: 'name', optional: false }] }
+ *
+ * @example
+ * parseNodeSelector('config.0')
+ * // => { kind: 'property', head: 'config', tail: [{ key: '0', optional: false }] }
+ *
+ * @example
+ * parseNodeSelector('prop?.nested?.field')
+ * // => { kind: 'property', head: 'prop', tail: [{ key: 'nested', optional: true }, { key: 'field', optional: true }] }
+ *
+ * @example
+ * parseNodeSelector('$varName.field')
+ * // => { kind: 'variable', head: 'varName', tail: [{ key: 'field', optional: false }] }
+ *
+ * @example
+ * parseNodeSelector('&ref->prop.field')
+ * // => {
+ * //   componentSelector: [{ qualifier: 'ref', modifier: '&', conditions: [] }],
+ * //   kind: 'property',
+ * //   head: 'prop',
+ * //   tail: [{ key: 'field', optional: false }]
+ * // }
+ *
+ * @example
+ * parseNodeSelector(':Button[disabled=true]->label.text')
+ * // => {
+ * //   componentSelector: [{ qualifier: 'Button', modifier: ':', conditions: [['disabled', 'true']] }],
+ * //   kind: 'property',
+ * //   head: 'label',
+ * //   tail: [{ key: 'text', optional: false }]
+ * // }
+ */
+export declare function parseNodeSelector(path: string): NodeSelector;

package/lib/types/command.d.ts

@@ -0,0 +1,3 @@
+export interface CommandRef<_TParams = unknown[], TResult = unknown> {
+    execute(...params: unknown[]): Promise<TResult>;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from './schema';
+export * from './command';
+export * from './node.guards';
+export * from '../computation';

package/lib/types/node.guards.d.ts

@@ -0,0 +1,4 @@
+import { ValueType } from '@kaskad/types';
+import { AbstractNode, ArrayNode, CommandNode } from '../node/node';
+export declare function isArrayNode(node: AbstractNode<ValueType>): node is ArrayNode;
+export declare function isCommandNode(node: AbstractNode<ValueType>): node is CommandNode;

package/lib/types/schema.d.ts

@@ -0,0 +1,13 @@
+import { ComponentId } from '@kaskad/types';
+import { CommandNode } from '../node/node';
+export interface CommandNodeStructure {
+    runnerType: string;
+    owner: ComponentId;
+    target: string;
+    init?: string;
+    finalize?: string;
+}
+export interface NodeChangeHandler {
+    readonly selector: string;
+    readonly command: CommandNode;
+}

package/lib/util/extract-node-value.d.ts

@@ -0,0 +1,3 @@
+import { ComponentId, ValueType } from '@kaskad/types';
+import { AbstractNode } from '../node/node';
+export declare function extractComponentsIds(node: AbstractNode<ValueType>, ids?: ComponentId[]): ComponentId[];

package/lib/util/format-source.d.ts

@@ -0,0 +1 @@
+export declare function formatSource(sourceUrl: string | null | undefined, path?: (string | number)[]): string;

package/lib/util/get-component.d.ts

@@ -0,0 +1,4 @@
+import { ValueType } from '@kaskad/types';
+import { TComponent } from '../mobx/component';
+import { AbstractNode } from '../node/node';
+export declare function getComponent(node: AbstractNode<ValueType>): TComponent;

package/lib/util/id-generator.d.ts

@@ -0,0 +1,5 @@
+export declare const componentIdGenerator: {
+    increment: number;
+    generateId(): string;
+    reset(): void;
+};

package/lib/util/traverse-node.d.ts

@@ -0,0 +1,26 @@
+import { ValueType } from '@kaskad/types';
+import { AbstractNode } from '../node/node';
+import { PathSegment } from '../parsers';
+/**
+ * Traverse a node using parsed path segments, respecting optional chaining.
+ *
+ * @param node - The starting node
+ * @param segments - Array of path segments to traverse
+ * @returns The found node, or null if not found and optional chaining was used
+ * @throws Error if a required segment is not found
+ *
+ * @example
+ * const userNode = component.getNode('user');
+ * const nameNode = traverseNode(userNode, [
+ *   { key: 'profile', optional: false },
+ *   { key: 'name', optional: false }
+ * ]);
+ *
+ * @example
+ * // With optional chaining - returns null instead of throwing
+ * const emailNode = traverseNode(userNode, [
+ *   { key: 'contact', optional: true },
+ *   { key: 'email', optional: false }
+ * ]);
+ */
+export declare function traverseNode(node: AbstractNode<ValueType>, segments: PathSegment[]): AbstractNode<ValueType> | null;

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kaskad/component-tree",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@kaskad/types": "0.0.1",
+    "@kaskad/schema": "0.0.1",
+    "@kaskad/definition": "0.0.1",
+    "@kaskad/config": "0.0.1",
+    "mobx": "^6.13.7"
+  },
+  "sideEffects": false,
+  "module": "esm2022/kaskad-component-tree.js",
+  "typings": "kaskad-component-tree.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./kaskad-component-tree.d.ts",
+      "default": "./esm2022/kaskad-component-tree.js"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}