@uwdata/mosaic-core 0.17.0 → 0.19.0

package/dist/src/Selection.js

@@ -0,0 +1,322 @@
+import { literal, or } from '@uwdata/mosaic-sql';
+import { Param } from './Param.js';
+/**
+ * Test if a value is a Selection instance.
+ * @param x The value to test.
+ * @returns True if the input is a Selection, false otherwise.
+ */
+export function isSelection(x) {
+    return x instanceof Selection;
+}
+function create(options, include) {
+    return new Selection(new SelectionResolver(options), include ? [include].flat() : undefined);
+}
+/**
+ * Represents a dynamic set of query filter predicates.
+ */
+export class Selection extends Param {
+    _resolved;
+    _resolver;
+    _relay;
+    /**
+     * Create a new Selection instance with an
+     * intersect (conjunction) resolution strategy.
+     * @param options The selection options.
+     * @returns The new Selection instance.
+     */
+    static intersect({ cross = false, empty = false, include = [] } = {}) {
+        return create({ cross, empty }, include);
+    }
+    /**
+     * Create a new Selection instance with a
+     * union (disjunction) resolution strategy.
+     * @param options The selection options.
+     * @returns The new Selection instance.
+     */
+    static union({ cross = false, empty = false, include = [] } = {}) {
+        return create({ cross, empty, union: true }, include);
+    }
+    /**
+     * Create a new Selection instance with a singular resolution strategy
+     * that keeps only the most recent selection clause.
+     * @param options The selection options.
+     * @returns The new Selection instance.
+     */
+    static single({ cross = false, empty = false, include = [] } = {}) {
+        return create({ cross, empty, single: true }, include);
+    }
+    /**
+     * Create a new Selection instance with a
+     * cross-filtered intersect resolution strategy.
+     * @param options The selection options.
+     * @returns The new Selection instance.
+     */
+    static crossfilter({ empty = false, include = [] } = {}) {
+        return create({ cross: true, empty }, include);
+    }
+    /**
+     * Create a new Selection instance.
+     * @param resolver The selection resolution
+     *  strategy to apply.
+     * @param include Upstream selections whose clauses
+     * should be included as part of this selection. Any clauses published
+     * to these upstream selections will be relayed to this selection.
+     */
+    constructor(resolver = new SelectionResolver(), include = []) {
+        super([]);
+        this._resolved = this._value;
+        this._resolver = resolver;
+        this._relay = new Set();
+        if (Array.isArray(include)) {
+            for (const sel of include) {
+                sel._relay.add(this);
+            }
+        }
+    }
+    /**
+     * Create a cloned copy of this Selection instance.
+     * @returns A clone of this selection.
+     */
+    clone() {
+        const s = new Selection(this._resolver);
+        s._value = s._resolved = this._value;
+        return s;
+    }
+    /**
+     * Create a clone of this Selection with clauses corresponding
+     * to the provided source removed.
+     * @param source The clause source to remove.
+     * @returns A cloned and updated Selection.
+     */
+    remove(source) {
+        const s = this.clone();
+        s._value = s._resolved = s._resolver.resolve(this._resolved, { source });
+        s._value.active = { source };
+        return s;
+    }
+    /**
+     * The selection clause resolver.
+     */
+    get resolver() {
+        return this._resolver;
+    }
+    /**
+     * Indicate if this selection has a single resolution strategy.
+     */
+    get single() {
+        return this._resolver.single;
+    }
+    /**
+     * The current array of selection clauses.
+     */
+    get clauses() {
+        return super.value;
+    }
+    /**
+     * The current active (most recently updated) selection clause.
+     */
+    get active() {
+        return this.clauses.active;
+    }
+    /**
+     * The value corresponding to the current active selection clause.
+     * This method ensures compatibility where a normal Param is expected.
+     */
+    // @ts-expect-error return type differs from Param parent class
+    get value() {
+        return this.active?.value;
+    }
+    /**
+     * The value corresponding to a given source. Returns undefined if
+     * this selection does not include a clause from this source.
+     * @param source The clause source to look up the value for.
+     */
+    valueFor(source) {
+        return this.clauses.find(c => c.source === source)?.value;
+    }
+    /**
+     * Emit an activate event with the given selection clause.
+     * @param clause The clause representing the potential activation.
+     */
+    activate(clause) {
+        // @ts-expect-error selection operates differently than scalar param
+        this.emit('activate', clause);
+        this._relay.forEach(sel => sel.activate(clause));
+    }
+    /**
+     * Update the selection with a new selection clause.
+     * @param clause The selection clause to add.
+     * @returns This Selection instance.
+     */
+    // @ts-expect-error selection and param use differing value types
+    update(clause) {
+        // we maintain an up-to-date list of all resolved clauses
+        // this ensures consistent clause state across unemitted event values
+        this._resolved = this._resolver.resolve(this._resolved, clause, true);
+        this._resolved.active = clause;
+        this._relay.forEach(sel => sel.update(clause));
+        return super.update(this._resolved);
+    }
+    /**
+     * Reset the selection state by removing all provided clauses. If no clause
+     * array is provided as an argument, all current clauses are removed. The
+     * reset method (if defined) is invoked on all corresponding clause sources.
+     * The reset is relayed to downstream selections that include this selection.
+     * @param clauses The clauses to remove. If unspecified, all current clauses are removed.
+     * @returns This selection instance.
+     */
+    reset(clauses) {
+        clauses ??= this._resolved;
+        clauses.forEach(c => c.source?.reset?.());
+        this._resolved = this._resolved.filter(c => clauses.includes(c));
+        this._relay.forEach(sel => sel.reset(clauses));
+        return super.update(this._resolved = []);
+    }
+    /**
+     * Upon value-typed updates, sets the current clause list to the
+     * input value and returns the active clause value.
+     * @param type The event type.
+     * @param value The input event value.
+     * @returns For value-typed events, returns the active clause
+     *  values. Otherwise returns the input event value as-is.
+     */
+    // @ts-expect-error selection and param use differing value types
+    willEmit(type, value) {
+        if (type === 'value') {
+            this._value = value;
+            return this.value;
+        }
+        return value;
+    }
+    /**
+     * Upon value-typed updates, returns a dispatch queue filter function.
+     * The return value depends on the selection resolution strategy.
+     * @param type The event type.
+     * @param value The new event value that will be enqueued.
+     * @returns A dispatch queue filter function. For non-value events,
+     *  returns a function that always returns null (no filtering).
+     */
+    // @ts-expect-error selection and param use differing value types
+    emitQueueFilter(type, value) {
+        return type === 'value'
+            ? this._resolver.queueFilter(value)
+            : null;
+    }
+    /**
+     * Indicates if a selection clause should not be applied to a given client.
+     * The return value depends on the selection resolution strategy.
+     * @param client The client to test. If null or undefined, return false.
+     * @param clause The selection clause.
+     * @returns True if the client should be skipped, false otherwise.
+     */
+    skip(client, clause) {
+        return this._resolver.skip(client, clause);
+    }
+    /**
+     * Return a selection query predicate for the given client.
+     * @param client The client whose data may be filtered. If null or undefined, return a predicate with all clauses.
+     * @param noSkip Disable skipping of active
+     *  cross-filtered sources. If set true, the source of the active
+     *  clause in a cross-filtered selection will not be skipped.
+     * @returns The query predicate for filtering client data,
+     *  based on the current state of this selection.
+     */
+    predicate(client = undefined, noSkip = false) {
+        const { clauses } = this;
+        const active = noSkip ? null : clauses.active;
+        return this._resolver.predicate(clauses, active, client);
+    }
+}
+/**
+ * Implements selection clause resolution strategies.
+ */
+export class SelectionResolver {
+    union;
+    cross;
+    single;
+    empty;
+    /**
+     * Create a new selection resolved instance.
+     * @param options The resolution strategy options.
+     * @param options.union Boolean flag to indicate a union strategy.
+     *  If false, an intersection strategy is used.
+     * @param options.cross Boolean flag to indicate cross-filtering.
+     * @param options.single Boolean flag to indicate single clauses only.
+     * @param options.empty Boolean flag indicating if a lack
+     *  of clauses should correspond to an empty selection with no records. This
+     *  setting determines the default selection state.
+     */
+    constructor({ union, cross, single, empty } = {}) {
+        this.union = !!union;
+        this.cross = !!cross;
+        this.single = !!single;
+        this.empty = !!empty;
+    }
+    /**
+     * Resolve a list of selection clauses according to the resolution strategy.
+     * @param clauseList An array of selection clauses.
+     * @param clause A new selection clause to add.
+     * @returns An updated array of selection clauses.
+     */
+    resolve(clauseList, clause, reset = false) {
+        const { source, predicate } = clause;
+        const filtered = clauseList.filter(c => source !== c.source);
+        const clauses = this.single ? [] : filtered;
+        if (this.single && reset)
+            filtered.forEach(c => c.source?.reset?.());
+        if (predicate)
+            clauses.push(clause);
+        return clauses;
+    }
+    /**
+     * Indicates if a selection clause should not be applied to a given client.
+     * The return value depends on the resolution strategy.
+     * @param client The client to test. If null or undefined, return false.
+     * @param clause The selection clause.
+     * @returns True if the client should be skipped, false otherwise.
+     */
+    skip(client, clause) {
+        if (client == null) {
+            return false;
+        }
+        return Boolean(this.cross && clause?.clients?.has(client));
+    }
+    /**
+     * Return a selection query predicate for the given client.
+     * @param clauseList An array of selection clauses.
+     * @param active The current active selection clause.
+     * @param client The client whose data may be filtered. If null or undefined, return all clauses.
+     * @returns The query predicate for filtering client data,
+     *  based on the current state of this selection.
+     */
+    predicate(clauseList, active, client) {
+        const { empty, union } = this;
+        if (empty && !clauseList.length) {
+            return [literal(false)];
+        }
+        // do nothing if cross-filtering and client is currently active
+        if (this.skip(client, active))
+            return undefined;
+        // remove client-specific predicates if cross-filtering
+        const predicates = clauseList
+            .filter(clause => !this.skip(client, clause))
+            .map(clause => clause.predicate);
+        // return appropriate conjunction or disjunction
+        // an array of predicates is implicitly conjunctive
+        return union && predicates.length > 1 ? or(predicates) : predicates;
+    }
+    /**
+     * Returns a filter function for queued selection updates.
+     * @param value The new event value that will be enqueued.
+     * @returns A dispatch queue filter
+     *  function, or null if all unemitted event values should be filtered.
+     */
+    queueFilter(value) {
+        if (this.cross) {
+            const source = value.active?.source;
+            return value => value.active?.source !== source;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=Selection.js.map

package/dist/src/Selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Selection.js","sourceRoot":"","sources":["../../src/Selection.ts"],"names":[],"mappings":"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"}

package/dist/src/SelectionClause.d.ts

@@ -0,0 +1,222 @@
+import { MosaicClient } from './MosaicClient.js';
+import { type ExprNode, type ExprValue, type ScaleOptions, type ScaleDomain, contains, prefix, regexp_matches, suffix } from '@uwdata/mosaic-sql';
+/**
+ * Selection clause metadata to guide possible query optimizations.
+ * Sub-interfaces provide more information about the specifics of a
+ * given selection based on the selection type.
+ */
+export interface ClauseMetadata {
+    /**
+     * The selection type, such as `'point'`, `'interval'`, or `'match'`.
+     */
+    type: string;
+}
+/**
+ * Selection clause metadata indicating selection of one or more discrete
+ * point values, typically based on equality or is distinctiveness checks.
+ */
+export interface PointMetadata extends ClauseMetadata {
+    type: 'point';
+}
+/**
+ * Selection clause metadata indicating text search matching.
+ */
+export interface MatchMetadata extends ClauseMetadata {
+    type: 'match';
+    /** The text search matching method used. */
+    method?: 'contains' | 'prefix' | 'suffix' | 'regexp' | (string & {});
+}
+/** A binning method name. */
+export type BinMethod = 'floor' | 'ceil' | 'round';
+/**
+ * Selection clause metadata for one or more selected intervals. This
+ * metadata can be used to determine appropriate data-space binning
+ * schemes that correspond to pixel-level bins in screen space.
+ */
+export interface IntervalMetadata extends ClauseMetadata {
+    type: 'interval';
+    /**
+     * The interactive pixel size used by the generating component.
+     * Values larger than one indicate intervals that "snap-to" values
+     * greater than a single pixel. If unspecified, assumed to be `1`.
+     */
+    pixelSize?: number;
+    /**
+     * An array of one or more scale descriptors that describe the
+     * mapping from data values to screen pixels.
+     */
+    scales?: ScaleOptions[];
+    /**
+     * A hint for the binning method to use when discretizing the
+     * interval domain. If unspecified, the default is `'floor'`.
+     */
+    bin?: BinMethod;
+}
+export type ClauseSource = object & {
+    reset?: () => void;
+};
+/**
+ * A selection clause representing filtering criteria
+ * to apply within a Mosaic Selection.
+ */
+export interface SelectionClause {
+    /**
+     * A unique identifier (according to object equality) for the source
+     * component that generated this clause. In many cases, this is a
+     * reference to the originating component itself.
+     */
+    source: ClauseSource;
+    /**
+     * A set of Mosaic clients associated with this clause that should not
+     * be updated when this clause is applied in a cross-filtering context.
+     */
+    clients?: Set<MosaicClient>;
+    /**
+     * A selected value associated with this clause. For example, for a 1D
+     * interval selection clause the value may be a [lo, hi] array.
+     */
+    value: unknown;
+    /**
+     * A predicate SQL expression suitable for use in a query WHERE clause.
+     * The predicate should apply filtering criteria consistent with this
+     * clause's *value* property.
+     */
+    predicate: ExprNode | null;
+    /**
+     * Optional clause metadata that varies based on the selection type.
+     * The metadata can be used to optimize selection queries, for example
+     * by creating materialized views of pre-aggregated data when applicable.
+     */
+    meta?: ClauseMetadata;
+}
+interface PointOptions {
+    source: ClauseSource;
+    clients?: Set<MosaicClient>;
+}
+/**
+ * Generate a selection clause for a single selected point value.
+ * @param field The table column or expression to select.
+ * @param value The selected value.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns The generated selection clause.
+ */
+export declare function clausePoint(field: ExprValue, value: unknown, { source, clients }: PointOptions): SelectionClause;
+/**
+ * Generate a selection clause for multiple selected point values.
+ * @param fields The table columns or expressions to select.
+ * @param value The selected values, as an array of
+ *  arrays. Each subarray contains values for each *fields* entry.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns The generated selection clause.
+ */
+export declare function clausePoints(fields: ExprValue[], value: unknown[][] | null | undefined, { source, clients }: PointOptions): SelectionClause;
+/** Interval selection clause options. */
+interface IntervalOptions {
+    source: ClauseSource;
+    clients?: Set<MosaicClient>;
+    bin?: BinMethod;
+    pixelSize?: number;
+}
+/**
+ * Generate a selection clause for a selected 1D interval.
+ * @param field The table column or expression to select.
+ * @param value The selected interval as a [lo, hi] array.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param options.scale The scale mapping descriptor.
+ * @param options.bin A binning method hint.
+ * @param options.pixelSize The interactive pixel size.
+ * @returns The generated selection clause.
+ */
+export declare function clauseInterval(field: ExprValue, value: ScaleDomain | null | undefined, { source, clients, bin, scale, pixelSize }: IntervalOptions & {
+    scale?: ScaleOptions;
+}): SelectionClause;
+/**
+ * Generate a selection clause for multiple selected intervals.
+ * @param fields The table columns or expressions to select.
+ * @param value The selected intervals, as an array of extents.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @param options.scales The scale mapping descriptors,
+ *  in an order matching the given *fields* and *value* extents.
+ * @param options.bin A binning method hint.
+ * @param options.pixelSize The interactive pixel size.
+ * @returns The generated selection clause.
+ */
+export declare function clauseIntervals(fields: ExprValue[], value: ScaleDomain[] | null | undefined, { source, clients, bin, scales, pixelSize }: IntervalOptions & {
+    scales?: ScaleOptions[];
+}): SelectionClause;
+declare const MATCH_METHODS: {
+    contains: typeof contains;
+    prefix: typeof prefix;
+    suffix: typeof suffix;
+    regexp: typeof regexp_matches;
+};
+/** Text search matching methods. */
+export type MatchMethod = keyof typeof MATCH_METHODS;
+/** Text matching selection clause options. */
+export interface MatchOptions {
+    source: ClauseSource;
+    clients?: Set<MosaicClient>;
+    method?: MatchMethod;
+    caseSensitive?: boolean;
+}
+/**
+ * Generate a selection clause for text search matching over a single column.
+ * @param field The table column or expression to match.
+ * @param value The selected text search query string.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients Mosaic clients associated with this clause.
+ *  These clients are not filtered by this clause in cross-filtering contexts.
+ * @param options.method The text matching method to use, default `'contains'`.
+ * @param options.caseSensitive Flag for case sensitive matching, default `false`.
+ * @returns The generated selection clause.
+ */
+export declare function clauseMatch(field: string | ExprNode, value: string | null | undefined, { source, clients, method, caseSensitive }: MatchOptions): SelectionClause;
+/**
+ * Generate a selection clause for text search matching over multiple columns.
+ * A match will succeed if any field successfully matches.
+ * @param fields The table columns or expressions to match.
+ * @param value The selected text search query string.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients Mosaic clients associated with this clause.
+ *  These clients are not filtered by this clause in cross-filtering contexts.
+ * @param options.method The text matching method to use, default `'contains'`.
+ * @param options.caseSensitive Flag for case sensitive matching, default `false`.
+ * @returns The generated selection clause.
+ */
+export declare function clauseMatchAny(fields: (string | ExprNode)[], value: string | null, { source, clients, method, caseSensitive }: MatchOptions): SelectionClause;
+/**
+ * Generate a selection clause for a single selected point value in a list.
+ * @param field The table column or expression to select, which must be a list.
+ * @param value The selected value.
+ * @param options Additional clause properties.
+ * @param options.source The source component generating this clause.
+ * @param options.clients The Mosaic clients associated
+ *  with this clause. These clients are not filtered by this clause in
+ *  cross-filtering contexts.
+ * @returns The generated selection clause.
+ */
+export declare function clauseList(field: ExprValue, value: unknown, { source, clients, listMatch }: {
+    source: ClauseSource;
+    clients?: Set<MosaicClient>;
+    listMatch?: 'any' | 'all';
+}): SelectionClause;
+export {};
+//# sourceMappingURL=SelectionClause.d.ts.map

package/dist/src/SelectionClause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelectionClause.d.ts","sourceRoot":"","sources":["../../src/SelectionClause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAO,QAAQ,EAA+C,MAAM,EAAE,cAAc,EAAE,MAAM,EAAiC,MAAM,oBAAoB,CAAC;AAEnO;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,IAAI,EAAE,OAAO,CAAC;IACd,4CAA4C;IAC5C,MAAM,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CACtE;AAED,6BAA6B;AAC7B,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,IAAI,EAAE,UAAU,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB;;;OAGG;IACH,GAAG,CAAC,EAAE,SAAS,CAAA;CAChB;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CAAE,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B;;;OAGG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED,UAAU,YAAY;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,OAAO,EAAE,EACd,MAAM,EACN,OAAgE,EACjE,EAAE,YAAY,GACd,eAAe,CAWjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EAAE,EACnB,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,GAAG,SAAS,EACrC,EACE,MAAM,EACN,OAAgE,EACjE,EAAE,YAAY,GACd,eAAe,CAiBjB;AAED,yCAAyC;AACzC,UAAU,eAAe;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,EACrC,EACE,MAAM,EACN,OAAgE,EAChE,GAAG,EACH,KAAK,EACL,SAAa,EACd,EAAE,eAAe,GAAG;IAAE,KAAK,CAAC,EAAE,YAAY,CAAA;CAAE,GAC5C,eAAe,CASjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EAAE,EACnB,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,GAAG,SAAS,EACvC,EACE,MAAM,EACN,OAAgE,EAChE,GAAG,EACH,MAAW,EACX,SAAa,EACd,EAAE,eAAe,GAAG;IAAE,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,GAC/C,eAAe,CAWjB;AAID,QAAA,MAAM,aAAa;;;;;CAAuD,CAAC;AAE3E,oCAAoC;AACpC,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,aAAa,CAAC;AAErD,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,GAAG,QAAQ,EACxB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,EACE,MAAM,EACN,OAAmB,EACnB,MAAmB,EACnB,aAAqB,EACtB,EAAE,YAAY,GACd,eAAe,CAMjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,CAAC,MAAM,GAAG,QAAQ,CAAC,EAAE,EAC7B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,EACE,MAAM,EACN,OAAmB,EACnB,MAAmB,EACnB,aAAqB,EACtB,EAAE,YAAY,GACd,eAAe,CAUjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,OAAO,EACd,EACE,MAAM,EACN,OAAgE,EAChE,SAAiB,EAClB,EAAE;IACD,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAC5B,SAAS,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;CAC3B,GACA,eAAe,CAIjB"}