@aquera/nile-visualization 2.6.0 → 2.7.0

package/dist/src/nile-filter-chart/nile-filter-chart.d.ts

@@ -17,6 +17,99 @@ export interface TreeNode {
     expanded?: boolean;
     children?: TreeNode[];
 }
+export interface QueryLanguageConfig {
+    /** Enables the query layer at all. Default: false. */
+    enabled: boolean;
+    /**
+     * - `'auto'`   → submit emits the raw typed string.
+     * - `'strict'` → submit parses the input with filtrex and emits a
+     *                pure-JSON payload (`{ source }`) plus a sibling
+     *                `evaluate` function on the event detail. On
+     *                parse failure, `nile-prompt-parse-error` fires and
+     *                `nile-prompt-submit` does NOT fire.
+     * Default: `'auto'`.
+     */
+    mode?: 'auto' | 'strict';
+    /** Parser engine. Currently only `'filtrex'` is supported. */
+    engine?: 'filtrex';
+    /** Optional hint text shown beneath the input describing the syntax. */
+    syntaxHint?: string;
+    /**
+     * Extra functions registered with filtrex on top of the built-in set.
+     * Each function receives the resolved argument values from the
+     * expression and returns a value usable in further comparisons.
+     *
+     * Example: `{ daysAgo: (d) => (Date.now() - +new Date(d)) / 86400000 }`
+     * Used in expressions like `daysAgo(lastSeen) < 7`.
+     */
+    extraFunctions?: Record<string, (...args: any[]) => unknown>;
+    /**
+     * Optional value-getter for accessing row properties. Filtrex calls
+     * this for every identifier reference. Default: dotted property
+     * access (`row.foo.bar` works out of the box).
+     *
+     * Override when your data model uses a Map / class / proxy that
+     * standard property access can't read.
+     */
+    customProp?: (name: string, get: (key: string) => unknown, obj: unknown) => unknown;
+}
+/**
+ * Recursive ESTree-shaped node returned by the AST parser. The shape
+ * matches what `jsep` produces — a small, well-known JS-expression AST.
+ * Pure JSON: every field is a string, number, boolean, null, or another
+ * `QueryNode`, so `JSON.stringify` round-trips cleanly.
+ */
+export type QueryNode = {
+    type: 'Identifier';
+    name: string;
+} | {
+    type: 'Literal';
+    value: string | number | boolean | null;
+    raw?: string;
+} | {
+    type: 'BinaryExpression';
+    operator: string;
+    left: QueryNode;
+    right: QueryNode;
+} | {
+    type: 'LogicalExpression';
+    operator: string;
+    left: QueryNode;
+    right: QueryNode;
+} | {
+    type: 'UnaryExpression';
+    operator: string;
+    argument: QueryNode;
+    prefix: boolean;
+} | {
+    type: 'CallExpression';
+    callee: QueryNode;
+    arguments: QueryNode[];
+} | {
+    type: 'MemberExpression';
+    computed: boolean;
+    object: QueryNode;
+    property: QueryNode;
+} | {
+    type: 'ArrayExpression';
+    elements: QueryNode[];
+} | {
+    type: 'Compound';
+    body: QueryNode[];
+};
+export type QueryJson = {
+    /** The exact string the user typed, retained for display / serialization. */
+    source: string;
+    ast: QueryNode;
+};
+export type QuerySubmitDetail = {
+    id: string;
+    /** JSON-serializable payload — string in auto mode, `QueryJson` in strict. */
+    value: string | QueryJson;
+    /** Compiled filtrex predicate. Only present in strict mode on success.
+     *  Use as `data.filter(e.detail.evaluate)`. */
+    evaluate?: (row: unknown) => unknown;
+};
 export interface FilterControl {
     id: string;
     label: string;
@@ -50,28 +143,26 @@ export interface FilterControl {
      * Prompt variant only. Inline callback invoked when the user presses
      * Enter inside the prompt input. Called in addition to the
      * `nile-prompt-submit` event.
-     */
-    onSubmit?: (value: string, id: string) => void;
-    /**
-     * Prompt variant only. Colors used for the animated border gradient.
-     * Pass any number of CSS color strings (hex / rgb / hsl / named); they
-     * are evenly distributed across the gradient by default. To control
-     * stops explicitly, include positions in the strings themselves
-     * (e.g. `'#2563eb 0%'`, `'#06b6d4 50%'`).
      *
-     * Example: `['#ec4899', '#f97316', '#facc15', '#ec4899']`
-     * Default: an indigo → cyan → violet → indigo blue palette.
+     *   - auto mode (default)  → `value` is the raw `string` the user typed.
+     *   - strict mode (success) → `value` is a `QueryJson` (pure-JSON
+     *                              `{ source }`); the compiled predicate is
+     *                              passed as the third argument so callers
+     *                              that want to filter inline can. JSON
+     *                              consumers can ignore that argument.
+     *   - strict mode (parse fail) → routes through `onParseError` instead;
+     *                              `onSubmit` is NOT called.
      */
-    gradientColors?: string[];
+    onSubmit?: (value: string | QueryJson, id: string, evaluate?: (row: unknown) => unknown) => void;
     /**
-     * Prompt variant only. Linear-gradient direction (e.g. `'90deg'`,
-     * `'to right'`, `'45deg'`). Default: `'90deg'`.
+     * Prompt variant only. Inline callback invoked when `queryLanguage.mode`
+     * is `'strict'` and the user-typed expression FAILS to parse on submit.
+     * Mirrors the `nile-prompt-parse-error` event.
      */
+    onParseError?: (input: string, error: Error, id: string) => void;
+    queryLanguage?: QueryLanguageConfig;
+    gradientColors?: string[];
     gradientDirection?: string;
-    /**
-     * Prompt variant only. Animation duration in milliseconds for one full
-     * gradient sweep. Default: 4500.
-     */
     gradientSpeedMs?: number;
     valueB?: string;
     operator?: string;
@@ -124,6 +215,12 @@ export declare class NileFilterChart extends NileElement {
     private _renderComparison;
     private _renderThreshold;
     private _renderPreset;
+    private static readonly _builtInFiltrexFns;
+    private static _filtrexLoading;
+    private static _getCompileExpression;
+    private static _jsepLoading;
+    private static _getJsep;
+    private _handleSubmit;
     private _renderPrompt;
     private _renderControl;
     private _renderGroup;

package/dist/src/nile-filter-chart/nile-filter-chart.js

@@ -1,9 +1,10 @@
+var NileFilterChart_1;
 import { __decorate } from "tslib";
 import { html, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { styles } from './nile-filter-chart.css.js';
 import NileElement from '../internal/nile-element.js';
-let NileFilterChart = class NileFilterChart extends NileElement {
+let NileFilterChart = NileFilterChart_1 = class NileFilterChart extends NileElement {
     constructor() {
         super(...arguments);
         this.config = null;
@@ -425,21 +426,80 @@ let NileFilterChart = class NileFilterChart extends NileElement {
           </button>`)}
       </div>`;
     }
-    // ── Prompt ───────────────────────────────────────────────────────────────────
-    //
-    // Renders a free-text input wrapped in a div whose border is an animated
-    // multi-stop blue gradient (CSS @keyframes — purely visual, no JS in the
-    // animation loop). The placeholder is driven by a typewriter that cycles
-    // through `ctrl.placeholders`. Each keystroke fires `nile-change` with the
-    // current string; pressing Enter additionally fires `nile-prompt-submit`
-    // for AI-style "ask" UIs.
+    static async _getCompileExpression() {
+        if (!NileFilterChart_1._filtrexLoading) {
+            NileFilterChart_1._filtrexLoading = import('filtrex').then(m => {
+                const fn = m.compileExpression
+                    ?? m.default?.compileExpression;
+                if (typeof fn !== 'function') {
+                    throw new Error('filtrex: compileExpression export not found');
+                }
+                return fn;
+            });
+        }
+        return NileFilterChart_1._filtrexLoading;
+    }
+    static async _getJsep() {
+        if (!NileFilterChart_1._jsepLoading) {
+            NileFilterChart_1._jsepLoading = import('jsep').then(m => {
+                const candidate = m.default ?? m;
+                if (typeof candidate !== 'function') {
+                    throw new Error('jsep: function export not found');
+                }
+                const fn = candidate;
+                try {
+                    fn.addBinaryOp?.('and', 2);
+                    fn.addBinaryOp?.('or', 1);
+                    fn.addBinaryOp?.('in', 6);
+                    fn.addUnaryOp?.('not');
+                }
+                catch {
+                }
+                return fn;
+            });
+        }
+        return NileFilterChart_1._jsepLoading;
+    }
+    async _handleSubmit(value, ctrl) {
+        const ql = ctrl.queryLanguage;
+        if (!ql?.enabled || (ql.mode ?? 'auto') === 'auto') {
+            this.emit('nile-prompt-submit', { id: ctrl.id, value });
+            if (typeof ctrl.onSubmit === 'function')
+                ctrl.onSubmit(value, ctrl.id);
+            return;
+        }
+        try {
+            const jsep = await NileFilterChart_1._getJsep();
+            const ast = jsep(value);
+            const compileExpression = await NileFilterChart_1._getCompileExpression();
+            const extraFunctions = {
+                ...NileFilterChart_1._builtInFiltrexFns,
+                ...(ql.extraFunctions ?? {}),
+            };
+            const evaluate = compileExpression(value, {
+                extraFunctions,
+                ...(ql.customProp ? { customProp: ql.customProp } : {}),
+            });
+            const json = { source: value, ast };
+            this.emit('nile-prompt-submit', { id: ctrl.id, value: json, evaluate });
+            if (typeof ctrl.onSubmit === 'function')
+                ctrl.onSubmit(json, ctrl.id, evaluate);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.emit('nile-prompt-parse-error', {
+                id: ctrl.id,
+                input: value,
+                error: { message: error.message },
+            });
+            if (typeof ctrl.onParseError === 'function') {
+                ctrl.onParseError(value, error, ctrl.id);
+            }
+        }
+    }
     _renderPrompt(ctrl) {
         const value = String(this.selectedValues.get(ctrl.id) ?? '');
         const animated = this._promptPlaceholder.get(ctrl.id) ?? '';
-        // Build the inline style overrides as CSS custom properties — these
-        // are picked up by the .fc-prompt rule via var(--fc-prompt-gradient,
-        // <default>) / var(--fc-prompt-gradient-speed, 4.5s). Only emit a
-        // declaration when the consumer actually supplied an override.
         const styleParts = [];
         if (ctrl.gradientColors && ctrl.gradientColors.length > 0) {
             const dir = ctrl.gradientDirection ?? '90deg';
@@ -484,10 +544,7 @@ let NileFilterChart = class NileFilterChart extends NileElement {
             @keydown="${(e) => {
             if (e.key === 'Enter') {
                 const t = e.target;
-                this.emit('nile-prompt-submit', { id: ctrl.id, value: t.value });
-                if (typeof ctrl.onSubmit === 'function') {
-                    ctrl.onSubmit(t.value, ctrl.id);
-                }
+                this._handleSubmit(t.value, ctrl);
             }
         }}"
           />
@@ -577,6 +634,25 @@ let NileFilterChart = class NileFilterChart extends NileElement {
       </div>`;
     }
 };
+NileFilterChart._builtInFiltrexFns = {
+    contains: (s, sub) => String(s ?? '').includes(String(sub ?? '')),
+    startsWith: (s, p) => String(s ?? '').startsWith(String(p ?? '')),
+    endsWith: (s, p) => String(s ?? '').endsWith(String(p ?? '')),
+    lower: (s) => String(s ?? '').toLowerCase(),
+    upper: (s) => String(s ?? '').toUpperCase(),
+    len: (s) => (s == null ? 0 : Array.isArray(s) ? s.length : String(s).length),
+    isEmpty: (s) => s == null || s === '' || (Array.isArray(s) && s.length === 0),
+    isNotEmpty: (s) => !(s == null || s === '' || (Array.isArray(s) && s.length === 0)),
+    between: (n, lo, hi) => Number(n) >= Number(lo) && Number(n) <= Number(hi),
+    year: (d) => new Date(d).getFullYear(),
+    month: (d) => new Date(d).getMonth() + 1,
+    day: (d) => new Date(d).getDate(),
+    daysAgo: (d) => (Date.now() - +new Date(d)) / 86400000,
+    matches: (s, re) => new RegExp(String(re ?? '')).test(String(s ?? '')),
+    coalesce: (...xs) => xs.find(x => x != null && x !== '') ?? null,
+};
+NileFilterChart._filtrexLoading = null;
+NileFilterChart._jsepLoading = null;
 __decorate([
     property({ attribute: false })
 ], NileFilterChart.prototype, "config", void 0);
@@ -589,7 +665,7 @@ __decorate([
 __decorate([
     state()
 ], NileFilterChart.prototype, "_promptPlaceholder", void 0);
-NileFilterChart = __decorate([
+NileFilterChart = NileFilterChart_1 = __decorate([
     customElement('nile-filter-chart')
 ], NileFilterChart);
 export { NileFilterChart };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aquera/nile-visualization",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "A visualization Library for the Nile Design System",
   "license": "MIT",
   "author": "Aquera Inc",
@@ -57,7 +57,9 @@
     "clean": "rimraf dist/*"
   },
   "dependencies": {
-    "lit": "^3.0.0"
+    "lit": "^3.0.0",
+    "filtrex": "^3.0.0",
+    "jsep": "^1.3.9"
   },
   "peerDependencies": {
     "highcharts": ">=10.0.0",