@aceshooting/lyra-ui 4.0.0 → 4.1.0

package/dist/components/graph-query-builder/graph-query-builder.class.d.ts

@@ -0,0 +1,242 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import { LyraElement } from '../../internal/lyra-element.js';
+import '../select/select.class.js';
+import '../combobox/option.class.js';
+import '../input/input.class.js';
+import '../chip/chip.class.js';
+import '../chip/chip-group.class.js';
+/** Traversal direction relative to the matched node(s): `'out'` (outgoing edges), `'in'`
+ *  (incoming edges), or `'both'`. */
+export type GraphQueryDirection = 'out' | 'in' | 'both';
+/** One pickable relationship or node type, as offered to this component's type pickers via
+ *  `relationshipTypeOptions`/`nodeTypeOptions`. */
+export interface GraphQueryTypeOption {
+    value: string;
+    /** Display label. Falls back to `value` when omitted. */
+    label?: string;
+}
+/**
+ * The serializable query model this component builds and edits -- a single typed relationship/
+ * path filter over a knowledge graph, suitable for handing directly to a GraphRAG retrieval or
+ * traversal backend. `startId`/`endId` anchor the path (`endId` left empty means "any reachable
+ * node" rather than a specific target); `relationshipTypes`/`nodeTypes` constrain which edges/
+ * nodes the traversal may pass through (empty arrays mean "any type"); `direction` constrains
+ * edge traversal direction; `minHops`/`maxHops` bound the path length, mirroring a graph query
+ * language's variable-length path syntax (e.g. Cypher's `-[:REL*1..3]->`).
+ *
+ * This is deliberately a **flat** shape, not a nested boolean filter tree: a GraphRAG relationship
+ * -path query composes by union ("traverse `worksFor` OR `foundedBy`, through `Person` or
+ * `Organization` nodes, 1 to 3 hops out from this entity") rather than by nested AND/OR groups --
+ * every array field here is implicitly OR'd, and there is exactly one path per query. A branching
+ * multi-path/subgraph-pattern query is a different, considerably heavier feature and out of scope.
+ */
+export interface GraphQuery {
+    /** The anchor entity id the traversal starts from. Required for the query to be valid/runnable
+     *  -- see `checkValidity()`. */
+    startId: string;
+    /** An optional specific target entity id ("find a path to this node"). Empty means any
+     *  reachable node satisfying the other filters. */
+    endId: string;
+    /** Relationship (edge) type values to traverse. Empty means any relationship type. */
+    relationshipTypes: string[];
+    /** Node type values the traversal may pass through. Empty means any node type. */
+    nodeTypes: string[];
+    direction: GraphQueryDirection;
+    /** Minimum path length, inclusive. */
+    minHops: number;
+    /** Maximum path length, inclusive. Must be `>= minHops` -- see `checkValidity()`. */
+    maxHops: number;
+}
+/** One named, host-persisted query. `id` is assigned by the host (e.g. on `lr-query-save`) --
+ *  this component never generates ids itself, the same controlled-list convention every other
+ *  Lyra component with a host-owned collection follows. */
+export interface GraphQuerySavedItem {
+    id: string;
+    name: string;
+    query: GraphQuery;
+}
+export interface LyraGraphQueryBuilderEventMap {
+    'lr-input': CustomEvent<{
+        value: GraphQuery;
+    }>;
+    'lr-validity-change': CustomEvent<{
+        valid: boolean;
+        errors: Record<string, string>;
+    }>;
+    'lr-query-run': CustomEvent<{
+        query: GraphQuery;
+    }>;
+    'lr-query-save': CustomEvent<{
+        name: string;
+        query: GraphQuery;
+    }>;
+    'lr-query-load': CustomEvent<{
+        id: string;
+        query: GraphQuery;
+    }>;
+    'lr-query-delete': CustomEvent<{
+        id: string;
+    }>;
+}
+/**
+ * `<lr-graph-query-builder>` — an editor for a single typed relationship/path filter
+ * (`GraphQuery`) over a knowledge graph: start/end entity anchors, relationship-type and
+ * node-type pickers with a removable active-filter chip display, a traversal direction, a
+ * min/max hop range, validation, and a host-persisted saved-query list -- a serializable query
+ * model for GraphRAG workflows (feed the `value`/`lr-query-run` payload straight to a retrieval
+ * or traversal backend).
+ *
+ * Composes `<lr-select>` for every closed-choice picker (relationship type, node type,
+ * direction, hop counts) and `<lr-input>` for the free-text entity ids -- the relationship/
+ * node-type pickers are "add" selects: choosing an option appends it to the corresponding
+ * array and the picker itself resets to its placeholder, so the *current* selection is shown
+ * separately as a row of removable `<lr-chip>`s inside an `<lr-chip-group>` (click a chip's
+ * remove button to drop that one type). A type value present in `value` but missing from
+ * `relationshipTypeOptions`/`nodeTypeOptions` (e.g. a saved query referencing a type that was
+ * since renamed/removed from the picker's own option list) still renders as a chip, labeled with
+ * its raw value, rather than being silently dropped.
+ *
+ * **Query model placement:** `GraphQuery` is kept local to this component rather than promoted
+ * to the shared `src/ai/types.ts` surface. Unlike that module's types (`ChatMessage`,
+ * `Citation`, `RetrievalQuery`, etc.), which each mirror a shape multiple existing primitives
+ * already consume, `GraphQuery` is specific to this component's own editable-filter-set shape
+ * (its `minHops`/`maxHops` selects, its "add picker + chip list" editing idiom) -- no other
+ * component reads or produces this exact shape today. This mirrors `<lr-rubric-form>`'s
+ * `RubricValue`/`RubricKey` and `<lr-tool-param-form>`'s `ToolParamFormSchema`, both also kept
+ * local to their own component for the identical reason.
+ *
+ * **Form association:** every other "structured, non-string value" editor in this package that
+ * looks like this one -- `<lr-rubric-form>`, `<lr-tool-param-form>`, `<lr-time-range>` -- attaches
+ * `ElementInternals` directly (the `FormAssociated` mixin only fits a plain string value) and
+ * treats native `<form>` participation as a nice-to-have layered on top of its primary
+ * `value`/`lr-input`/`lr-validity-change` integration contract, not a requirement. This component
+ * follows that same established convention: `value` round-trips through `JSON.stringify()` as the
+ * submitted form value, and a consumer that never places this inside a `<form>` loses nothing.
+ *
+ * @customElement lr-graph-query-builder
+ * @slot actions - Extra host controls rendered in the footer beside the Run button.
+ * @event lr-input - `detail: { value }` — any field changed; the full current query.
+ * @event lr-validity-change - `detail: { valid, errors }` — fired only on an actual change.
+ * @event lr-query-run - The Run button was activated and `reportValidity()` passed. `detail: { query }`.
+ * @event lr-query-save - The Save button was activated with a non-empty name. `detail: { name, query }`
+ * — the host is responsible for assigning an id and appending the entry to `savedQueries`.
+ * @event lr-query-load - A saved query's Load button was activated (`value` has already been
+ * replaced with it by the time this fires). `detail: { id, query }`.
+ * @event lr-query-delete - A saved query's delete button was activated. `detail: { id }` — the
+ * host is responsible for removing the matching entry from `savedQueries`.
+ * @csspart base - The outer wrapper around every section.
+ * @csspart path-fields - The row wrapping the start/end entity inputs and hop-count selects.
+ * @csspart start-input - The start-entity `<lr-input>`.
+ * @csspart end-input - The end-entity `<lr-input>`.
+ * @csspart min-hops - The minimum-hops `<lr-select>`.
+ * @csspart max-hops - The maximum-hops `<lr-select>`.
+ * @csspart filter-group - One type-filter section (relationship or node type); rendered twice.
+ * @csspart relationship-picker - The "add a relationship type" `<lr-select>`.
+ * @csspart relationship-chips - The `<lr-chip-group>` listing currently active relationship types.
+ * @csspart node-type-picker - The "add a node type" `<lr-select>`.
+ * @csspart node-type-chips - The `<lr-chip-group>` listing currently active node types.
+ * @csspart direction - The traversal-direction `<lr-select>`.
+ * @csspart footer - The row containing the actions slot and the Run button.
+ * @csspart run-button - The Run button.
+ * @csspart saved-queries - The wrapper around the save row and the saved-query list.
+ * @csspart saved-queries-label - The saved-queries section heading.
+ * @csspart save-row - The row containing the save-name input and Save button.
+ * @csspart save-name-input - The new-saved-query name `<lr-input>`.
+ * @csspart save-button - The Save button.
+ * @csspart saved-empty - The message shown when `savedQueries` has no entries.
+ * @csspart saved-list - The list of saved queries.
+ * @csspart saved-item - One saved query's row.
+ * @csspart saved-load-button - A saved query row's Load button.
+ * @csspart saved-delete-button - A saved query row's delete button.
+ */
+export declare class LyraGraphQueryBuilder extends LyraElement<LyraGraphQueryBuilderEventMap> {
+    static formAssociated: boolean;
+    static styles: import("lit").CSSResultGroup[];
+    static properties: {
+        name: {
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+        value: {
+            attribute: boolean;
+            noAccessor: boolean;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+            noAccessor: boolean;
+        };
+    };
+    /** Pickable relationship types offered by the relationship-type "add" picker. */
+    relationshipTypeOptions: GraphQueryTypeOption[];
+    /** Pickable node types offered by the node-type "add" picker. */
+    nodeTypeOptions: GraphQueryTypeOption[];
+    /** Host-persisted saved queries. Controlled -- this component never mutates this array itself,
+     *  it only emits `lr-query-save`/`lr-query-delete` requests for the host to act on. */
+    savedQueries: GraphQuerySavedItem[];
+    /** Upper bound (inclusive) offered by the minimum/maximum hop selects. Sanitized to a finite
+     *  integer in `[1, 20]`, falling back to `6`. */
+    hopLimit: number;
+    /** Accessible name for the whole component; falls back to the localized `graphQueryBuilderLabel`. */
+    label: string;
+    private _errors;
+    private touchedFields;
+    private saveName;
+    private internals;
+    private validityController;
+    private _fieldsetDisabled;
+    private _name;
+    private _value;
+    private _disabled;
+    private _validityFlags;
+    private lastValidityKey;
+    constructor();
+    get form(): HTMLFormElement | null;
+    get labels(): NodeList;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    get value(): GraphQuery;
+    set value(next: GraphQuery);
+    get name(): string;
+    set name(next: string);
+    get disabled(): boolean;
+    set disabled(next: boolean);
+    /** Effective disabled state: this element's own `disabled` OR an ancestor
+     *  `<fieldset disabled>`'s inherited state. */
+    get effectiveDisabled(): boolean;
+    /** The current validation errors, keyed by the csspart name of the field they apply to
+     *  (`'start-input'` | `'max-hops'`). Mirrors the last `lr-validity-change` event's `errors`. */
+    get errors(): Record<string, string>;
+    private computeValidation;
+    private syncFormState;
+    /** Resynchronizes validity without revealing inline errors. */
+    checkValidity(): boolean;
+    /** Reveals every current field error and returns overall validity -- the hook Run calls before
+     *  acting, mirroring a native `<form>`'s `reportValidity()`. */
+    reportValidity(): boolean;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null, _mode?: 'restore' | 'autocomplete'): void;
+    formDisabledCallback(disabled: boolean): void;
+    private setValue;
+    private addRelationshipType;
+    private removeRelationshipType;
+    private addNodeType;
+    private removeNodeType;
+    private markTouched;
+    private runQuery;
+    private saveQuery;
+    private loadQuery;
+    private deleteQuery;
+    protected updated(changed: PropertyValues): void;
+    private hopOptions;
+    private labelForType;
+    private renderTypeFilter;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-graph-query-builder': LyraGraphQueryBuilder;
+    }
+}
+//# sourceMappingURL=graph-query-builder.class.d.ts.map

package/dist/components/graph-query-builder/graph-query-builder.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-query-builder.class.d.ts","sourceRoot":"","sources":["../../../src/components/graph-query-builder/graph-query-builder.class.ts"],"names":[],"mappings":"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"}