@elaraai/east-ui 1.0.7 → 1.0.9

package/dist/src/disclosure/story/index.js

@@ -0,0 +1,369 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { East, ArrayType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType, variant, some, none, } from "@elaraai/east";
+import { UIComponentType } from "../../component.js";
+import { StoryLayoutType, StoryLayout, StoryStepLengthType, StoryActiveBindingType, StoryProgressBindingType, StoryStyleType, } from "./types.js";
+// Re-export types
+export { StoryLayoutType, StoryLayout, StoryStepLengthType, StoryStepLength, StoryActiveBindingType, StoryProgressBindingType, StoryStyleType, } from "./types.js";
+// ============================================================================
+// StoryStepType — standalone mirror of the inline `StoryStep` variant
+// ============================================================================
+/**
+ * Concrete struct mirroring the inline `StoryStep` variant in
+ * `component.ts`. Renderers reference this for `equalFor` / `ValueTypeOf`.
+ *
+ * @remarks
+ * One narrative beat: spine node · eyebrow (`index / total · label`) ·
+ * title · body. The body is the step's children — any east-ui subtree —
+ * and fills the step's full scroll runway. The optional `stage` is the
+ * keyframe shown in the sticky slot while this step is active; a step
+ * without one holds the previous keyframe (the natural shape for two beats
+ * narrating the same visual).
+ *
+ * @property id - Step identifier, used for deep links, snapshot names, and
+ *   the `activeStep` static override
+ * @property eyebrow - Short label after the `index / total` prefix
+ * @property title - Step heading (DM Sans 17px/600)
+ * @property stage - Keyframe rendered in the sticky stage while active
+ * @property body - Rail content (the step's children)
+ */
+export const StoryStepType = StructType({
+    id: StringType,
+    eyebrow: OptionType(StringType),
+    title: OptionType(StringType),
+    stage: OptionType(UIComponentType),
+    body: ArrayType(UIComponentType),
+});
+// ============================================================================
+// StoryType — standalone mirror of the inline `Story` variant
+// ============================================================================
+/**
+ * Concrete struct mirroring the inline `Story` variant in `component.ts`.
+ *
+ * @property steps - Children; expected to be `StoryStep` values (soft
+ *   contract, like ChipRail's chip-shaped children — the renderer skips
+ *   non-step children with a dev warning)
+ * @property active - Optional narrative-position binding (Integer
+ *   read/write closures, the `State.bind` struct)
+ * @property progress - Optional within-step scrub binding (Float 0–1)
+ * @property activeStep - Static override: renders one deterministic
+ *   keyframe by step id (snapshot pipeline / deep links)
+ * @property title - When present, the one-row `Story.Progress` chrome is
+ *   rendered sticky above the story with this eyebrow title
+ * @property onStepEnter - Fired with the step id on activation (either
+ *   scroll direction)
+ * @property onStepExit - Fired with the step id on deactivation
+ * @property style - Visual-presentation sub-struct
+ */
+export const StoryType = StructType({
+    steps: ArrayType(UIComponentType),
+    active: OptionType(StoryActiveBindingType),
+    progress: OptionType(StoryProgressBindingType),
+    activeStep: OptionType(StringType),
+    title: OptionType(StringType),
+    onStepEnter: OptionType(FunctionType([StringType], NullType)),
+    onStepExit: OptionType(FunctionType([StringType], NullType)),
+    style: OptionType(StoryStyleType),
+});
+// ============================================================================
+// StoryProgressType — standalone mirror of the inline `StoryProgress` variant
+// ============================================================================
+/**
+ * Concrete struct mirroring the inline `StoryProgress` variant in
+ * `component.ts`.
+ *
+ * @remarks
+ * The one-row chrome strip: eyebrow title · per-step dots · counter ·
+ * prev/next. Mounts standalone anywhere (a page header, a Drawer foot)
+ * because it only talks to the `active` binding.
+ *
+ * @property count - Total number of steps
+ * @property active - Optional narrative-position binding
+ * @property title - Eyebrow title at the left of the row
+ */
+export const StoryProgressType = StructType({
+    count: IntegerType,
+    active: OptionType(StoryActiveBindingType),
+    title: OptionType(StringType),
+});
+// ============================================================================
+// Story Step Factory
+// ============================================================================
+/**
+ * Creates a Story step — one narrative beat in the rail.
+ *
+ * @param body - Rail content (any east-ui subtree); fills the step's full
+ *   scroll runway
+ * @param options - `id` (required) plus `eyebrow` / `title` / `stage`
+ * @returns An East expression representing the StoryStep component
+ *
+ * @remarks
+ * Steps are real components (a `UIComponentType` variant arm), so a
+ * conditional step (`cond.ifElse(stepA, stepB)`) is legal. One idea per
+ * step: a body that needs a scrollbar is two steps.
+ *
+ * @example
+ * ```ts
+ * import { East } from "@elaraai/east";
+ * import { Story, Text, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const step = East.function([], UIComponentType, _$ =>
+ *     Story.Step([
+ *         Text.Root("Orders climbed from week 6 and never gave the gain back."),
+ *     ], { id: "demand", eyebrow: "Demand", title: "Demand ran hot" }),
+ * );
+ * ```
+ */
+function createStoryStep(body, options) {
+    // Cast at variant boundary — the inline `StoryStep` variant in
+    // component.ts uses the recursive `node` for stage/body, structurally
+    // identical to `UIComponentType` after unfolding but not provably
+    // equal to TS.
+    return East.value(variant("StoryStep", {
+        id: options.id,
+        eyebrow: options.eyebrow !== undefined ? some(options.eyebrow) : none,
+        title: options.title !== undefined ? some(options.title) : none,
+        stage: options.stage !== undefined ? some(options.stage) : none,
+        body: body,
+    }), UIComponentType);
+}
+// ============================================================================
+// Story Root Factory
+// ============================================================================
+/**
+ * Creates a Story — a scroll-driven narrative with a prose rail and a
+ * sticky stage (design/story.html §2.7 Narrate).
+ *
+ * @param steps - The narrative beats, built with `Story.Step` (soft
+ *   contract — non-step children are skipped with a dev warning)
+ * @param options - State + behaviour + visual style fields
+ * @returns An East expression representing the Story component
+ *
+ * @remarks
+ * Scroll drives the active step; the active step drives the stage
+ * keyframe. The component observes native scroll and never hijacks it;
+ * the single sanctioned programmatic scroll is navigation (a step/dot
+ * click or an external `active` write smooth-scrolls that step to the
+ * trigger line). The position is one ordinary state binding — omit
+ * `active` and Story keeps it internal.
+ *
+ * @example
+ * ```ts
+ * import { East } from "@elaraai/east";
+ * import { Story, Text, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const review = East.function([], UIComponentType, _$ =>
+ *     Story.Root([
+ *         Story.Step([Text.Root("Orders climbed steadily from week 6.")],
+ *             { id: "demand", eyebrow: "Demand", title: "Demand ran hot",
+ *               stage: Text.Root("kf 1") }),
+ *         Story.Step([Text.Root("The committed forecast kept its old slope.")],
+ *             { id: "forecast", eyebrow: "Forecast", title: "The plan missed the turn",
+ *               stage: Text.Root("kf 2") }),
+ *     ], { title: "Q4 demand review", stageHeight: 420, stepLength: "default" }),
+ * );
+ * ```
+ */
+function createStoryRoot(steps, options) {
+    const { active, progress, activeStep, title, onStepEnter, onStepExit, ...visual } = options ?? {};
+    const hasVisual = Object.values(visual).some(field => field !== undefined);
+    const styleValue = hasVisual ? buildStoryStyle(visual) : undefined;
+    return East.value(variant("Story", {
+        steps: steps,
+        active: active !== undefined ? some(active) : none,
+        progress: progress !== undefined ? some(progress) : none,
+        activeStep: activeStep !== undefined ? some(activeStep) : none,
+        title: title !== undefined ? some(title) : none,
+        onStepEnter: onStepEnter ? some(onStepEnter) : none,
+        onStepExit: onStepExit ? some(onStepExit) : none,
+        style: styleValue ? some(styleValue) : none,
+    }), UIComponentType);
+}
+function buildStoryStyle(style) {
+    const layoutValue = style.layout
+        ? (typeof style.layout === "string"
+            ? East.value(variant(style.layout, null), StoryLayoutType)
+            : style.layout)
+        : undefined;
+    const stepLengthValue = style.stepLength
+        ? (typeof style.stepLength === "string"
+            ? East.value(variant(style.stepLength, null), StoryStepLengthType)
+            : style.stepLength)
+        : undefined;
+    const stageHeightValue = style.stageHeight !== undefined
+        ? (typeof style.stageHeight === "number"
+            ? `${Math.round(style.stageHeight)}px`
+            : style.stageHeight)
+        : undefined;
+    const heightValue = style.height !== undefined
+        ? (typeof style.height === "number"
+            ? `${Math.round(style.height)}px`
+            : style.height)
+        : undefined;
+    return East.value({
+        layout: layoutValue ? some(layoutValue) : none,
+        stageHeight: stageHeightValue !== undefined ? some(stageHeightValue) : none,
+        stepLength: stepLengthValue ? some(stepLengthValue) : none,
+        height: heightValue !== undefined ? some(heightValue) : none,
+    }, StoryStyleType);
+}
+// ============================================================================
+// Story Progress Factory
+// ============================================================================
+/**
+ * Creates the Story.Progress chrome strip: eyebrow title · per-step dots ·
+ * counter · prev/next.
+ *
+ * @param options - `count` (required) plus the `active` binding and `title`
+ * @returns An East expression representing the StoryProgress component
+ *
+ * @remarks
+ * Mounts standalone anywhere because it shares nothing with the Story but
+ * the binding: dots and prev/next simply write `active`, and the Story's
+ * rail treats the write as navigation. Inside `Story.Root` the chrome is
+ * rendered automatically when the story's `title` option is set.
+ *
+ * @example
+ * ```ts
+ * import { East } from "@elaraai/east";
+ * import { Story, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const chrome = East.function([], UIComponentType, _$ =>
+ *     Story.Progress({ count: 4, title: "Q4 demand review" }),
+ * );
+ * ```
+ */
+function createStoryProgress(options) {
+    const countValue = typeof options.count === "number"
+        ? BigInt(Math.round(options.count))
+        : options.count;
+    return East.value(variant("StoryProgress", {
+        count: countValue,
+        active: options.active !== undefined ? some(options.active) : none,
+        title: options.title !== undefined ? some(options.title) : none,
+    }), UIComponentType);
+}
+// ============================================================================
+// Story Compound Namespace
+// ============================================================================
+/**
+ * Story compound primitive for scroll-driven narratives — one persistent
+ * visual (the stage) evolving through keyframes while prose steps scroll
+ * past in a rail beside it. The reader's scrollbar is the timeline.
+ *
+ * @remarks
+ * Use `Story.Root(steps, options)` for the container, `Story.Step(body,
+ * { id, … })` for each beat, and `Story.Progress(options)` for standalone
+ * chrome. Reach for Story only when the *sequence* of readings carries the
+ * argument; random-access beats are Tabs, equal-weight siblings with no
+ * shared visual are a Carousel.
+ */
+export const Story = {
+    /**
+     * Creates a Story container.
+     *
+     * @param steps - The narrative beats, built with `Story.Step`
+     * @param options - State + behaviour + visual style fields
+     * @returns An East expression representing the Story component
+     *
+     * @remarks
+     * See {@link createStoryRoot} for full semantics. `active` / `progress`
+     * / `activeStep` (state) and `onStepEnter` / `onStepExit` (behaviour)
+     * sit alongside the visual style fields in one flat bag.
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Story, Text, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const ex = East.function([], UIComponentType, _$ =>
+     *     Story.Root([
+     *         Story.Step([Text.Root("Beat one.")], { id: "one", title: "One" }),
+     *         Story.Step([Text.Root("Beat two.")], { id: "two", title: "Two" }),
+     *     ], { stageHeight: 420 }),
+     * );
+     * ```
+     */
+    Root: createStoryRoot,
+    /**
+     * Creates a Story step.
+     *
+     * @param body - Rail content (any east-ui subtree)
+     * @param options - `id` (required) plus `eyebrow` / `title` / `stage`
+     * @returns An East expression representing the StoryStep component
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Story, Text, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const ex = East.function([], UIComponentType, _$ =>
+     *     Story.Step([Text.Root("Orders climbed steadily.")],
+     *         { id: "demand", eyebrow: "Demand", title: "Demand ran hot" }),
+     * );
+     * ```
+     */
+    Step: createStoryStep,
+    /**
+     * Creates the standalone Story.Progress chrome strip.
+     *
+     * @param options - `count` (required) plus `active` binding and `title`
+     * @returns An East expression representing the StoryProgress component
+     *
+     * @example
+     * ```ts
+     * import { East } from "@elaraai/east";
+     * import { Story, UIComponentType } from "@elaraai/east-ui";
+     *
+     * const ex = East.function([], UIComponentType, _$ =>
+     *     Story.Progress({ count: 4, title: "Q4 demand review" }),
+     * );
+     * ```
+     */
+    Progress: createStoryProgress,
+    /**
+     * Helper for creating story layout values.
+     *
+     * @param v - The layout string
+     * @returns An East expression representing the layout
+     */
+    Layout: StoryLayout,
+    Types: {
+        /**
+         * The concrete East type for the Story container — mirrors the
+         * inline `Story` variant in `component.ts`.
+         */
+        Story: StoryType,
+        /**
+         * The concrete East type for a Story step.
+         */
+        Step: StoryStepType,
+        /**
+         * The concrete East type for the Story.Progress chrome.
+         */
+        Progress: StoryProgressType,
+        /**
+         * Visual-only style struct for Story. See {@link StoryStyleType}.
+         */
+        Style: StoryStyleType,
+        /**
+         * Layout enum (rail-left / rail-right / stacked).
+         */
+        Layout: StoryLayoutType,
+        /**
+         * Step runway enum (compact / default / long).
+         */
+        StepLength: StoryStepLengthType,
+        /**
+         * Narrative-position binding struct (Integer read/write closures).
+         */
+        ActiveBinding: StoryActiveBindingType,
+        /**
+         * Within-step scrub binding struct (Float read/write closures).
+         */
+        ProgressBinding: StoryProgressBindingType,
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/src/disclosure/story/index.js.map

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

package/dist/src/disclosure/story/types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { type ExprType, type SubtypeExprOrValue, BooleanType, FloatType, FunctionType, IntegerType, NullType, OptionType, StringType, StructType, VariantType } from "@elaraai/east";
+/**
+ * Layout options for Story (design/story.html §Story.Root Layouts).
+ *
+ * @remarks
+ * `stacked` is also forced automatically below 720px container width: the
+ * stage compresses to `min(stageHeight, 280px)`, sticks to the top, and the
+ * prose scrolls beneath it full-width. There is no overlay layout — text
+ * never floats over the visual.
+ *
+ * @property rail-left - Prose rail left, stage right (default; reading order matches scan order)
+ * @property rail-right - Mirror image; for pages whose surrounding chrome already sits left
+ * @property stacked - Stage on top, prose beneath (forced under 720px)
+ */
+export declare const StoryLayoutType: VariantType<{
+    readonly "rail-left": NullType;
+    readonly "rail-right": NullType;
+    readonly stacked: NullType;
+}>;
+/**
+ * Type representing the StoryLayout structure.
+ */
+export type StoryLayoutType = typeof StoryLayoutType;
+/**
+ * String literal type for story layout values.
+ */
+export type StoryLayoutLiteral = "rail-left" | "rail-right" | "stacked";
+/**
+ * Helper function to create story layout values.
+ *
+ * @param v - The layout string
+ * @returns An East expression representing the story layout
+ */
+export declare function StoryLayout(v: StoryLayoutLiteral): ExprType<StoryLayoutType>;
+/**
+ * Step runway presets — the scroll distance the reader travels per keyframe
+ * (design/story.html §Story.Root Dimensions).
+ *
+ * @property compact - 36vh per step
+ * @property default - 52vh per step
+ * @property long - 72vh per step
+ */
+export declare const StoryStepLengthType: VariantType<{
+    readonly compact: NullType;
+    readonly default: NullType;
+    readonly long: NullType;
+}>;
+/**
+ * Type representing the StoryStepLength structure.
+ */
+export type StoryStepLengthType = typeof StoryStepLengthType;
+/**
+ * String literal type for story step length values.
+ */
+export type StoryStepLengthLiteral = "compact" | "default" | "long";
+/**
+ * Helper function to create story step length values.
+ *
+ * @param v - The step length string
+ * @returns An East expression representing the step length
+ */
+export declare function StoryStepLength(v: StoryStepLengthLiteral): ExprType<StoryStepLengthType>;
+/**
+ * The narrative-position binding: Integer read/write closures, the exact
+ * struct `State.bind([IntegerType], key, default)` produces — bindings pass
+ * straight through, no adapter (design/story.html §Wiring).
+ *
+ * @remarks
+ * The scroll driver writes it as steps cross the trigger line; an external
+ * write is treated as navigation — the rail smooth-scrolls that step to the
+ * trigger line, then resumes observing. Anything exposing these closures
+ * works; there is no bespoke handle type.
+ *
+ * @property read - Returns the active step index
+ * @property write - Sets the active step index (navigation when external)
+ * @property has - True when the underlying state key exists
+ */
+export declare const StoryActiveBindingType: StructType<{
+    readonly read: FunctionType<[], IntegerType>;
+    readonly write: FunctionType<[IntegerType], NullType>;
+    readonly has: FunctionType<[], BooleanType>;
+}>;
+/**
+ * Type representing the StoryActiveBinding structure.
+ */
+export type StoryActiveBindingType = typeof StoryActiveBindingType;
+/**
+ * The within-step scrub binding: Float read/write closures over progress
+ * ∈ [0, 1] through the active step, the exact struct
+ * `State.bind([FloatType], key, default)` produces.
+ *
+ * @remarks
+ * Written by the scroll driver only; consumers read it (inside `Reactive`)
+ * for scroll-locked effects and never write it. Scrub maps 1:1 to scroll —
+ * no easing, no duration.
+ *
+ * @property read - Returns progress through the active step (0–1)
+ * @property write - Sets the progress (scroll driver only)
+ * @property has - True when the underlying state key exists
+ */
+export declare const StoryProgressBindingType: StructType<{
+    readonly read: FunctionType<[], FloatType>;
+    readonly write: FunctionType<[FloatType], NullType>;
+    readonly has: FunctionType<[], BooleanType>;
+}>;
+/**
+ * Type representing the StoryProgressBinding structure.
+ */
+export type StoryProgressBindingType = typeof StoryProgressBindingType;
+/**
+ * Visual-only style struct for Story. Content (`steps`), state (`active` /
+ * `progress` / `activeStep`), and behaviour (`onStepEnter` / `onStepExit`)
+ * live on the main `Story` variant (inline in `component.ts` because steps
+ * are recursive `node` children).
+ *
+ * @property layout - Rail placement (rail-left / rail-right / stacked)
+ * @property stageHeight - Stage height as a CSS length (default "420px") —
+ *   fixed per story so keyframe tweens never reflow the page
+ * @property stepLength - Step runway preset (compact / default / long)
+ * @property height - Scrollport height as a CSS length. When set, the
+ *   story owns an internal scroll container (the spec demo's `.story-demo`
+ *   form) — use it for embeds whose ancestors break sticky (cards,
+ *   overflow-clipped frames, showcases). When omitted the story rides the
+ *   native page scroll, the default for report pages.
+ */
+export declare const StoryStyleType: StructType<{
+    readonly layout: OptionType<VariantType<{
+        readonly "rail-left": NullType;
+        readonly "rail-right": NullType;
+        readonly stacked: NullType;
+    }>>;
+    readonly stageHeight: OptionType<StringType>;
+    readonly stepLength: OptionType<VariantType<{
+        readonly compact: NullType;
+        readonly default: NullType;
+        readonly long: NullType;
+    }>>;
+    readonly height: OptionType<StringType>;
+}>;
+/**
+ * Type representing the Story visual-style structure.
+ */
+export type StoryStyleType = typeof StoryStyleType;
+/**
+ * TypeScript options bag for Story's `style` sub-struct — visual props only.
+ *
+ * @remarks
+ * State (`active` / `progress` / `activeStep`) and behaviour
+ * (`onStepEnter` / `onStepExit`) live on the main options object passed to
+ * `Story.Root`, not here.
+ */
+export interface StoryStyle {
+    /** Rail placement (rail-left / rail-right / stacked) */
+    layout?: SubtypeExprOrValue<StoryLayoutType> | StoryLayoutLiteral;
+    /** Stage height as a CSS length ("420px", "50vh"); bare numbers are px */
+    stageHeight?: SubtypeExprOrValue<StringType> | number;
+    /** Step runway preset (compact / default / long) */
+    stepLength?: SubtypeExprOrValue<StoryStepLengthType> | StoryStepLengthLiteral;
+    /** Scrollport height as a CSS length ("520px", "70vh", "100%"); bare
+     *  numbers are px. When set the story owns an internal scroll container
+     *  (spec demo form); omit to ride the page scroll */
+    height?: SubtypeExprOrValue<StringType> | number;
+}
+/**
+ * TypeScript options bag for `Story.Progress`.
+ *
+ * @property count - Total number of steps shown by the dots / counter
+ * @property active - Narrative-position binding (`State.bind` struct) shared
+ *   with the Story it narrates
+ * @property title - Eyebrow title at the left of the chrome row
+ */
+export interface StoryProgressOptions {
+    /** Total number of steps shown by the dots / counter */
+    count: SubtypeExprOrValue<IntegerType> | number;
+    /** Narrative-position binding shared with the Story */
+    active?: SubtypeExprOrValue<StoryActiveBindingType>;
+    /** Eyebrow title at the left of the chrome row */
+    title?: SubtypeExprOrValue<StringType>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/disclosure/story/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/disclosure/story/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,WAAW,EACX,SAAS,EACT,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EAEd,MAAM,eAAe,CAAC;AAMvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe;;;;EAI1B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,YAAY,GAAG,SAAS,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAAC,eAAe,CAAC,CAE5E;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;;;;EAI9B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAEpE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,sBAAsB,GAAG,QAAQ,CAAC,mBAAmB,CAAC,CAExF;AAMD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB;;;;EAIjC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC;AAEnE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB;;;;EAInC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,wBAAwB,CAAC;AAMvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;EAKzB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAMnD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACvB,wDAAwD;IACxD,MAAM,CAAC,EAAE,kBAAkB,CAAC,eAAe,CAAC,GAAG,kBAAkB,CAAC;IAClE,0EAA0E;IAC1E,WAAW,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;IACtD,oDAAoD;IACpD,UAAU,CAAC,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,GAAG,sBAAsB,CAAC;IAC9E;;yDAEqD;IACrD,MAAM,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACjC,wDAAwD;IACxD,KAAK,EAAE,kBAAkB,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;IAChD,uDAAuD;IACvD,MAAM,CAAC,EAAE,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;IACpD,kDAAkD;IAClD,KAAK,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;CAC1C"}