@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/util/jexlFilterRows.d.ts

@@ -0,0 +1,89 @@
+import type { AstNode, Subject } from '@jbrowse/jexl';
+export type JexlFilterFieldType = 'number' | 'text' | 'flag';
+export type JexlFilterField = {
+    label: string;
+    /** unset for a field whose values may be numbers or text */
+    type?: JexlFilterFieldType;
+    group?: string;
+    description?: string;
+    /** holds several values per feature, so a comparison asks whether any does */
+    multi?: boolean;
+    values?: string[];
+} & ({
+    path: string[];
+} | {
+    call: string;
+});
+export interface FieldChoice {
+    key: string;
+    label: string;
+    type?: JexlFilterFieldType;
+    subject: Subject;
+    group?: string;
+    description?: string;
+    multi?: boolean;
+    values?: string[];
+}
+export type RowOp = '>' | '>=' | '<' | '<=' | '==' | '!=' | 'in' | '~' | 'set' | '!set';
+export declare const OPERATORS: Record<JexlFilterFieldType | 'any', {
+    op: RowOp;
+    label: string;
+}[]>;
+export interface ConditionRow {
+    kind: 'condition';
+    id: number;
+    line?: number;
+    field?: FieldChoice;
+    op: RowOp;
+    value: string | string[];
+}
+export interface TextRow {
+    kind: 'text';
+    id: number;
+    line?: number;
+    text: string;
+}
+export type FilterRow = ConditionRow | TextRow;
+/**
+ * Rows keep the index of the stored line they came from until one of that
+ * line's rows changes, so an untouched line is written back byte-identical.
+ */
+export interface FilterRows {
+    lines: readonly string[];
+    rows: FilterRow[];
+}
+interface Parser {
+    parse: (text: string) => AstNode | null;
+}
+export declare function resolveFields(fields: readonly JexlFilterField[]): {
+    key: string;
+    label: string;
+    type: JexlFilterFieldType | undefined;
+    group: string | undefined;
+    description: string | undefined;
+    multi: boolean | undefined;
+    values: string[] | undefined;
+    subject: Subject;
+}[];
+/**
+ * The columns an adapter's metadata describes as `{column: description}`, as
+ * a BigBed's autoSql does, less those `fields` already lists. Any other
+ * metadata describes none.
+ */
+export declare function describedColumns(metadata: unknown, fields: readonly JexlFilterField[]): JexlFilterField[];
+/** A field typed into the picker rather than chosen, read as a dotted path. */
+export declare function typedField(text: string): FieldChoice;
+export declare function stripJexlPrefix(line: string): string;
+export declare function readFilterRows(lines: readonly string[], parser: Parser, choices: readonly FieldChoice[]): FilterRows;
+export declare function addRow(state: FilterRows): FilterRows;
+export declare function replaceRow(state: FilterRows, row: FilterRow): FilterRows;
+export declare function removeRow(state: FilterRows, id: number): FilterRows;
+export declare function withField(row: ConditionRow, field: FieldChoice): ConditionRow;
+export declare function withOp(row: ConditionRow, op: RowOp): ConditionRow;
+/**
+ * The stored filters: an untouched line as it was, and every row of an edited
+ * line as a line of its own, which is equivalent because lines AND together.
+ * Rows left incomplete are dropped.
+ */
+export declare function writeFilterRows({ lines, rows }: FilterRows): string[];
+export {};

package/esm/util/jexlFilterRows.js

@@ -0,0 +1,252 @@
+import { callSubject, conditions, pathSubject, print, printCondition, } from '@jbrowse/jexl';
+import { JEXL_PREFIX, ensureJexlPrefix, isJexl } from './jexlStrings.js';
+export const OPERATORS = {
+    number: [
+        { op: '>', label: '>' },
+        { op: '>=', label: '≥' },
+        { op: '<', label: '<' },
+        { op: '<=', label: '≤' },
+        { op: '==', label: '=' },
+        { op: '!=', label: '≠' },
+    ],
+    text: [
+        { op: '==', label: 'is' },
+        { op: '!=', label: 'is not' },
+        { op: 'in', label: 'is one of' },
+        { op: '~', label: 'matches' },
+    ],
+    flag: [
+        { op: 'set', label: 'is set' },
+        { op: '!set', label: 'is not set' },
+    ],
+    any: [
+        { op: '==', label: 'is' },
+        { op: '!=', label: 'is not' },
+        { op: '>', label: '>' },
+        { op: '>=', label: '≥' },
+        { op: '<', label: '<' },
+        { op: '<=', label: '≤' },
+        { op: 'in', label: 'is one of' },
+        { op: '~', label: 'matches' },
+    ],
+};
+const ROW = 'feature';
+function subjectKey(subject) {
+    return JSON.stringify(subject.kind === 'path'
+        ? ['path', ...subject.path]
+        : ['call', subject.name, ...subject.args]);
+}
+export function resolveFields(fields) {
+    return fields.map(({ label, type, group, description, multi, values, ...source }) => {
+        const subject = 'call' in source
+            ? callSubject(ROW, source.call)
+            : pathSubject(ROW, source.path);
+        return {
+            key: subjectKey(subject),
+            label,
+            type,
+            group,
+            description,
+            multi,
+            values,
+            subject,
+        };
+    });
+}
+// a feature carries these as refName, start and end
+const BED_LOCUS_COLUMNS = new Set(['chrom', 'chromStart', 'chromEnd']);
+/**
+ * The columns an adapter's metadata describes as `{column: description}`, as
+ * a BigBed's autoSql does, less those `fields` already lists. Any other
+ * metadata describes none.
+ */
+export function describedColumns(metadata, fields) {
+    const entries = metadata && typeof metadata === 'object' ? Object.entries(metadata) : [];
+    const listed = new Set(fields.map(field => field.label));
+    return entries.every((entry) => typeof entry[1] === 'string')
+        ? entries
+            .filter(([name]) => !listed.has(name) && !BED_LOCUS_COLUMNS.has(name))
+            .map(([name, description]) => ({
+            label: name,
+            path: [name],
+            description: description || undefined,
+        }))
+        : [];
+}
+/** A field typed into the picker rather than chosen, read as a dotted path. */
+export function typedField(text) {
+    const subject = pathSubject(ROW, text.split('.'));
+    return { key: subjectKey(subject), label: text, subject };
+}
+export function stripJexlPrefix(line) {
+    return isJexl(line) ? line.slice(JEXL_PREFIX.length) : line;
+}
+/** A field of no known type writes a value that reads as a number as one. */
+function scalar(type, text) {
+    const number = Number(text);
+    return type === 'number' ||
+        (!type && text.trim() !== '' && Number.isFinite(number))
+        ? number
+        : text;
+}
+function subjectLabel(subject) {
+    return subject.kind === 'path'
+        ? subject.path
+            .map((key, i) => typeof key === 'number' ? `[${key}]` : i === 0 ? key : `.${key}`)
+            .join('')
+        : print(subject.node);
+}
+function conditionRow(c, choices, id, line) {
+    const value = 'value' in c ? c.value : undefined;
+    const key = subjectKey(c.subject);
+    const field = choices.find(f => f.key === key) ?? {
+        key,
+        label: subjectLabel(c.subject),
+        type: value === undefined ? 'flag' : undefined,
+        subject: c.subject,
+    };
+    const op = c.op;
+    const values = value === undefined ? [] : [value].flat();
+    const writesBack = (v) => op === '~' ? typeof v === 'string' : scalar(field.type, String(v)) === v;
+    return OPERATORS[field.type ?? 'any'].some(o => o.op === op) &&
+        values.every(writesBack)
+        ? {
+            kind: 'condition',
+            id,
+            line,
+            field,
+            op,
+            value: Array.isArray(value) ? value.map(String) : String(value ?? ''),
+        }
+        : undefined;
+}
+function parseConditions(text, parser, calls) {
+    try {
+        return conditions(parser.parse(text), {
+            row: ROW,
+            accessors: { get: [] },
+            calls,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readFilterRows(lines, parser, choices) {
+    const calls = choices.flatMap(f => f.subject.kind === 'call' ? [f.subject.name] : []);
+    const rows = [];
+    for (const [line, stored] of lines.entries()) {
+        const text = stripJexlPrefix(stored);
+        const id = rows.length;
+        const read = parseConditions(text, parser, calls)?.map((c, i) => conditionRow(c, choices, id + i, line));
+        rows.push(...(read?.every(row => row !== undefined)
+            ? read
+            : [{ kind: 'text', id, line, text: text.trim() }]));
+    }
+    return { lines, rows };
+}
+function nextId(rows) {
+    return rows.reduce((max, row) => Math.max(max, row.id + 1), 0);
+}
+function emptyRow(id) {
+    return { kind: 'condition', id, op: '==', value: '' };
+}
+export function addRow(state) {
+    return { ...state, rows: [...state.rows, emptyRow(nextId(state.rows))] };
+}
+function detach(rows, id) {
+    const line = rows.find(row => row.id === id)?.line;
+    return line === undefined
+        ? rows
+        : rows.map(row => (row.line === line ? { ...row, line: undefined } : row));
+}
+export function replaceRow(state, row) {
+    return {
+        ...state,
+        rows: detach(state.rows, row.id).map(r => r.id === row.id ? { ...row, line: undefined } : r),
+    };
+}
+export function removeRow(state, id) {
+    return {
+        ...state,
+        rows: detach(state.rows, id).filter(row => row.id !== id),
+    };
+}
+export function withField(row, field) {
+    const sameType = row.field?.type === field.type;
+    const ops = OPERATORS[field.type ?? 'any'];
+    return {
+        ...row,
+        field,
+        op: sameType ? row.op : ops[0].op,
+        value: sameType ? row.value : '',
+    };
+}
+export function withOp(row, op) {
+    const { value } = row;
+    return {
+        ...row,
+        op,
+        value: op === 'in'
+            ? Array.isArray(value)
+                ? value
+                : value
+                    ? [value]
+                    : []
+            : Array.isArray(value)
+                ? (value[0] ?? '')
+                : value,
+    };
+}
+function writeCondition({ field, op, value }) {
+    if (!field) {
+        return undefined;
+    }
+    const { subject, type } = field;
+    const usable = (v) => v.trim() !== '' && (type !== 'number' || Number.isFinite(Number(v)));
+    if (op === 'set' || op === '!set') {
+        return printCondition({ subject, op });
+    }
+    if (op === 'in') {
+        const list = [value].flat().filter(usable);
+        return list.length > 0
+            ? printCondition({
+                subject,
+                op,
+                value: list.map(v => scalar(type, v)),
+            })
+            : undefined;
+    }
+    const text = [value].flat()[0] ?? '';
+    return !usable(text)
+        ? undefined
+        : op === '~'
+            ? printCondition({ subject, op, value: text })
+            : printCondition({ subject, op, value: scalar(type, text) });
+}
+function writeRow(row) {
+    const text = row.kind === 'text' ? row.text.trim() || undefined : writeCondition(row);
+    return text === undefined ? undefined : ensureJexlPrefix(text);
+}
+/**
+ * The stored filters: an untouched line as it was, and every row of an edited
+ * line as a line of its own, which is equivalent because lines AND together.
+ * Rows left incomplete are dropped.
+ */
+export function writeFilterRows({ lines, rows }) {
+    const out = [];
+    let previous;
+    for (const row of rows) {
+        if (row.line === undefined) {
+            const text = writeRow(row);
+            if (text !== undefined) {
+                out.push(text);
+            }
+        }
+        else if (row.line !== previous) {
+            out.push(lines[row.line]);
+        }
+        previous = row.line;
+    }
+    return out;
+}

package/esm/util/jexlFilters.d.ts

@@ -1,75 +1,50 @@
 import { getConf } from '../configuration/getConf.ts';
+import type { RetiredDisplayState } from '../pluggableElementTypes/DisplayType.ts';
 import type { Reversible } from '../ui/filterMenuItems.ts';
 /**
- * The two-tier feature-filter contract, shared by every display offering a
- * "Filter by..." row. Two tiers because the setting has two authors:
- *
- * - the **`jexlFilters` config slot** on `baseLinearDisplayConfigSchema`, which
- *   an admin declares in a track config. It stores expressions **unprefixed**,
- *   because config-slot values are deferred-evaluation and a stored `jexl:` is
- *   what marks a slot as a callback — so the prefix goes on at read time, in
- *   `configuredJexlFilters`.
- * - the **`jexlFiltersSetting` display property**, which the dialog writes and
- *   which stores them already prefixed (the runtime convention). Set — *even to
- *   an empty list* — it replaces the config tier entirely, which is what makes
- *   "clear the filters an admin declared" expressible.
- *
- * Every display implemented one half of this and a different half each:
- * `LinearBasicDisplay` had both tiers, `LDDisplay` had the slot alone, and the
- * multi-sample variant displays had a property literally named `jexlFilters`
- * that shadowed the inherited slot, so a config filter on one of those tracks
- * was read by nothing and reported no error. Neither of the last two prefixed,
- * so a filter following the slot's own documented convention reached
- * `stringToJexlExpression` unprefixed and threw inside the worker.
+ * The feature-filter contract, shared by every display offering a "Filter
+ * by..." row: the **`filter` config slot** holds the filters applied, as
+ * `jexl:` expressions (`jexlFilterConfigSchemaFields` in display-kit, spread
+ * by the canvas base display schema, the mark display schema and the shared
+ * multi-sample variant schema). The dialog, a feature's "Filter" actions and
+ * "Edit plot..." all write that slot, and the session keeps the write as it
+ * keeps any track setting, so "Reset track settings" returns it with the
+ * rest.
  */
 export interface JexlFilterSource {
-    /**
-     * The dialog's override, `jexl:`-prefixed. `undefined` means "follow the
-     * config slot"; an empty array means "the user cleared them".
-     */
-    jexlFiltersSetting?: readonly string[];
-    /**
-     * The config tier, `jexl:`-prefixed — in practice
-     * `configuredJexlFilters(self)`. A member rather than a read this module does
-     * itself, so the two things that consume this contract off a **duck-typed**
-     * model — LD's structural menu builder and its shape test — need no live
-     * config node to answer a count with.
-     */
+    /** The slot's filters, in practice `configuredJexlFilters(self)`. */
     configuredFilters: () => string[];
 }
 /**
  * The writing half, for the dialog and the menu's clear row. Separate from
- * {@link JexlFilterSource} because a display declares `activeFilters()` in an
- * earlier `.views()` block than the `.actions()` block declaring its setter, so
- * requiring the setter to *read* the filters would put the two in an order MST
- * cannot satisfy.
+ * {@link JexlFilterSource} because a display declares its readers in an
+ * earlier `.views()` block than the `.actions()` block declaring its setter.
  */
 export interface JexlFilterModel extends JexlFilterSource {
-    setJexlFilters: (filters?: string[]) => void;
+    /** What the track's config declares, which "Clear all filters" returns to. */
+    baseFilters: () => string[];
+    /** Write the slot; undefined returns it to {@link baseFilters}. */
+    setFilter: (filters?: string[]) => void;
 }
-/**
- * What the `jexlFilters` config slot alone declares, `jexl:`-prefixed. The slot
- * stores them unprefixed and every runtime consumer wants them prefixed, so the
- * prefixing happens once, here — this is what a display's `configuredFilters`
- * member is.
- */
+/** What the `filter` config slot holds: a display's `configuredFilters`. */
 export declare function configuredJexlFilters(self: Parameters<typeof getConf>[0]): string[];
 /**
- * The filters actually applied, `jexl:`-prefixed — the single source of truth
- * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
- * filters show up and are editable), and for the narrowing count below.
+ * What the track's config declares for this display's `filter`, before the
+ * session wrote any: a display's `baseFilters`. Empty in a session that keeps
+ * no base.
  */
-export declare function activeJexlFilters(self: JexlFilterSource): string[];
+export declare function baseJexlFilters(self: object): string[];
 /**
- * The `Reversible` a display declares for its jexl filters.
- *
- * The count is whether the override **differs from the configured baseline**,
- * not the number of expressions: a filter an admin declared is not something
- * the user narrowed, and "Clear all filters" could not undo it anyway. It
- * counts in both directions when they differ — narrowing further, and (emptied
- * over a slot that declares filters) widening past what the config asked for.
- *
- * No per-item row: a list of jexl expressions has no recovery to name beyond
- * restoring the config default, which the group clear already is.
+ * The `Reversible` a display declares for its jexl filters. The count is
+ * whether the filters differ from what the track's config declares, not the
+ * number of expressions: a filter an admin declared is not something the user
+ * narrowed. It counts in both directions, narrowing further and, emptied over
+ * a config that declares filters, widening past it.
  */
 export declare function jexlFilterNarrowing(self: JexlFilterModel): Reversible;
+/**
+ * A v4 session's display-instance `jexlFiltersSetting`, which is the `filter`
+ * slot now: the retired state the canvas and single-sample variant displays
+ * declare (ADR-168).
+ */
+export declare const retiredFilterState: RetiredDisplayState;

package/esm/util/jexlFilters.js

@@ -2,48 +2,50 @@
 // which import this one, and a value import back into it is the cycle shape
 // `openFeatureWidget` documents
 import { getConf } from '../configuration/getConf.js';
+import { baseDisplayConfig } from './baseDisplayConfig.js';
 import { ensureJexlPrefix } from './jexlStrings.js';
-/**
- * What the `jexlFilters` config slot alone declares, `jexl:`-prefixed. The slot
- * stores them unprefixed and every runtime consumer wants them prefixed, so the
- * prefixing happens once, here — this is what a display's `configuredFilters`
- * member is.
- */
+/** What the `filter` config slot holds: a display's `configuredFilters`. */
 export function configuredJexlFilters(self) {
-    return getConf(self, 'jexlFilters').map(ensureJexlPrefix);
+    return getConf(self, 'filter');
 }
 /**
- * The filters actually applied, `jexl:`-prefixed — the single source of truth
- * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
- * filters show up and are editable), and for the narrowing count below.
+ * What the track's config declares for this display's `filter`, before the
+ * session wrote any: a display's `baseFilters`. Empty in a session that keeps
+ * no base.
  */
-export function activeJexlFilters(self) {
-    const { jexlFiltersSetting } = self;
-    return jexlFiltersSetting ? [...jexlFiltersSetting] : self.configuredFilters();
+export function baseJexlFilters(self) {
+    const declared = baseDisplayConfig(self).filter;
+    return Array.isArray(declared)
+        ? declared.map(f => ensureJexlPrefix(String(f)))
+        : [];
 }
 /**
- * The `Reversible` a display declares for its jexl filters.
- *
- * The count is whether the override **differs from the configured baseline**,
- * not the number of expressions: a filter an admin declared is not something
- * the user narrowed, and "Clear all filters" could not undo it anyway. It
- * counts in both directions when they differ — narrowing further, and (emptied
- * over a slot that declares filters) widening past what the config asked for.
- *
- * No per-item row: a list of jexl expressions has no recovery to name beyond
- * restoring the config default, which the group clear already is.
+ * The `Reversible` a display declares for its jexl filters. The count is
+ * whether the filters differ from what the track's config declares, not the
+ * number of expressions: a filter an admin declared is not something the user
+ * narrowed. It counts in both directions, narrowing further and, emptied over
+ * a config that declares filters, widening past it.
  */
 export function jexlFilterNarrowing(self) {
-    const override = self.jexlFiltersSetting;
-    const configured = self.configuredFilters();
+    const current = self.configuredFilters();
+    const base = self.baseFilters();
     return {
-        count: override !== undefined &&
-            (override.length !== configured.length ||
-                override.some((f, i) => ensureJexlPrefix(f) !== configured[i]))
+        count: current.length !== base.length || current.some((f, i) => f !== base[i])
             ? 1
             : 0,
         clear: () => {
-            self.setJexlFilters(undefined);
+            self.setFilter(undefined);
         },
     };
 }
+/**
+ * A v4 session's display-instance `jexlFiltersSetting`, which is the `filter`
+ * slot now: the retired state the canvas and single-sample variant displays
+ * declare (ADR-168).
+ */
+export const retiredFilterState = {
+    keys: ['jexlFiltersSetting'],
+    lift: ({ jexlFiltersSetting }) => Array.isArray(jexlFiltersSetting)
+        ? { filter: jexlFiltersSetting.map(f => ensureJexlPrefix(String(f))) }
+        : {},
+};

package/esm/util/jexlStrings.d.ts

@@ -1,6 +1,6 @@
 export interface JexlExpression {
     eval(context?: Record<string, unknown>): unknown;
-    _exprStr?: string;
+    readonly source?: string;
 }
 export interface JexlInstance {
     compile(code: string): JexlExpression;
@@ -11,9 +11,8 @@ export declare function isJexl(str: unknown): str is string;
 /** Add the `jexl:` prefix unless the string already carries it. */
 export declare function ensureJexlPrefix(code: string): string;
 /**
- * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
- * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
- * wrapper.
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
  *
  * @param str - string of code like `jexl:...`
  * @param jexl - the instance whose registered functions the expression may call

package/esm/util/jexlStrings.js

@@ -8,9 +8,8 @@ export function ensureJexlPrefix(code) {
     return isJexl(code) ? code : `${JEXL_PREFIX}${code}`;
 }
 /**
- * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
- * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
- * wrapper.
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
  *
  * @param str - string of code like `jexl:...`
  * @param jexl - the instance whose registered functions the expression may call

package/esm/util/layouts/GranularRectLayout.d.ts

@@ -17,9 +17,16 @@ export default class GranularRectLayout {
         hardRowLimit?: number;
     });
     /**
+     * `lower` gives the rows lying wholly at or past `lower.top` px below the
+     * rect's top a span of their own.
+     *
      * @returns top position for the rect, or Null if laying
      *  out the rect would exceed maxHeight
      */
-    addRect(id: string, left: number, right: number, height: number): number | null;
+    addRect(id: string, left: number, right: number, height: number, lower?: {
+        top: number;
+        left: number;
+        right: number;
+    }): number | null;
     private getOrCreateRow;
 }