@ahoo-wang/wow-view-engine 9.2.0-rc.0

package/dist/runtime/viewRuntimeTypes.d.ts

@@ -0,0 +1,445 @@
+import { DataViewConfig, AnalysisViewConfig, DashboardDefinition, DashboardFilters, DashboardViewConfig, DataViewDefinition, FieldDefinition, FilterTree, Issue, PagingMode, RecordData, RecordKey, RecordPageTarget, RecordViewConfig, RuntimeLimits, ViewAudience, ViewConfig, ViewInstance, ViewScope } from '../model/index.js';
+import { FieldKindRegistry } from '../filter/index.js';
+import { RuntimeEnvironment } from './environment.js';
+import { RequestRunner } from './requestRunner.js';
+import { OptionSource, ProjectedView, ViewSource } from './source.js';
+import { ExportRowsOptions, ExportedRows } from './exportRows.js';
+import { ValueCandidateSource } from './valueCandidates.js';
+import { WriteState } from './write.js';
+import { DashboardRuntime } from './dashboardRuntime.js';
+import { HeldFilters } from './dashboard/contract.js';
+/**
+ * One open view. A small store with `subscribe` and `getSnapshot`, so React
+ * binds to it with `useSyncExternalStore` and nothing else is needed.
+ *
+ * The three states it keeps apart are the whole design: `draft` is what the
+ * editor shows, `applied` is what was last executed, and `result` is what came
+ * back, tagged with the config that produced it.
+ */
+export interface ViewRuntime<C extends ViewConfig = ViewConfig> {
+    /** Runtime identity, distinct from the instance id: an unsaved view has one too. */
+    readonly id: string;
+    readonly kind: C['kind'];
+    readonly definition: DefinitionFor<C>;
+    /**
+     * Fields the filter editor edits against: a data view's own, a dashboard's
+     * declared global ones. A dashboard's set follows its draft, so read this
+     * on every render rather than once per runtime.
+     */
+    readonly fields: readonly FieldDefinition[];
+    /** The registry admission used, which an editor must edit against. */
+    readonly kinds: FieldKindRegistry;
+    /**
+     * The budgets this view was admitted under. An editor offers within them
+     * rather than offering a choice the kernel will then refuse: a page size
+     * above `maxPageSize` is an error the user made by picking from a list the
+     * UI drew, which is the UI's fault and not theirs.
+     */
+    readonly limits: RuntimeLimits;
+    /**
+     * The remote candidates behind a `reference` field's `remote` key, or
+     * `null` when the host wired no `resolveOptions`. The editor asks here
+     * rather than reaching for the engine: a runtime is what a workbench
+     * holds, and a value editor two levels down has no engine to reach.
+     */
+    optionSource(remote: string): OptionSource | null;
+    /**
+     * The values a condition on `field` may be picked from, counted from this
+     * view's data within the injected scope (`ValueCandidateSources`), or
+     * `null` where they are not offered: a field the definition does not let
+     * be grouped by value, one with `options` or `remote` of its own, and every
+     * field of a dashboard, which has no data of its own to count.
+     */
+    valueCandidates(field: string): ValueCandidateSource | null;
+    getSnapshot(): ViewRuntimeState<C>;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Changes the draft only, synchronously.
+     *
+     * A member given as `undefined` is **removed** rather than set to it. A
+     * config is JSON, where a member that is not there and one that is
+     * `undefined` are the same config but not the same object — and `dirty`
+     * is an equality against the saved one, so setting it left a view
+     * permanently unsaved and the leave guard asking about an edit the user
+     * had already undone. An editor that takes the last entry out of an
+     * optional list therefore says `undefined` and gets the config back as it
+     * was.
+     */
+    edit(patch: Partial<C>): void;
+    /**
+     * What the draft uses that its source no longer admits (capabilities.md
+     * Q2): the errors admission raises against the definition as the source
+     * narrows it and not against the definition as declared. The view waits
+     * to be fixed, as for any error, and sends nothing. Empty when nothing
+     * narrows the definition, and on a dashboard.
+     */
+    unavailable(): Issue[];
+    /**
+     * 「移除不可用的条件」: takes out of the draft what `unavailable` names
+     * and can go — a condition, a sort entry, 「只保留」, a dimension's
+     * missing-value group or filled gaps — and leaves the rest, which would
+     * change the question rather than trim it, to the reader. Nothing runs
+     * until the draft is applied.
+     */
+    removeUnavailable(): void;
+    /** Promotes a valid draft to `applied` and executes it. */
+    apply(): void;
+    /**
+     * Takes the draft back to the saved baseline and puts it in force again. A
+     * view that was never saved has no baseline to return to, so it is a no-op
+     * there; what is on screen is all there is.
+     */
+    revert(): void;
+    /**
+     * Re-runs `applied` from the first page. A no-op while `applied` was never
+     * admitted: a view opened on a config the definition refuses waits for a
+     * fix, and no command runs it as it stands.
+     */
+    refresh(): void;
+    /** Called when an editor takes or loses focus; pauses auto-refresh. */
+    setEditing(active: boolean): void;
+    /**
+     * Whether the view refreshes itself on the interval it applied (on when
+     * opened). Off, the timer is held for good — the interval stays what it
+     * was, and saving writes it unchanged — until it is on again: an embed
+     * whose host asked for no auto-refresh (`EmbeddedView`'s `autoRefresh`).
+     * A refresh asked for still runs.
+     */
+    setAutoRefresh(on: boolean): void;
+    /**
+     * Whether the draft runs on its own a moment after its question changes
+     * (`autoApply.ts`); which members are the question is declared per kind
+     * by the model (`autoRunMembers`), and the range still waits for `apply`.
+     * Off by default: the workbench switches it on from the user's preference.
+     */
+    setAutoApply(on: boolean): void;
+    /**
+     * An outer condition ANDed onto the applied filter; never touches the draft.
+     *
+     * Returns what the condition was refused for, which is empty when it is in
+     * force. A refusal changes nothing: the scope in force stays in force, the
+     * result on screen stays on screen, and the host is told — the one thing
+     * this view must never do is narrow less than the page asked without
+     * saying so.
+     */
+    setScopeFilter(tree: FilterTree | null): Issue[];
+    /**
+     * What the scope last asked for was refused for, or empty while what was
+     * asked for is in force.
+     *
+     * A refusal is the host's condition and not the view's defect, so it is not
+     * among `state.issues` and does not stop the view (D17-5): a view opened
+     * under a scope its definition cannot take runs un-narrowed and says this.
+     * Read rather than only returned by `setScopeFilter`, because a scope goes
+     * in at construction as well, and a host that opened one through
+     * `ViewEngine.open` has no return value to read it from.
+     */
+    readonly refusedScope: Issue[];
+    /**
+     * The outer condition in force, as it was last admitted, or `null` while
+     * none is — including a scope that was asked for and refused.
+     *
+     * It is read rather than only written because the conditions the rows came
+     * back under are two things and not one: the view's own, which the editor
+     * addresses and may take out, and the host's, which are in force and are
+     * nobody's here to remove. A summary that reads the merged tree can tell
+     * neither apart — see `ViewResult.own`.
+     */
+    readonly scopeFilter: FilterTree | null;
+    /**
+     * The host this view runs against: its clock, its timers, its visibility.
+     *
+     * Read rather than only written because `nextRefreshAt` is a reading of
+     * *this* clock and means nothing against another one. A countdown that
+     * asked the system clock would drift away from the timer it claims to be
+     * counting to the moment a test, a demo or a server-rendered page injected
+     * a clock of its own — which is the whole reason the environment exists.
+     * `ViewEngine` already hands the same object out for its time zone.
+     */
+    readonly environment: RuntimeEnvironment;
+    dispose(): void;
+    /** True once disposed: every command is a no-op from then on. */
+    readonly disposed: boolean;
+}
+/**
+ * The definition a config belongs to. A dashboard owns no data, so its
+ * definition is a catalogue entry with no fields and no capabilities.
+ */
+export type DefinitionFor<C extends ViewConfig> = C extends DashboardViewConfig ? DashboardDefinition : DataViewDefinition;
+/** Paging and selection belong to Record alone. */
+export interface RecordViewRuntime<P extends PagingMode = PagingMode> extends ViewRuntime<RecordViewConfig> {
+    page(target: RecordPageTarget<P>): void;
+    select(keys: RecordKey[]): void;
+    /**
+     * Every row the **applied** conditions match, paged out behind the screen
+     * for an export — the same filter and sort, without the page on screen.
+     *
+     * It runs beside the view rather than through it: no scheduler slot, no
+     * `apply`, and `state.result` is untouched, so the rows the user is reading
+     * stay exactly as they are while a long export runs. Stopped by
+     * `options.signal`, capped at `limits.exportMax`.
+     */
+    exportRows(options?: ExportRowsOptions): Promise<ExportedRows>;
+    /**
+     * One record, whole, by its row key — for a detail panel (`fetchRecord`):
+     * every field, within the injected scope and not the page's conditions.
+     * `null` when it is no longer there.
+     */
+    fetchRecord(key: RecordKey, signal?: AbortSignal): Promise<RecordData | null>;
+}
+/** What opening an instance returns; narrow it by `runtime.kind`. */
+export type AnyViewRuntime = RecordViewRuntime | ViewRuntime<AnalysisViewConfig> | DashboardRuntime;
+/**
+ * What `ViewEngine` needs beyond the public contract: admission at the scope
+ * a write is headed for, and the three ways an outcome reaches an open view.
+ * Both runtime classes implement it, which is how the engine stays
+ * indifferent to the kind.
+ */
+export interface ManagedViewRuntime<C extends ViewConfig = ViewConfig> extends ViewRuntime<C> {
+    /**
+     * Admission of the draft as it would stand at a target scope, which is what
+     * "save as shared" has to ask: a dashboard may reference views the people it
+     * would be shared with cannot read.
+     */
+    issuesAt(scope: ViewScope): Issue[];
+    /** Advances the saved baseline once the store has confirmed this view's write. */
+    markSaved(instance: ViewInstance): void;
+    /**
+     * Advances the baseline because a write elsewhere moved it: the same
+     * instance open in another view, or renamed from the list. Whatever write
+     * of this view's own is still unsettled stays so, for its recovery actions.
+     */
+    moveBaseline(instance: ViewInstance): void;
+    /** Replaces the draft with the store's state, for "reload" on a conflict. */
+    adoptSaved(instance: ViewInstance): void;
+    /**
+     * A config as it is written to the store, where that differs from how
+     * the view reads it: a board stores no time wire it derives (D1). Left
+     * out, as it is.
+     */
+    stored?(config: C): C;
+    setWrite(write: WriteState | null): void;
+}
+/**
+ * Keeps the narrow type through `create`, which knows its config statically
+ * — and, for a config whose kind only the value knows (a union), is what
+ * `open` hands back (`AnyViewRuntime`), so no caller has to say it again.
+ */
+export type RuntimeFor<C extends ViewConfig> = [C] extends [RecordViewConfig] ? RecordViewRuntime : [C] extends [AnalysisViewConfig] ? ViewRuntime<AnalysisViewConfig> : [C] extends [DashboardViewConfig] ? DashboardRuntime : AnyViewRuntime;
+export type QueryStatus = 'idle' | 'loading' | 'success' | 'error';
+export interface ViewQueryState {
+    status: QueryStatus;
+    error?: Issue;
+    requestId?: string;
+    /**
+     * On a failure: the result still on screen was asked under other
+     * conditions than the query that failed — the reader changed them (in
+     * either filter mode) or a board's filter did, and the new ones did not
+     * come back. A failed refresh of the same conditions leaves it out: its
+     * rows are only older. The rows stay either way (a view that empties
+     * itself on a dropped connection loses what the user was reading), and
+     * this is what lets the screen say which conditions they belong to.
+     */
+    conditionsChanged?: true;
+}
+export interface ViewResult<C> {
+    /** The config that produced this data, scope filter included. */
+    config: C;
+    /**
+     * The view's own half of it: the `applied` config as it was promoted,
+     * before the scope filter was merged in.
+     *
+     * A summary of the conditions in force addresses the draft through this one.
+     * `mergeFilters` appends the scope as a trailing group, and wraps an `or` or
+     * `nor` draft as the first child of an `and`, so a path into `config.filter`
+     * addresses neither the draft's tree nor anything the editor may remove —
+     * and the host's own condition would sit in the bar looking removable.
+     * Equal to `config` when nothing is injected, and for a dashboard, which
+     * runs no query of its own.
+     */
+    own: C;
+    data: ProjectedView;
+    receivedAt: number;
+    /**
+     * How long the answer took, in milliseconds on the environment's clock:
+     * from the moment it was asked to the moment it landed, a wait in the
+     * engine's queue included — that is time the person waited too. A page
+     * re-asked because the result shrank out from under it counts from the
+     * first asking. The analysis result's footer says it («耗时 0.4 秒»).
+     */
+    elapsedMs: number;
+}
+export interface ViewRuntimeState<C> {
+    /** The saved baseline; `null` while the view has never been saved. */
+    saved: ViewInstance | null;
+    title: string;
+    scope: ViewScope;
+    draft: C;
+    applied: C;
+    /**
+     * Admission of the draft as it would run: with the injected scope filter
+     * ANDed in, because that is the config `apply` executes. An `error` blocks
+     * `apply` and every write. The scope is appended after the draft's own
+     * conditions, so a path into the draft's tree is unchanged by it.
+     */
+    issues: Issue[];
+    dirty: boolean;
+    query: ViewQueryState;
+    result: ViewResult<C> | null;
+    /** Row keys of the current result only; cleared when the result changes. */
+    selection: RecordKey[];
+    write: WriteState | null;
+    editing: boolean;
+    /** See `ViewRuntime.setAutoApply`. */
+    autoApply: boolean;
+    /**
+     * When the next automatic refresh is due, on the environment's clock, or
+     * `null` while no timer is armed — no interval in force, or one of the four
+     * reasons the runtime holds it.
+     *
+     * It is the timer's own due time rather than a second opinion about it: set
+     * where the timer is armed, cleared where it is stopped. A control counting
+     * down to the next refresh reads this against `environment.now()`, so what
+     * it says and what will happen cannot come apart; a countdown run off a
+     * clock of its own would.
+     */
+    nextRefreshAt: number | null;
+}
+/**
+ * Whether this view ever got a result, even one that is now out of date.
+ *
+ * Not `rows.length > 0` and not `status === 'success'`: a failed refresh
+ * keeps the rows it could not replace and turns to `error`, and a successful
+ * result matching zero rows has no rows at all. The table, the applied bar
+ * and the result block all ask the same question of the same member, so they
+ * ask it here — a spelling of `state.result != null` at every call site is
+ * one place each for it to start meaning something else.
+ *
+ * Structural in its argument, because it is asked of whatever holds a
+ * snapshot: a runtime's state, a controller's, or nothing yet.
+ */
+export declare function hasResult(state: {
+    result: unknown;
+} | null | undefined): boolean;
+/**
+ * Whether this view has put a question to its source: a result came back,
+ * one is on its way, or the last one failed.
+ *
+ * It is the wider question the chrome around a result asks — the applied
+ * conditions, a toolbar that reads the question out — because each of those
+ * has something true to say from the moment a query is sent, not only from
+ * the moment one lands. Drawn only once rows arrived, they appeared under
+ * the reader's eyes as the first answer landed and pushed the result down
+ * the page, and a first query that failed left the failure standing alone
+ * with nothing around it to act on. A query that was sent was admitted, so
+ * `applied` is a config the screen may describe.
+ *
+ * What it is not: a view whose config was refused before it ran. Nothing
+ * was asked there, and the status line is what speaks.
+ */
+export declare function hasAsked(state: {
+    result: unknown;
+    query: {
+        status: QueryStatus;
+    };
+} | null | undefined): boolean;
+export interface ViewRuntimeOptions<C extends DataViewConfig> {
+    id: string;
+    definition: DataViewDefinition;
+    config: C;
+    title: string;
+    scope: ViewScope;
+    saved?: ViewInstance | null;
+    kinds: FieldKindRegistry;
+    limits: RuntimeLimits;
+    environment: RuntimeEnvironment;
+    source: ViewSource;
+    runner: RequestRunner;
+    /** See `ViewRuntime.optionSource`. */
+    resolveOptions?(key: string): OptionSource;
+    /** An outer condition in force from the first execution on. */
+    scopeFilter?: FilterTree | null;
+    /**
+     * False inside a dashboard, which times the refresh of every panel itself
+     * rather than letting each one run a timer of its own.
+     */
+    autoRefresh?: boolean;
+    /**
+     * What the source admits, followed while the view is open
+     * (capabilities.md 6); left out, the view runs on `definition` for good.
+     */
+    capabilities?: RuntimeCapabilities;
+}
+/** How one open data view follows its source's capability descriptor. */
+export interface RuntimeCapabilities {
+    /** The definition as the application declared it, before any narrowing. */
+    readonly declared: DataViewDefinition;
+    /**
+     * The definition and the limits in force now; throws the refusal when
+     * the descriptor contradicts the definition.
+     */
+    effective(): {
+        definition: DataViewDefinition;
+        limits: RuntimeLimits;
+    };
+    /** Tells `listener` when the descriptor changes; returns the way to stop. */
+    watch(listener: () => void): () => void;
+    /** Checks the descriptor again when it is stale; a refresh is one moment to. */
+    revalidate(): void;
+    /**
+     * Checks the descriptor again at once after the source refused a query
+     * for a capability (`checksDescriptorAgain`); resolves whether it changed.
+     */
+    recheck(code: string | undefined): Promise<boolean>;
+}
+/** What `ViewEngine.create` makes a view from: nothing is saved until `save`. */
+export interface CreateInput<C extends ViewConfig> {
+    title: string;
+    /** A user creates for an audience; only a definition declares a system view. */
+    scope: ViewAudience;
+    config: C;
+    /**
+     * The host's injected condition, as `open` takes it: a view made from an
+     * open one — a drill-through — inherits the scope its origin ran under,
+     * so it never shows a row the page around it was narrowed away from.
+     */
+    scopeFilter?: FilterTree | null;
+}
+/** How `ViewEngine.open` opens a view, beyond which one. */
+export interface OpenOptions {
+    /**
+     * An outer condition in force from the first query, in the view's own field
+     * names. It is admitted with the config rather than after it, so a host that
+     * scopes a view — an order page showing one customer's shipments — never
+     * lets an unscoped query leave, and never shows rows outside its scope.
+     */
+    scopeFilter?: FilterTree | null;
+    /**
+     * The tab a dashboard opens on (D22 E) — a host's route says it. Left out,
+     * the one this reader last read the board on (`ViewPreferences.lastTabs`);
+     * a tab the board lacks opens its first. Nothing else reads it.
+     */
+    tab?: string | null;
+    /**
+     * What a dashboard's filters hold as it opens (D22 F) — a host's address
+     * keeps them. Left out, every filter at its default; what the board does
+     * not take is left out, the rest taken (`DashboardRuntime.refusedFilters`
+     * says what was left out). Nothing else reads it.
+     */
+    filters?: DashboardFilters | null;
+    /**
+     * The filters a host holds as the dashboard opens (`holdFilters`): in
+     * force from the first query, over `filters` or the defaults. Nothing
+     * else reads it.
+     */
+    held?: HeldFilters | null;
+    /**
+     * The definition the caller draws views of — a workbench's. An instance
+     * of another is refused (`view.open.other-definition`) before anything
+     * runs: an id handed over by an address two workbenches share, or by a
+     * host, is no view of this page's, and opening it would show another
+     * page's view under this one's list. Left out, any definition's.
+     */
+    definitionId?: string;
+}
+//# sourceMappingURL=viewRuntimeTypes.d.ts.map

package/dist/runtime/viewRuntimeTypes.d.ts.map

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

package/dist/runtime/write.d.ts

@@ -0,0 +1,96 @@
+import { Issue, ViewAudience, ViewConfig, ViewInstance, ViewPreferences } from '../model/index.js';
+/**
+ * The body of a write, kept as it was sent. A retry and an overwrite replay
+ * this, not the current draft, so the user's intent survives whatever they
+ * edited while the request was in flight.
+ *
+ * The expected `revision` travels with it for the same reason: a retry is the
+ * same logical write, so it carries the same expectation, and only an
+ * overwrite moves it forward to the revision the conflict reported.
+ */
+export type WritePayload = {
+    action: 'preferences';
+    definitionId: string;
+    next: ViewPreferences;
+} | {
+    action: 'create';
+    input: Omit<ViewInstance, 'id' | 'revision'>;
+    /** `first-save` binds the source runtime to the new instance; `save-as` leaves it alone. */
+    intent: 'first-save' | 'save-as';
+} | {
+    action: 'save';
+    id: string;
+    revision: string;
+    config: ViewConfig;
+} | {
+    action: 'rename';
+    id: string;
+    revision: string;
+    title: string;
+} | {
+    action: 'changeAudience';
+    id: string;
+    revision: string;
+    audience: ViewAudience;
+} | {
+    action: 'delete';
+    id: string;
+    definitionId: string;
+    revision: string;
+};
+export type WriteAction = WritePayload['action'];
+/**
+ * An outcome that is not success. A successful write advances the baseline and
+ * clears this field instead.
+ *
+ * `unknown` is the one that matters: the request left, and nothing came back.
+ * It is neither a failure nor a success, and the only safe move is to replay
+ * the same `requestId` and let the server deduplicate. Its `issue`, when it
+ * has one, says what is known of why: the browser's storage would not keep
+ * the write (`view.write.storage`), which a retry writes again once there is
+ * room.
+ */
+export type WriteState = {
+    requestId: string;
+    payload: WritePayload;
+} & ({
+    kind: 'conflict';
+    remote: ViewInstance | ViewPreferences;
+} | {
+    kind: 'rejected';
+    issue: Issue;
+} | {
+    kind: 'unknown';
+    issue?: Issue;
+});
+/**
+ * Addresses a write that no open runtime owns, such as renaming a view from
+ * the list. Its outcome lives in `engine.pendingWrites()`.
+ */
+export interface WriteHandle {
+    readonly id: string;
+}
+/**
+ * How every write command rejects. It carries the outcome and its handle, so
+ * a caller acts on its own command instead of guessing which entry of
+ * `pendingWrites()` belongs to it.
+ */
+export declare class ViewWriteError extends Error {
+    readonly handle: WriteHandle;
+    readonly state: WriteState;
+    constructor(state: WriteState);
+}
+/** By name, as every guard of the engine's errors (`isViewStoreError`). */
+export declare function isViewWriteError(error: unknown): error is ViewWriteError;
+/**
+ * A command the engine refused before dispatching it: a missing definition, an
+ * empty title, a permission the user does not hold, a config that still has an
+ * error. Nothing was sent, so there is no outcome to retry.
+ */
+export declare class ViewCommandError extends Error {
+    readonly issue: Issue;
+    constructor(issue: Issue);
+}
+/** By name, as every guard of the engine's errors (`isViewStoreError`). */
+export declare function isViewCommandError(error: unknown): error is ViewCommandError;
+//# sourceMappingURL=write.d.ts.map

package/dist/runtime/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/runtime/write.ts"],"names":[],"mappings":"AAaA,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACtE;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,UAAU,CAAC,CAAC;IAC7C,4FAA4F;IAC5F,MAAM,EAAE,YAAY,GAAG,SAAS,CAAC;CAClC,GACD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACpE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAGjE;IACE,MAAM,EAAE,gBAAgB,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;CACxB,GAID;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG,CACpE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CACrC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,KAAK,EAAE,UAAU;CAM9B;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAKxE;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;gBAEV,KAAK,EAAE,KAAK;CAKzB;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAK5E"}