@elaraai/e3-ui 1.0.94 → 1.0.95

package/dist/src/roster/targets.js

@@ -0,0 +1,213 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Roster.targets(record, config)` (#1368, `Builder Interfaces Spec.md`
+ * §5.2): the staffing targets the Roster writes, the app's own record — a row
+ * per slot, its fields mapped to the Roster's roles: the slot's day, group and
+ * shift, the positions to fill, and the hours each activity needs. The app's
+ * forecast fills it; the planner edits it.
+ *
+ * - **Roles.** Each names a field of the row: `day` a DateTime (a UTC
+ *   midnight), `group` and `shift` Strings, `positions` an Integer, `hours` a
+ *   `Dict<String, Float>`. An edit writes only those fields; every other field
+ *   of the row reads back as it was.
+ * - **New rows.** A slot with no row has no target. A target edit on such a
+ *   slot inserts one, keyed by a key the Roster mints, its unmapped fields
+ *   their type's default.
+ * - **Reads.** Through the Roster's slice, by its `targets` source — an
+ *   interval index from the day to the day, its `range` the day field — and
+ *   then `entries` reads one target by its key; or the record whole.
+ * - **The inspector.** The app's own form for one target, `(row, update) =>
+ *   UIComponentType`, in place of the Roster's.
+ *
+ * The targets are one session of the Roster's history (`session.ts`), as its
+ * duties and its periods are: Save sends their changes through the record's
+ * patch door as a request of their own.
+ *
+ * @packageDocumentation
+ */
+import { BlobType, DateTimeType, DictType, East, Expr, FloatType, IntegerType, NullType, OptionType, StringType, defaultValue, isTypeEqual, none, some, toEastTypeValue, } from "@elaraai/east";
+import { scheduleRecordWindow } from "../schedule/record-window.js";
+import { scheduleRecordSession } from "../schedule/session.js";
+import { checkEntries, typeText } from "../schedule/window.js";
+import { RowInspectorType, rowInspector } from "../utils/row-inspector.js";
+import { RosterTargetEntryType, RosterTargetRolesType, RosterTargetsKindType } from "./types.js";
+/** The key the targets' declaration carries what it is under. */
+export const ROSTER_TARGETS = Symbol("Roster.targets");
+/** A field of a struct as an East expression, by name. */
+function fieldOf(row, name) {
+    return row[name];
+}
+/**
+ * Declares the app's targets (see the module docs).
+ *
+ * @typeParam R - The app's target row type
+ * @param record - The app's record of targets, `Record.bind(record, [e3.mutation.patch(record)])`: a `Dict` keyed by String
+ * @param config - The fields its roles name, the app's own form, and its read by key
+ * @returns The targets, for the Roster's `targets`
+ * @throws {Error} Naming the option: a record not bound with its patch mutation, not keyed by String, or whose rows are no
+ *   structs; a role naming a field the row lacks, or a field of another type; two roles naming one field; `entries`
+ *   that is not a paged read of the record's own entries; and an `inspector` that is no East function `(row, update) =>
+ *   UIComponentType` over the row
+ * @example
+ * ```tsx
+ * import { DateTimeType, DictType, FloatType, IntegerType, StringType, StructType } from "@elaraai/east";
+ * import { Record, Roster } from "@elaraai/e3-ui";
+ * import e3 from "@elaraai/e3";
+ *
+ * const Cover = StructType({ day: DateTimeType, team: StringType, shift: StringType, heads: IntegerType, hours: DictType(StringType, FloatType) });
+ * const cover = e3.record("cover", DictType(StringType, Cover), new Map());
+ * const coverPatch = e3.mutation.patch(cover);
+ *
+ * // Inside the Roster's Reactive body: a target per slot, over the app's own rows.
+ * const targets = Roster.targets(Record.bind(cover, [coverPatch]), { day: "day", group: "team", shift: "shift", positions: "heads", hours: "hours" });
+ * ```
+ */
+export function rosterTargets(record, config) {
+    const where = "Roster.targets";
+    const c = config;
+    const handleType = Expr.type(record);
+    const read = handleType.type === "Struct" ? handleType.fields["read"] : undefined;
+    if (handleType.type !== "Struct" || read === undefined || read.type !== "Function"
+        || handleType.fields["binding"] === undefined) {
+        throw new Error(`${where}: \`record\` is the app's record of targets, bound with its patch mutation — Record.bind(record, [e3.mutation.patch(record)])`);
+    }
+    const recordType = read.output;
+    if (recordType.type !== "Dict" || !isTypeEqual(recordType.key, StringType)) {
+        throw new Error(`${where}: a target is keyed by a String — the Roster mints a new target's key — and this record holds ${typeText(recordType)}`);
+    }
+    const rowType = recordType.value;
+    if (rowType.type !== "Struct") {
+        throw new Error(`${where}: a target's row is a struct of the app's fields, its roles among them — and this record's rows are ${typeText(rowType)}`);
+    }
+    const fields = rowType.fields;
+    // Each role a field of the row, of the role's type.
+    const role = (prop, name, type, what) => {
+        if (typeof name !== "string")
+            throw new Error(`${where}: \`${prop}\` names ${what} of the row`);
+        const held = fields[name];
+        if (held === undefined)
+            throw new Error(`${where}: \`${prop}\` names "${name}", a field the row does not have (${Object.keys(fields).join(", ")})`);
+        if (!isTypeEqual(held, type))
+            throw new Error(`${where}: \`${prop}\` names ${what} — "${name}" holds ${typeText(held)}`);
+        return name;
+    };
+    const day = role("day", c.day, DateTimeType, "a DateTime field, the slot's day");
+    const group = role("group", c.group, StringType, "a String field, the slot's group");
+    const shift = role("shift", c.shift, StringType, "a String field, the slot's shift");
+    const positions = role("positions", c.positions, IntegerType, "an Integer field, the positions to fill");
+    const hours = role("hours", c.hours, DictType(StringType, FloatType), "a Dict of String to Float field, the hours each activity needs");
+    // The Roster writes each role into a field of its own.
+    const named = new Map();
+    for (const [prop, name] of [["day", day], ["group", group], ["shift", shift], ["positions", positions], ["hours", hours]]) {
+        const prior = named.get(name);
+        if (prior !== undefined)
+            throw new Error(`${where}: \`${prior}\` and \`${prop}\` both name "${name}" — the Roster writes each of its roles into a field of its own`);
+        named.set(name, prop);
+    }
+    const inspector = c.inspector === undefined ? undefined : rowInspector(c.inspector, rowType, `${where}: \`inspector\` is the app's own form for one target — an East.function over the target's row and its writer: ` +
+        "East.function([RowType, FunctionType([RowType], NullType)], UIComponentType, ($, row, update) => …), RowType the record's row");
+    // The targets read by key, or whole; and their session, declared now, so a record bound without its patch door is refused here.
+    const entries = c.entries === undefined ? undefined : checkEntries(c.entries, StringType, rowType, `${where}: \`entries\``);
+    const session = scheduleRecordSession(record, StringType, rowType, entries);
+    return {
+        [ROSTER_TARGETS]: true,
+        rowType,
+        build(part) {
+            if (part === undefined && entries !== undefined) {
+                throw new Error(`${where}: \`entries\` reads one target by its key beside the Roster's slice's \`targets\` source, which reads the week's — ` +
+                    "give that source with it, or leave `entries` out to read the record whole");
+            }
+            if (part !== undefined && entries === undefined) {
+                throw new Error(`${where}: the Roster's slice's \`targets\` source reads only the week's targets — and one target, its editing's, ` +
+                    "is read by its key: give `entries` beside it, Data.bindPaged(record), the record's own entries");
+            }
+            // The week's targets through the slice's source — its interval index from the day to the day — or the record whole.
+            const window = part === undefined ? undefined
+                : scheduleRecordWindow(part, "targets", StringType, rowType, day, day, false, false, where);
+            const { editing, entries: seam } = session.build();
+            const Roles = RosterTargetRolesType;
+            // A row's roles: the slot's day, group and shift, its positions and its hours.
+            const rolesOf = East.function([rowType], Roles, (_$, row) => ({
+                day: fieldOf(row, day), group: fieldOf(row, group),
+                shift: fieldOf(row, shift), positions: fieldOf(row, positions),
+                hours: fieldOf(row, hours),
+            }));
+            // The row with its roles written from `roles`, and every other field from `source`.
+            const rowWith = (source, roles) => East.value(Object.fromEntries(Object.keys(fields).map((f) => [f,
+                f === day ? roles.day
+                    : f === group ? roles.group
+                        : f === shift ? roles.shift
+                            : f === positions ? roles.positions
+                                : f === hours ? roles.hours
+                                    : fieldOf(source, f)])), rowType);
+            const RowsType = OptionType(DictType(StringType, RosterTargetEntryType));
+            // Erased as the record's own read is, so the record whole and a window of it are one type.
+            const HeldType = DictType(StringType, rowType);
+            const rows = East.function([DateTimeType, DateTimeType], RowsType, ($, from, to) => {
+                const roles = $.const(rolesOf);
+                const result = $.let(East.value(none, RowsType), RowsType);
+                let held;
+                if (window === undefined) {
+                    held = $.let(East.value(some(session.readAll()), OptionType(HeldType)));
+                }
+                else {
+                    const read = $.const(window);
+                    held = $.let(read(from, to));
+                }
+                $.match(held, {
+                    some: ($2, all) => {
+                        const out = $2.let(new Map(), DictType(StringType, RosterTargetEntryType));
+                        $2.for(all, ($3, row, key) => {
+                            const at = $3.const(fieldOf(row, day));
+                            $3.if(East.greaterEqual(at, from).and(() => East.less(at, to)), ($4) => {
+                                $4(out.insert(key, { roles: roles(row), row: East.Blob.encodeBeast(row, "v2") }));
+                            });
+                        });
+                        $2.assign(result, East.value(some(out), RowsType));
+                    },
+                });
+                return result;
+            });
+            const readRoles = East.function([BlobType], Roles, ($, bytes) => {
+                const of = $.const(rolesOf);
+                return of(bytes.decodeBeast(rowType, "v2"));
+            });
+            const write = East.function([BlobType, Roles], BlobType, ($, bytes, roles) => {
+                const row = $.const(bytes.decodeBeast(rowType, "v2"));
+                return East.Blob.encodeBeast(rowWith(row, roles), "v2");
+            });
+            // A new target: its roles written, and every other field its type's default.
+            const blank = East.value(defaultValue(rowType), rowType);
+            const create = East.function([Roles], BlobType, ($, roles) => {
+                const row = $.const(blank);
+                return East.Blob.encodeBeast(rowWith(row, roles), "v2");
+            });
+            return East.value({
+                editing,
+                entries: seam,
+                rows,
+                read: readRoles,
+                write,
+                create,
+                history: session.history,
+                inspector: inspector === undefined ? East.value(none, OptionType(RowInspectorType)) : East.value(some(inspector), OptionType(RowInspectorType)),
+                rowType: toEastTypeValue(rowType),
+            }, RosterTargetsKindType);
+        },
+    };
+}
+/**
+ * Whether a value is the app's targets, declared (`Roster.targets`): what the
+ * Roster's `targets` checks before it takes one.
+ *
+ * @param value - What the app passed
+ * @returns Whether it is the targets, declared
+ * @internal
+ */
+export function isRosterTargets(value) {
+    return typeof value === "object" && value !== null && value[ROSTER_TARGETS] === true;
+}
+//# sourceMappingURL=targets.js.map

package/dist/src/roster/targets.js.map

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

package/dist/src/roster/times.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * What the Roster reads from a duty's times (#1368, `Builder Interfaces
+ * Spec.md` §5.5): pure East functions, compiled once by the renderer, so a
+ * task and the screen use the same arithmetic.
+ *
+ * - **Day.** A duty's day is the UTC day whose shift start is nearest the
+ *   duty's start ({@link rosterDayOf}); its week is the week holding that day.
+ * - **A duty**, as the Roster reads it, is its kind's roles and its row
+ *   ({@link rosterPlacement}): its slot, from its day, its group and its
+ *   shift; who it is, from its resource; its position, its activity, its own
+ *   times and its hours. A duty whose shift or group isn't configured, or that
+ *   names no one, is placed nowhere: the Roster lists it in Issues and keeps
+ *   it as stored.
+ * - **A move** to another slot ({@link rosterMove}) moves the duty's start
+ *   and end with it, kept where they stood against its shift's start, and
+ *   writes its shift and group: a move and back leaves its times as they were.
+ * - **A new duty** ({@link rosterNewDuty}) runs its slot's shift: from the
+ *   shift's start on its day ({@link rosterShiftStart}), for the shift's
+ *   hours. Copying the week before copies each duty so, its other fields as
+ *   they were.
+ *
+ * @packageDocumentation
+ */
+import { DateTimeType, IntegerType, OptionType, StringType, type EastType, type ExprType, type FunctionType } from "@elaraai/east";
+import { ScheduleRosterRolesType } from "../schedule/types.js";
+import { RosterContextType, RosterPlacementTypeFor } from "./types.js";
+/**
+ * A duty's day (§5.5, rule 1): the UTC midnight of the day whose shift start is
+ * nearest the duty's start.
+ *
+ * @param start - The duty's start
+ * @param clock - Its shift's start, a time of day
+ * @returns Its day, a UTC midnight
+ * @remarks The shift starts on the duty's day within 12 hours of the duty's start, so the day is the one `start` falls in once moved back by the shift's start and on by 12 hours: an early start (`05:00` on the `06:00` shift) is the shift's day, and a night shift's duty past midnight (`00:30` on the `22:00` shift) the night before's.
+ * @internal
+ */
+export declare const rosterDayOf: import("@elaraai/east").CallableFunctionExpr<[DateTimeType, import("@elaraai/east").StructType<{
+    readonly hour: IntegerType;
+    readonly minute: IntegerType;
+}>], DateTimeType>;
+/**
+ * A shift's start on a day (§5.5, rule 5): where a new duty of the shift
+ * starts, and what a duty's own times are drawn against.
+ *
+ * @param day - The day, a UTC midnight
+ * @param shift - The shift
+ * @returns Its start on that day
+ * @internal
+ */
+export declare const rosterShiftStart: import("@elaraai/east").CallableFunctionExpr<[DateTimeType, import("@elaraai/east").StructType<{
+    readonly key: StringType;
+    readonly label: StringType;
+    readonly code: StringType;
+    readonly start: import("@elaraai/east").StructType<{
+        readonly hour: IntegerType;
+        readonly minute: IntegerType;
+    }>;
+    readonly hours: import("@elaraai/east").FloatType;
+}>], DateTimeType>;
+/**
+ * Reads one duty as the Roster does: its kind's roles and its row, in the week
+ * of `start`.
+ *
+ * @typeParam R - The app's duty row type
+ * @param row - The app's duty row type
+ * @returns An East function `(roles, row, key, start, context) → Placement(R)`: the duty placed in the week of
+ *   `start`; `elsewhere` for a duty whose day falls in another week; `unplaced`, with the issue that lists it, for a
+ *   duty of this week whose shift or group isn't configured, or that names no person and no agency
+ * @remarks The duty kind's resource names the `people` slot for a person and the `agencies` slot for an agency's request; a kind with no `position` role holds none, `""`. A duty of a shift not configured has no shift start to be nearest: its day is the UTC day it starts.
+ * @internal
+ */
+export declare function rosterPlacement<R extends EastType>(row: R): ExprType<FunctionType<[ScheduleRosterRolesType, R, StringType, DateTimeType, RosterContextType], RosterPlacementTypeFor<R>>>;
+/**
+ * A duty moved to a slot (§5.5, rule 3): its start and end moved with it,
+ * kept where they stood against its shift's start, and its shift and group
+ * written.
+ *
+ * @param roles - The duty's roles
+ * @param start - The week's first day, a UTC midnight
+ * @param slot - The slot it moves to
+ * @param context - The configuration
+ * @returns Its roles, moved; `none` for a slot whose shift or group isn't configured
+ * @remarks Its length is kept, and its start stands as far from the slot's shift's start as it stood from its own: a move and back leaves its times as they were. A duty of a shift not configured has no start to stand against, and starts the slot's shift.
+ * @internal
+ */
+export declare const rosterMove: import("@elaraai/east").CallableFunctionExpr<[import("@elaraai/east").StructType<{
+    readonly start: DateTimeType;
+    readonly end: DateTimeType;
+    readonly resource: OptionType<import("@elaraai/east").StructType<{
+        readonly kind: StringType;
+        readonly key: StringType;
+    }>>;
+    readonly shift: StringType;
+    readonly group: StringType;
+    readonly position: OptionType<StringType>;
+    readonly activity: OptionType<StringType>;
+    readonly hours: import("@elaraai/east").FloatType;
+}>, DateTimeType, import("@elaraai/east").StructType<{
+    readonly day: IntegerType;
+    readonly group: StringType;
+    readonly shift: StringType;
+}>, import("@elaraai/east").StructType<{
+    readonly people: import("@elaraai/east").DictType<StringType, import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly name: StringType;
+        readonly group: StringType;
+        readonly position: StringType;
+        readonly skills: import("@elaraai/east").SetType<StringType>;
+        readonly contract: import("@elaraai/east").FloatType;
+        readonly agency: import("@elaraai/east").BooleanType;
+        readonly trainer: import("@elaraai/east").BooleanType;
+        readonly trainee: import("@elaraai/east").BooleanType;
+        readonly usual: OptionType<StringType>;
+    }>>;
+    readonly groups: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+    }>>;
+    readonly activities: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+        readonly code: StringType;
+        readonly group: OptionType<StringType>;
+    }>>;
+    readonly shifts: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+        readonly code: StringType;
+        readonly start: import("@elaraai/east").StructType<{
+            readonly hour: IntegerType;
+            readonly minute: IntegerType;
+        }>;
+        readonly hours: import("@elaraai/east").FloatType;
+    }>>;
+    readonly positions: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+        readonly code: StringType;
+        readonly lead: import("@elaraai/east").BooleanType;
+    }>>;
+    readonly agencies: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly name: StringType;
+    }>>;
+    readonly rules: import("@elaraai/east").StructType<{
+        readonly rest: import("@elaraai/east").FloatType;
+        readonly lead: import("@elaraai/east").BooleanType;
+        readonly trainer: import("@elaraai/east").BooleanType;
+        readonly skill: import("@elaraai/east").BooleanType;
+    }>;
+}>], OptionType<import("@elaraai/east").StructType<{
+    readonly start: DateTimeType;
+    readonly end: DateTimeType;
+    readonly resource: OptionType<import("@elaraai/east").StructType<{
+        readonly kind: StringType;
+        readonly key: StringType;
+    }>>;
+    readonly shift: StringType;
+    readonly group: StringType;
+    readonly position: OptionType<StringType>;
+    readonly activity: OptionType<StringType>;
+    readonly hours: import("@elaraai/east").FloatType;
+}>>>;
+/**
+ * A new duty (§5.5, rule 5): it runs its slot's shift, from the shift's start
+ * on its day, for the shift's hours.
+ *
+ * @param who - Who it is: a person, or an agency asked to send someone
+ * @param slot - Its slot
+ * @param start - The week's first day, a UTC midnight
+ * @param position - The position it holds; `none` for a kind with no `position` role
+ * @param activity - Its activity, if any
+ * @param context - The configuration
+ * @returns Its roles; `none` for a slot whose shift or group isn't configured
+ * @remarks A person is a key of the `people` resource kind, an agency of the `agencies` one. Its hours are the shift's, until its row says otherwise. Copying the week before runs each of its duties so, written over its own row.
+ * @internal
+ */
+export declare const rosterNewDuty: import("@elaraai/east").CallableFunctionExpr<[import("@elaraai/east").VariantType<{
+    readonly person: StringType;
+    readonly request: StringType;
+}>, import("@elaraai/east").StructType<{
+    readonly day: IntegerType;
+    readonly group: StringType;
+    readonly shift: StringType;
+}>, DateTimeType, OptionType<StringType>, OptionType<StringType>, import("@elaraai/east").StructType<{
+    readonly people: import("@elaraai/east").DictType<StringType, import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly name: StringType;
+        readonly group: StringType;
+        readonly position: StringType;
+        readonly skills: import("@elaraai/east").SetType<StringType>;
+        readonly contract: import("@elaraai/east").FloatType;
+        readonly agency: import("@elaraai/east").BooleanType;
+        readonly trainer: import("@elaraai/east").BooleanType;
+        readonly trainee: import("@elaraai/east").BooleanType;
+        readonly usual: OptionType<StringType>;
+    }>>;
+    readonly groups: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+    }>>;
+    readonly activities: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+        readonly code: StringType;
+        readonly group: OptionType<StringType>;
+    }>>;
+    readonly shifts: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+        readonly code: StringType;
+        readonly start: import("@elaraai/east").StructType<{
+            readonly hour: IntegerType;
+            readonly minute: IntegerType;
+        }>;
+        readonly hours: import("@elaraai/east").FloatType;
+    }>>;
+    readonly positions: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly label: StringType;
+        readonly code: StringType;
+        readonly lead: import("@elaraai/east").BooleanType;
+    }>>;
+    readonly agencies: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        readonly key: StringType;
+        readonly name: StringType;
+    }>>;
+    readonly rules: import("@elaraai/east").StructType<{
+        readonly rest: import("@elaraai/east").FloatType;
+        readonly lead: import("@elaraai/east").BooleanType;
+        readonly trainer: import("@elaraai/east").BooleanType;
+        readonly skill: import("@elaraai/east").BooleanType;
+    }>;
+}>], OptionType<import("@elaraai/east").StructType<{
+    readonly start: DateTimeType;
+    readonly end: DateTimeType;
+    readonly resource: OptionType<import("@elaraai/east").StructType<{
+        readonly kind: StringType;
+        readonly key: StringType;
+    }>>;
+    readonly shift: StringType;
+    readonly group: StringType;
+    readonly position: OptionType<StringType>;
+    readonly activity: OptionType<StringType>;
+    readonly hours: import("@elaraai/east").FloatType;
+}>>>;
+//# sourceMappingURL=times.d.ts.map

package/dist/src/roster/times.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"times.d.ts","sourceRoot":"","sources":["../../../src/roster/times.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACH,YAAY,EAAQ,WAAW,EAAE,UAAU,EAAE,UAAU,EACvD,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAClD,MAAM,eAAe,CAAC;AACvB,OAAO,EAA8C,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAmB,sBAAsB,EAAkD,MAAM,YAAY,CAAC;AAExI;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW;;;kBAGtB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;kBAC8C,CAAC;AAE5E;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,QAAQ,EAAE,GAAG,EAAE,CAAC,GA6CrC,QAAQ,CAAC,YAAY,CAAC,CAAC,uBAAuB,EAAE,CAAC,EAAE,UAAU,EAAE,YAAY,EAAE,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,CAChJ;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAoBjB,CAAC;AAEP;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiBpB,CAAC"}