@hjmds/design-contracts 0.8.2

package/dist/slider.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Slider always has a value — there is no `empty` axis to model, unlike a
+ * NumberField that can start unset. Range selection (two handles) is out of
+ * scope until a real product needs it; adding it speculatively would mean
+ * guessing at a value-pair contract nobody has validated.
+ */
+export type SliderDescriptor = Readonly<{
+    /** Visible or accessibility label; announced before the value. */
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    /**
+     * Product-formatted copy overriding the raw numeric announcement, e.g.
+     * "75점" or ".357". Slider never formats numbers itself.
+     */
+    valueText?: string;
+}>;
+export type ResolvedSliderDescriptor = Omit<SliderDescriptor, "step"> & Readonly<{
+    step: number;
+}>;
+export declare function validateSliderDescriptor(descriptor: SliderDescriptor): void;
+export declare function resolveSliderDescriptor(descriptor: SliderDescriptor): ResolvedSliderDescriptor;
+/** 0..1 position of `value` between `min` and `max`, for track fill — not a display string. */
+export declare function resolveSliderFillFraction(descriptor: SliderDescriptor): number;
+/**
+ * Snaps user-originated input with NumberField's min-origin range math while
+ * preserving Slider's exact endpoints. Public controlled values may be
+ * off-grid; they remain untouched until a user interaction proposes a value.
+ */
+export declare function resolveSliderValue(descriptor: SliderDescriptor, candidate: number): number;
+export type SliderDirection = "ltr" | "rtl";
+/**
+ * Maps a pointer/touch offset to a min-origin step. RTL mirrors the physical
+ * track while preserving the logical meaning of increment/decrement.
+ */
+export declare function resolveSliderValueFromOffset(descriptor: SliderDescriptor, offset: number, extent: number, direction: SliderDirection): number;
+export type SliderStepIntent = "increment" | "decrement" | "increment-page" | "decrement-page" | "first" | "last";
+export declare const sliderBehaviorDefaults: {
+    readonly pageMultiplier: 10;
+};
+/**
+ * One function for every keyboard/RN step intent so Web arrow/Home/End/
+ * PageUp/PageDown and RN increment/decrement actions resolve through the same
+ * snap-and-clamp judgment as the stepper itself.
+ */
+export declare function getSliderStepTarget(descriptor: SliderDescriptor, intent: SliderStepIntent): number;
+export type SliderSize = "medium";
+export declare const sliderRecipe: {
+    readonly slots: readonly ["root", "track", "filledTrack", "thumb", "label", "valueLabel"];
+    readonly defaults: {
+        readonly size: "medium";
+    };
+    readonly sizes: {
+        readonly medium: {
+            readonly trackHeight: 4;
+            readonly thumbDiameter: 20;
+            readonly hitTarget: 44;
+            readonly labelVariant: "body";
+            readonly valueLabelVariant: "label";
+        };
+    };
+    readonly colors: {
+        readonly trackFilled: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly trackUnfilled: Readonly<{
+            source: "theme";
+            key: "surfaceAlt";
+            alpha?: number;
+        }>;
+        readonly trackUnfilledBorder: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly thumb: Readonly<{
+            source: "theme";
+            key: "bg";
+            alpha?: number;
+        }>;
+        readonly thumbBorder: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly label: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly valueLabel: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly disabledOpacity: 0.5;
+        readonly draggedOpacity: 0.64;
+    };
+    readonly radius: "full";
+};
+export declare const sliderBehavior: {
+    readonly controlled: readonly ["value", "defaultValue", "onValueChange"];
+    readonly events: readonly ["onValueChangeEnd"];
+    readonly defaults: {
+        readonly pageMultiplier: 10;
+    };
+    readonly stateAxes: {
+        readonly interaction: readonly ["idle", "hover", "focusVisible", "pressed", "dragged"];
+        readonly availability: readonly ["enabled", "disabled"];
+    };
+    readonly web: {
+        readonly roles: readonly ["slider"];
+        readonly keyboard: readonly ["Tab", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End", "PageUp", "PageDown"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["adjustable"];
+        readonly states: readonly ["disabled"];
+        readonly actions: readonly ["increment", "decrement"];
+    };
+    readonly scenarios: readonly ["label-then-value-then-range-announcement-order", "arrow-keys-step-by-one-increment", "page-keys-step-by-the-page-multiplier", "home-and-end-jump-to-min-and-max", "rtl-mirrors-the-track-without-reversing-logical-increment-actions", "continuous-change-and-interaction-end-are-separate-events", "non-divisible-ranges-preserve-exact-min-and-max-endpoints", "native-disable-during-drag-finishes-once-and-ignores-later-moves", "value-is-always-present-no-empty-state", "fill-color-is-never-the-only-value-cue", "range-two-handle-selection-is-out-of-scope-until-a-real-product-need-exists"];
+};
+//# sourceMappingURL=slider.d.ts.map

package/dist/slider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slider.d.ts","sourceRoot":"","sources":["../src/slider.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GACnE,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAQ7B,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAU3E;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,gBAAgB,GAC3B,wBAAwB,CAG1B;AAED,+FAA+F;AAC/F,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAG9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,gBAAgB,EAC5B,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR;AAED,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,KAAK,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,eAAe,GACzB,MAAM,CAWR;AAED,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,gBAAgB,GAChB,OAAO,GACP,MAAM,CAAC;AAEX,eAAO,MAAM,sBAAsB;;CAEsB,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,gBAAgB,GACvB,MAAM,CAcR;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;AAElC,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDxB,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;CAyCU,CAAC"}

package/dist/slider.js

@@ -0,0 +1,150 @@
+import { focusIndicatorContract } from "./component-contracts.js";
+import { control, opacity } from "./foundations.js";
+import { assertFiniteNumber, numericRangeDefaults, snapToStep, stepNumericValue, validateNumericRangeConfig, } from "./number-field.js";
+import { semanticColors } from "./semantic-colors.js";
+function assertNonEmptyCopy(value, field) {
+    if (value.trim().length === 0) {
+        throw new TypeError(`Slider ${field} must not be empty`);
+    }
+}
+export function validateSliderDescriptor(descriptor) {
+    assertNonEmptyCopy(descriptor.label, "label");
+    validateNumericRangeConfig(descriptor);
+    assertFiniteNumber(descriptor.value, "value");
+    if (descriptor.value < descriptor.min || descriptor.value > descriptor.max) {
+        throw new RangeError("Slider value must be within min and max");
+    }
+    if (descriptor.valueText !== undefined) {
+        assertNonEmptyCopy(descriptor.valueText, "valueText");
+    }
+}
+export function resolveSliderDescriptor(descriptor) {
+    validateSliderDescriptor(descriptor);
+    return { ...descriptor, step: descriptor.step ?? numericRangeDefaults.step };
+}
+/** 0..1 position of `value` between `min` and `max`, for track fill — not a display string. */
+export function resolveSliderFillFraction(descriptor) {
+    validateSliderDescriptor(descriptor);
+    return (descriptor.value - descriptor.min) / (descriptor.max - descriptor.min);
+}
+/**
+ * Snaps user-originated input with NumberField's min-origin range math while
+ * preserving Slider's exact endpoints. Public controlled values may be
+ * off-grid; they remain untouched until a user interaction proposes a value.
+ */
+export function resolveSliderValue(descriptor, candidate) {
+    validateSliderDescriptor(descriptor);
+    assertFiniteNumber(candidate, "candidate");
+    if (candidate <= descriptor.min)
+        return descriptor.min;
+    if (candidate >= descriptor.max)
+        return descriptor.max;
+    return snapToStep(candidate, descriptor);
+}
+/**
+ * Maps a pointer/touch offset to a min-origin step. RTL mirrors the physical
+ * track while preserving the logical meaning of increment/decrement.
+ */
+export function resolveSliderValueFromOffset(descriptor, offset, extent, direction) {
+    validateSliderDescriptor(descriptor);
+    assertFiniteNumber(offset, "offset");
+    assertFiniteNumber(extent, "extent");
+    if (extent <= 0)
+        throw new RangeError("Slider extent must be greater than 0");
+    const physicalFraction = Math.min(1, Math.max(0, offset / extent));
+    const logicalFraction = direction === "rtl" ? 1 - physicalFraction : physicalFraction;
+    return resolveSliderValue(descriptor, descriptor.min + logicalFraction * (descriptor.max - descriptor.min));
+}
+export const sliderBehaviorDefaults = {
+    pageMultiplier: 10,
+};
+/**
+ * One function for every keyboard/RN step intent so Web arrow/Home/End/
+ * PageUp/PageDown and RN increment/decrement actions resolve through the same
+ * snap-and-clamp judgment as the stepper itself.
+ */
+export function getSliderStepTarget(descriptor, intent) {
+    validateSliderDescriptor(descriptor);
+    if (intent === "first")
+        return descriptor.min;
+    if (intent === "last")
+        return descriptor.max;
+    const step = descriptor.step ?? numericRangeDefaults.step;
+    const config = { min: descriptor.min, max: descriptor.max, step };
+    if (intent === "increment" || intent === "decrement") {
+        return stepNumericValue(descriptor.value, config, intent);
+    }
+    const direction = intent === "increment-page" ? 1 : -1;
+    return resolveSliderValue(descriptor, descriptor.value + direction * step * sliderBehaviorDefaults.pageMultiplier);
+}
+export const sliderRecipe = {
+    slots: ["root", "track", "filledTrack", "thumb", "label", "valueLabel"],
+    defaults: { size: "medium" },
+    sizes: {
+        medium: {
+            trackHeight: 4,
+            thumbDiameter: 20,
+            hitTarget: control.minTouchTarget,
+            labelVariant: "body",
+            valueLabelVariant: "label",
+        },
+    },
+    colors: {
+        trackFilled: semanticColors.content.brand,
+        trackUnfilled: semanticColors.surface.sunken,
+        trackUnfilledBorder: semanticColors.content.secondary,
+        thumb: semanticColors.canvas,
+        thumbBorder: semanticColors.border.focus,
+        label: semanticColors.content.body,
+        valueLabel: semanticColors.content.secondary,
+    },
+    states: {
+        focus: focusIndicatorContract,
+        disabledOpacity: opacity.disabled,
+        draggedOpacity: opacity.dragged,
+    },
+    radius: "full",
+};
+export const sliderBehavior = {
+    controlled: ["value", "defaultValue", "onValueChange"],
+    events: ["onValueChangeEnd"],
+    defaults: sliderBehaviorDefaults,
+    stateAxes: {
+        interaction: ["idle", "hover", "focusVisible", "pressed", "dragged"],
+        availability: ["enabled", "disabled"],
+    },
+    web: {
+        roles: ["slider"],
+        keyboard: [
+            "Tab",
+            "ArrowLeft",
+            "ArrowRight",
+            "ArrowUp",
+            "ArrowDown",
+            "Home",
+            "End",
+            "PageUp",
+            "PageDown",
+        ],
+        focus: "native",
+    },
+    native: {
+        roles: ["adjustable"],
+        states: ["disabled"],
+        actions: ["increment", "decrement"],
+    },
+    scenarios: [
+        "label-then-value-then-range-announcement-order",
+        "arrow-keys-step-by-one-increment",
+        "page-keys-step-by-the-page-multiplier",
+        "home-and-end-jump-to-min-and-max",
+        "rtl-mirrors-the-track-without-reversing-logical-increment-actions",
+        "continuous-change-and-interaction-end-are-separate-events",
+        "non-divisible-ranges-preserve-exact-min-and-max-endpoints",
+        "native-disable-during-drag-finishes-once-and-ignores-later-moves",
+        "value-is-always-present-no-empty-state",
+        "fill-color-is-never-the-only-value-cue",
+        "range-two-handle-selection-is-out-of-scope-until-a-real-product-need-exists",
+    ],
+};
+//# sourceMappingURL=slider.js.map

package/dist/slider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slider.js","sourceRoot":"","sources":["../src/slider.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { BehaviorContract } from \"./behaviors.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport { control, opacity, type TextVariant } from \"./foundations.js\";\nimport {\n  assertFiniteNumber,\n  numericRangeDefaults,\n  snapToStep,\n  stepNumericValue,\n  validateNumericRangeConfig,\n  type NumericRangeConfig,\n} from \"./number-field.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Slider always has a value — there is no `empty` axis to model, unlike a\n * NumberField that can start unset. Range selection (two handles) is out of\n * scope until a real product needs it; adding it speculatively would mean\n * guessing at a value-pair contract nobody has validated.\n */\nexport type SliderDescriptor = Readonly<{\n  /** Visible or accessibility label; announced before the value. */\n  label: string;\n  value: number;\n  min: number;\n  max: number;\n  step?: number;\n  /**\n   * Product-formatted copy overriding the raw numeric announcement, e.g.\n   * \"75점\" or \".357\". Slider never formats numbers itself.\n   */\n  valueText?: string;\n}>;\n\nexport type ResolvedSliderDescriptor = Omit<SliderDescriptor, \"step\"> &\n  Readonly<{ step: number }>;\n\nfunction assertNonEmptyCopy(value: string, field: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`Slider ${field} must not be empty`);\n  }\n}\n\nexport function validateSliderDescriptor(descriptor: SliderDescriptor): void {\n  assertNonEmptyCopy(descriptor.label, \"label\");\n  validateNumericRangeConfig(descriptor);\n  assertFiniteNumber(descriptor.value, \"value\");\n  if (descriptor.value < descriptor.min || descriptor.value > descriptor.max) {\n    throw new RangeError(\"Slider value must be within min and max\");\n  }\n  if (descriptor.valueText !== undefined) {\n    assertNonEmptyCopy(descriptor.valueText, \"valueText\");\n  }\n}\n\nexport function resolveSliderDescriptor(\n  descriptor: SliderDescriptor,\n): ResolvedSliderDescriptor {\n  validateSliderDescriptor(descriptor);\n  return { ...descriptor, step: descriptor.step ?? numericRangeDefaults.step };\n}\n\n/** 0..1 position of `value` between `min` and `max`, for track fill — not a display string. */\nexport function resolveSliderFillFraction(descriptor: SliderDescriptor): number {\n  validateSliderDescriptor(descriptor);\n  return (descriptor.value - descriptor.min) / (descriptor.max - descriptor.min);\n}\n\n/**\n * Snaps user-originated input with NumberField's min-origin range math while\n * preserving Slider's exact endpoints. Public controlled values may be\n * off-grid; they remain untouched until a user interaction proposes a value.\n */\nexport function resolveSliderValue(\n  descriptor: SliderDescriptor,\n  candidate: number,\n): number {\n  validateSliderDescriptor(descriptor);\n  assertFiniteNumber(candidate, \"candidate\");\n  if (candidate <= descriptor.min) return descriptor.min;\n  if (candidate >= descriptor.max) return descriptor.max;\n  return snapToStep(candidate, descriptor);\n}\n\nexport type SliderDirection = \"ltr\" | \"rtl\";\n\n/**\n * Maps a pointer/touch offset to a min-origin step. RTL mirrors the physical\n * track while preserving the logical meaning of increment/decrement.\n */\nexport function resolveSliderValueFromOffset(\n  descriptor: SliderDescriptor,\n  offset: number,\n  extent: number,\n  direction: SliderDirection,\n): number {\n  validateSliderDescriptor(descriptor);\n  assertFiniteNumber(offset, \"offset\");\n  assertFiniteNumber(extent, \"extent\");\n  if (extent <= 0) throw new RangeError(\"Slider extent must be greater than 0\");\n  const physicalFraction = Math.min(1, Math.max(0, offset / extent));\n  const logicalFraction = direction === \"rtl\" ? 1 - physicalFraction : physicalFraction;\n  return resolveSliderValue(\n    descriptor,\n    descriptor.min + logicalFraction * (descriptor.max - descriptor.min),\n  );\n}\n\nexport type SliderStepIntent =\n  | \"increment\"\n  | \"decrement\"\n  | \"increment-page\"\n  | \"decrement-page\"\n  | \"first\"\n  | \"last\";\n\nexport const sliderBehaviorDefaults = {\n  pageMultiplier: 10,\n} as const satisfies Readonly<{ pageMultiplier: number }>;\n\n/**\n * One function for every keyboard/RN step intent so Web arrow/Home/End/\n * PageUp/PageDown and RN increment/decrement actions resolve through the same\n * snap-and-clamp judgment as the stepper itself.\n */\nexport function getSliderStepTarget(\n  descriptor: SliderDescriptor,\n  intent: SliderStepIntent,\n): number {\n  validateSliderDescriptor(descriptor);\n  if (intent === \"first\") return descriptor.min;\n  if (intent === \"last\") return descriptor.max;\n  const step = descriptor.step ?? numericRangeDefaults.step;\n  const config: NumericRangeConfig = { min: descriptor.min, max: descriptor.max, step };\n  if (intent === \"increment\" || intent === \"decrement\") {\n    return stepNumericValue(descriptor.value, config, intent);\n  }\n  const direction = intent === \"increment-page\" ? 1 : -1;\n  return resolveSliderValue(\n    descriptor,\n    descriptor.value + direction * step * sliderBehaviorDefaults.pageMultiplier,\n  );\n}\n\nexport type SliderSize = \"medium\";\n\nexport const sliderRecipe = {\n  slots: [\"root\", \"track\", \"filledTrack\", \"thumb\", \"label\", \"valueLabel\"] as const,\n  defaults: { size: \"medium\" },\n  sizes: {\n    medium: {\n      trackHeight: 4,\n      thumbDiameter: 20,\n      hitTarget: control.minTouchTarget,\n      labelVariant: \"body\",\n      valueLabelVariant: \"label\",\n    },\n  },\n  colors: {\n    trackFilled: semanticColors.content.brand,\n    trackUnfilled: semanticColors.surface.sunken,\n    trackUnfilledBorder: semanticColors.content.secondary,\n    thumb: semanticColors.canvas,\n    thumbBorder: semanticColors.border.focus,\n    label: semanticColors.content.body,\n    valueLabel: semanticColors.content.secondary,\n  },\n  states: {\n    focus: focusIndicatorContract,\n    disabledOpacity: opacity.disabled,\n    draggedOpacity: opacity.dragged,\n  },\n  radius: \"full\",\n} as const satisfies {\n  slots: readonly [\"root\", \"track\", \"filledTrack\", \"thumb\", \"label\", \"valueLabel\"];\n  defaults: { size: SliderSize };\n  sizes: Record<\n    SliderSize,\n    {\n      trackHeight: number;\n      thumbDiameter: number;\n      hitTarget: number;\n      labelVariant: TextVariant;\n      valueLabelVariant: TextVariant;\n    }\n  >;\n  colors: {\n    trackFilled: ColorReference;\n    trackUnfilled: ColorReference;\n    trackUnfilledBorder: ColorReference;\n    thumb: ColorReference;\n    thumbBorder: ColorReference;\n    label: ColorReference;\n    valueLabel: ColorReference;\n  };\n  states: {\n    focus: typeof focusIndicatorContract;\n    disabledOpacity: number;\n    draggedOpacity: number;\n  };\n  radius: \"full\";\n};\n\nexport const sliderBehavior = {\n  controlled: [\"value\", \"defaultValue\", \"onValueChange\"],\n  events: [\"onValueChangeEnd\"],\n  defaults: sliderBehaviorDefaults,\n  stateAxes: {\n    interaction: [\"idle\", \"hover\", \"focusVisible\", \"pressed\", \"dragged\"],\n    availability: [\"enabled\", \"disabled\"],\n  },\n  web: {\n    roles: [\"slider\"],\n    keyboard: [\n      \"Tab\",\n      \"ArrowLeft\",\n      \"ArrowRight\",\n      \"ArrowUp\",\n      \"ArrowDown\",\n      \"Home\",\n      \"End\",\n      \"PageUp\",\n      \"PageDown\",\n    ],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"adjustable\"],\n    states: [\"disabled\"],\n    actions: [\"increment\", \"decrement\"],\n  },\n  scenarios: [\n    \"label-then-value-then-range-announcement-order\",\n    \"arrow-keys-step-by-one-increment\",\n    \"page-keys-step-by-the-page-multiplier\",\n    \"home-and-end-jump-to-min-and-max\",\n    \"rtl-mirrors-the-track-without-reversing-logical-increment-actions\",\n    \"continuous-change-and-interaction-end-are-separate-events\",\n    \"non-divisible-ranges-preserve-exact-min-and-max-endpoints\",\n    \"native-disable-during-drag-finishes-once-and-ignores-later-moves\",\n    \"value-is-always-present-no-empty-state\",\n    \"fill-color-is-never-the-only-value-cue\",\n    \"range-two-handle-selection-is-out-of-scope-until-a-real-product-need-exists\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/splitter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `"horizontal"` means panes sit side by side (the separator is a vertical
+ * bar); `"vertical"` means panes stack top/bottom (the separator is a
+ * horizontal bar). See `resolveSplitterSeparatorOrientation` — the two are
+ * intentionally not spelled the same way to keep that inversion visible.
+ */
+export type SplitterAxis = "horizontal" | "vertical";
+/**
+ * "Pick a number within a range" — the same problem NumberField and Slider
+ * already solve, applied to a pane size instead of a displayed value. This
+ * descriptor reuses `min`/`max`/`step`/`value` verbatim and calls
+ * `src/number-field.ts`'s judgment functions directly rather than
+ * re-deriving clamp/snap/step arithmetic a third time.
+ */
+export type SplitterDescriptor = Readonly<{
+    /** The primary pane's current size, in whatever unit the product chose (fraction or px). */
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    axis?: SplitterAxis;
+    /** Required accessible name for the separator (e.g. "패널 크기 조절"). */
+    label: string;
+    /** Product-formatted announcement of the current size, e.g. "35%" or "320px". */
+    valueText?: string;
+}>;
+export declare const splitterDefaults: {
+    readonly axis: "horizontal";
+};
+export declare function validateSplitterDescriptor(descriptor: SplitterDescriptor): void;
+/**
+ * A WAI-ARIA `separator` reports orientation as the axis the pointer moves
+ * *along*, which is perpendicular to how the panes are arranged — a
+ * side-by-side (`"horizontal"`) splitter has a *vertical* separator bar.
+ * Named and exported so renderers translate this once instead of
+ * re-deriving the inversion at each call site.
+ */
+export declare function resolveSplitterSeparatorOrientation(axis: SplitterAxis): "horizontal" | "vertical";
+/** Keyboard step, reusing NumberField's stepper arithmetic unchanged. */
+export declare function getNextSplitterValue(descriptor: SplitterDescriptor, direction: "increment" | "decrement"): number;
+/** Drag resolution: snaps a raw pointer-derived value to the same step grid keyboard resize uses. */
+export declare function resolveSplitterDragValue(descriptor: SplitterDescriptor, rawValue: number): number;
+/** Boundary jump for Home/End, reusing NumberField's clamp unchanged. */
+export declare function resolveSplitterBoundaryValue(descriptor: SplitterDescriptor, boundary: "min" | "max"): number;
+/**
+ * Reused visual language from Slider: a thin visible line (`thickness`) with
+ * a much larger `hitTarget` — the same "small handle, 44-unit hit area"
+ * split documented in `docs/slider.md`.
+ */
+export declare const splitterRecipe: {
+    readonly slots: readonly ["root", "pane", "separator", "handle"];
+    readonly defaults: {
+        readonly axis: "horizontal";
+    };
+    readonly separator: {
+        readonly thickness: 1;
+        readonly hitTarget: 44;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly hoverColor: Readonly<{
+            source: "theme";
+            key: "textWeak";
+            alpha?: number;
+        }>;
+        readonly activeColor: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+    };
+};
+/**
+ * Deliberately excluded: collapse-to-hidden-pane (antd's collapsible
+ * arrows) and N-pane/multi-separator layouts. Neither has measured product
+ * demand, and both would roughly double this contract's surface (a
+ * collapsed pane needs its own reveal affordance and bypasses `min`; N
+ * panes need an ordered list of separators instead of one value) — the
+ * same reasoning Slider used to leave out two-handle `range` mode.
+ */
+export declare const splitterBehavior: {
+    readonly controlled: readonly ["value", "defaultValue", "onValueChange"];
+    readonly inputs: readonly ["min", "max", "step", "label", "valueText"];
+    readonly stateAxes: {
+        readonly interaction: readonly ["idle", "hover", "focusVisible", "pressed", "dragged"];
+        readonly availability: readonly ["enabled", "disabled"];
+    };
+    readonly web: {
+        readonly roles: readonly ["separator"];
+        readonly keyboard: readonly ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly [];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["separator-role-carries-aria-valuenow-min-max-and-optional-valuetext", "separator-orientation-is-perpendicular-to-the-splitter-axis-not-equal-to-it", "keyboard-arrow-keys-step-like-numberfield-home-and-end-jump-to-the-boundary", "drag-and-keyboard-resize-produce-the-same-snapped-value", "reuses-number-field-range-judgment-instead-of-a-new-numeric-domain", "no-collapse-to-hidden-pane-or-multi-separator-layout-in-this-contract"];
+};
+//# sourceMappingURL=splitter.d.ts.map

package/dist/splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitter.d.ts","sourceRoot":"","sources":["../src/splitter.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,UAAU,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;CAEwB,CAAC;AAQtD,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAc/E;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,YAAY,GACjB,YAAY,GAAG,UAAU,CAE3B;AAED,yEAAyE;AACzE,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,kBAAkB,EAC9B,SAAS,EAAE,WAAW,GAAG,WAAW,GACnC,MAAM,CAGR;AAED,qGAAqG;AACrG,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGjG;AAED,yEAAyE;AACzE,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,KAAK,GAAG,KAAK,GACtB,MAAM,CAGR;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsB1B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;CAqBQ,CAAC"}

package/dist/splitter.js

@@ -0,0 +1,99 @@
+import { focusIndicatorContract } from "./component-contracts.js";
+import { clampToRange, snapToStep, stepNumericValue, validateNumericRangeConfig, } from "./number-field.js";
+import { control } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const splitterDefaults = {
+    axis: "horizontal",
+};
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`Splitter ${field} must not be empty`);
+    }
+}
+export function validateSplitterDescriptor(descriptor) {
+    validateNumericRangeConfig(descriptor);
+    if (descriptor.value < descriptor.min || descriptor.value > descriptor.max) {
+        throw new RangeError("Splitter value must be within min and max");
+    }
+    if (descriptor.axis !== undefined &&
+        descriptor.axis !== "horizontal" &&
+        descriptor.axis !== "vertical") {
+        throw new TypeError(`Unsupported Splitter axis: ${String(descriptor.axis)}`);
+    }
+    assertNonEmpty(descriptor.label, "label");
+    if (descriptor.valueText !== undefined)
+        assertNonEmpty(descriptor.valueText, "valueText");
+}
+/**
+ * A WAI-ARIA `separator` reports orientation as the axis the pointer moves
+ * *along*, which is perpendicular to how the panes are arranged — a
+ * side-by-side (`"horizontal"`) splitter has a *vertical* separator bar.
+ * Named and exported so renderers translate this once instead of
+ * re-deriving the inversion at each call site.
+ */
+export function resolveSplitterSeparatorOrientation(axis) {
+    return axis === "horizontal" ? "vertical" : "horizontal";
+}
+/** Keyboard step, reusing NumberField's stepper arithmetic unchanged. */
+export function getNextSplitterValue(descriptor, direction) {
+    validateSplitterDescriptor(descriptor);
+    return stepNumericValue(descriptor.value, descriptor, direction);
+}
+/** Drag resolution: snaps a raw pointer-derived value to the same step grid keyboard resize uses. */
+export function resolveSplitterDragValue(descriptor, rawValue) {
+    validateSplitterDescriptor(descriptor);
+    return snapToStep(rawValue, descriptor);
+}
+/** Boundary jump for Home/End, reusing NumberField's clamp unchanged. */
+export function resolveSplitterBoundaryValue(descriptor, boundary) {
+    validateSplitterDescriptor(descriptor);
+    return clampToRange(boundary === "min" ? descriptor.min : descriptor.max, descriptor);
+}
+/**
+ * Reused visual language from Slider: a thin visible line (`thickness`) with
+ * a much larger `hitTarget` — the same "small handle, 44-unit hit area"
+ * split documented in `docs/slider.md`.
+ */
+export const splitterRecipe = {
+    slots: ["root", "pane", "separator", "handle"],
+    defaults: { axis: "horizontal" },
+    separator: {
+        thickness: 1,
+        hitTarget: control.minTouchTarget,
+        color: semanticColors.border.default,
+        hoverColor: semanticColors.border.strong,
+        activeColor: semanticColors.border.focus,
+    },
+    states: { focus: focusIndicatorContract },
+};
+/**
+ * Deliberately excluded: collapse-to-hidden-pane (antd's collapsible
+ * arrows) and N-pane/multi-separator layouts. Neither has measured product
+ * demand, and both would roughly double this contract's surface (a
+ * collapsed pane needs its own reveal affordance and bypasses `min`; N
+ * panes need an ordered list of separators instead of one value) — the
+ * same reasoning Slider used to leave out two-handle `range` mode.
+ */
+export const splitterBehavior = {
+    controlled: ["value", "defaultValue", "onValueChange"],
+    inputs: ["min", "max", "step", "label", "valueText"],
+    stateAxes: {
+        interaction: ["idle", "hover", "focusVisible", "pressed", "dragged"],
+        availability: ["enabled", "disabled"],
+    },
+    web: {
+        roles: ["separator"],
+        keyboard: ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"],
+        focus: "native",
+    },
+    native: { roles: [], states: [], actions: [] },
+    scenarios: [
+        "separator-role-carries-aria-valuenow-min-max-and-optional-valuetext",
+        "separator-orientation-is-perpendicular-to-the-splitter-axis-not-equal-to-it",
+        "keyboard-arrow-keys-step-like-numberfield-home-and-end-jump-to-the-boundary",
+        "drag-and-keyboard-resize-produce-the-same-snapped-value",
+        "reuses-number-field-range-judgment-instead-of-a-new-numeric-domain",
+        "no-collapse-to-hidden-pane-or-multi-separator-layout-in-this-contract",
+    ],
+};
+//# sourceMappingURL=splitter.js.map

package/dist/splitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitter.js","sourceRoot":"","sources":["../src/splitter.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { BehaviorContract } from \"./behaviors.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport {\n  clampToRange,\n  snapToStep,\n  stepNumericValue,\n  validateNumericRangeConfig,\n} from \"./number-field.js\";\nimport { control } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * `\"horizontal\"` means panes sit side by side (the separator is a vertical\n * bar); `\"vertical\"` means panes stack top/bottom (the separator is a\n * horizontal bar). See `resolveSplitterSeparatorOrientation` — the two are\n * intentionally not spelled the same way to keep that inversion visible.\n */\nexport type SplitterAxis = \"horizontal\" | \"vertical\";\n\n/**\n * \"Pick a number within a range\" — the same problem NumberField and Slider\n * already solve, applied to a pane size instead of a displayed value. This\n * descriptor reuses `min`/`max`/`step`/`value` verbatim and calls\n * `src/number-field.ts`'s judgment functions directly rather than\n * re-deriving clamp/snap/step arithmetic a third time.\n */\nexport type SplitterDescriptor = Readonly<{\n  /** The primary pane's current size, in whatever unit the product chose (fraction or px). */\n  value: number;\n  min: number;\n  max: number;\n  step?: number;\n  axis?: SplitterAxis;\n  /** Required accessible name for the separator (e.g. \"패널 크기 조절\"). */\n  label: string;\n  /** Product-formatted announcement of the current size, e.g. \"35%\" or \"320px\". */\n  valueText?: string;\n}>;\n\nexport const splitterDefaults = {\n  axis: \"horizontal\",\n} as const satisfies Readonly<{ axis: SplitterAxis }>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`Splitter ${field} must not be empty`);\n  }\n}\n\nexport function validateSplitterDescriptor(descriptor: SplitterDescriptor): void {\n  validateNumericRangeConfig(descriptor);\n  if (descriptor.value < descriptor.min || descriptor.value > descriptor.max) {\n    throw new RangeError(\"Splitter value must be within min and max\");\n  }\n  if (\n    descriptor.axis !== undefined &&\n    descriptor.axis !== \"horizontal\" &&\n    descriptor.axis !== \"vertical\"\n  ) {\n    throw new TypeError(`Unsupported Splitter axis: ${String(descriptor.axis)}`);\n  }\n  assertNonEmpty(descriptor.label, \"label\");\n  if (descriptor.valueText !== undefined) assertNonEmpty(descriptor.valueText, \"valueText\");\n}\n\n/**\n * A WAI-ARIA `separator` reports orientation as the axis the pointer moves\n * *along*, which is perpendicular to how the panes are arranged — a\n * side-by-side (`\"horizontal\"`) splitter has a *vertical* separator bar.\n * Named and exported so renderers translate this once instead of\n * re-deriving the inversion at each call site.\n */\nexport function resolveSplitterSeparatorOrientation(\n  axis: SplitterAxis,\n): \"horizontal\" | \"vertical\" {\n  return axis === \"horizontal\" ? \"vertical\" : \"horizontal\";\n}\n\n/** Keyboard step, reusing NumberField's stepper arithmetic unchanged. */\nexport function getNextSplitterValue(\n  descriptor: SplitterDescriptor,\n  direction: \"increment\" | \"decrement\",\n): number {\n  validateSplitterDescriptor(descriptor);\n  return stepNumericValue(descriptor.value, descriptor, direction);\n}\n\n/** Drag resolution: snaps a raw pointer-derived value to the same step grid keyboard resize uses. */\nexport function resolveSplitterDragValue(descriptor: SplitterDescriptor, rawValue: number): number {\n  validateSplitterDescriptor(descriptor);\n  return snapToStep(rawValue, descriptor);\n}\n\n/** Boundary jump for Home/End, reusing NumberField's clamp unchanged. */\nexport function resolveSplitterBoundaryValue(\n  descriptor: SplitterDescriptor,\n  boundary: \"min\" | \"max\",\n): number {\n  validateSplitterDescriptor(descriptor);\n  return clampToRange(boundary === \"min\" ? descriptor.min : descriptor.max, descriptor);\n}\n\n/**\n * Reused visual language from Slider: a thin visible line (`thickness`) with\n * a much larger `hitTarget` — the same \"small handle, 44-unit hit area\"\n * split documented in `docs/slider.md`.\n */\nexport const splitterRecipe = {\n  slots: [\"root\", \"pane\", \"separator\", \"handle\"] as const,\n  defaults: { axis: \"horizontal\" },\n  separator: {\n    thickness: 1,\n    hitTarget: control.minTouchTarget,\n    color: semanticColors.border.default,\n    hoverColor: semanticColors.border.strong,\n    activeColor: semanticColors.border.focus,\n  },\n  states: { focus: focusIndicatorContract },\n} as const satisfies {\n  slots: readonly [\"root\", \"pane\", \"separator\", \"handle\"];\n  defaults: { axis: SplitterAxis };\n  separator: {\n    thickness: number;\n    hitTarget: number;\n    color: ColorReference;\n    hoverColor: ColorReference;\n    activeColor: ColorReference;\n  };\n  states: { focus: typeof focusIndicatorContract };\n};\n\n/**\n * Deliberately excluded: collapse-to-hidden-pane (antd's collapsible\n * arrows) and N-pane/multi-separator layouts. Neither has measured product\n * demand, and both would roughly double this contract's surface (a\n * collapsed pane needs its own reveal affordance and bypasses `min`; N\n * panes need an ordered list of separators instead of one value) — the\n * same reasoning Slider used to leave out two-handle `range` mode.\n */\nexport const splitterBehavior = {\n  controlled: [\"value\", \"defaultValue\", \"onValueChange\"],\n  inputs: [\"min\", \"max\", \"step\", \"label\", \"valueText\"],\n  stateAxes: {\n    interaction: [\"idle\", \"hover\", \"focusVisible\", \"pressed\", \"dragged\"],\n    availability: [\"enabled\", \"disabled\"],\n  },\n  web: {\n    roles: [\"separator\"],\n    keyboard: [\"ArrowLeft\", \"ArrowRight\", \"ArrowUp\", \"ArrowDown\", \"Home\", \"End\"],\n    focus: \"native\",\n  },\n  native: { roles: [], states: [], actions: [] },\n  scenarios: [\n    \"separator-role-carries-aria-valuenow-min-max-and-optional-valuetext\",\n    \"separator-orientation-is-perpendicular-to-the-splitter-axis-not-equal-to-it\",\n    \"keyboard-arrow-keys-step-like-numberfield-home-and-end-jump-to-the-boundary\",\n    \"drag-and-keyboard-resize-produce-the-same-snapped-value\",\n    \"reuses-number-field-range-judgment-instead-of-a-new-numeric-domain\",\n    \"no-collapse-to-hidden-pane-or-multi-separator-layout-in-this-contract\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/statistic.d.ts

@@ -0,0 +1,41 @@
+export type StatisticTrendDirection = "up" | "down" | "flat";
+export type StatisticTrendTone = "neutral" | "success" | "warning" | "danger";
+export declare const statisticDefaults: {
+    readonly trendTone: "neutral";
+};
+export type StatisticTrendDescriptor = Readonly<{
+    direction: StatisticTrendDirection;
+    /** Direction and meaning are independent: an increase is not always good. */
+    tone?: StatisticTrendTone;
+    /** Visible localized copy ensures the trend is never communicated by color alone. */
+    label: string;
+}>;
+export type StatisticDescriptor<Id extends string = string> = Readonly<{
+    id: Id;
+    label: string;
+    /** Products own number/date/unit formatting and pass the final visible string. */
+    value: string;
+    prefix?: string;
+    suffix?: string;
+    hint?: string;
+    trend?: StatisticTrendDescriptor;
+}>;
+export type StatisticGroupDescriptor<Id extends string = string> = Readonly<{
+    items: readonly StatisticDescriptor<Id>[];
+    columns?: 1 | 2 | 3 | 4;
+}>;
+export type ResolvedStatisticTrendDescriptor = Omit<StatisticTrendDescriptor, "tone"> & Readonly<{
+    tone: StatisticTrendTone;
+}>;
+export type ResolvedStatisticDescriptor<Id extends string = string> = Omit<StatisticDescriptor<Id>, "trend"> & Readonly<{
+    trend?: ResolvedStatisticTrendDescriptor;
+}>;
+export declare function validateStatisticDescriptor<Id extends string>(descriptor: StatisticDescriptor<Id>): void;
+export declare function resolveStatisticDescriptor<Id extends string>(descriptor: StatisticDescriptor<Id>): ResolvedStatisticDescriptor<Id>;
+export declare function validateStatisticGroup<Id extends string>(group: StatisticGroupDescriptor<Id>): void;
+export declare const statisticTrendMarks: {
+    readonly up: "trendUp";
+    readonly down: "trendDown";
+    readonly flat: "trendFlat";
+};
+//# sourceMappingURL=statistic.d.ts.map

package/dist/statistic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statistic.d.ts","sourceRoot":"","sources":["../src/statistic.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAC7D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9E,eAAO,MAAM,iBAAiB;;CAEkC,CAAC;AAEjE,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,SAAS,EAAE,uBAAuB,CAAC;IACnC,6EAA6E;IAC7E,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IACrE,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,wBAAwB,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IAC1E,KAAK,EAAE,SAAS,mBAAmB,CAAC,EAAE,CAAC,EAAE,CAAC;IAC1C,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,MAAM,gCAAgC,GAAG,IAAI,CACjD,wBAAwB,EACxB,MAAM,CACP,GACC,QAAQ,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;AAEzC,MAAM,MAAM,2BAA2B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,IAAI,CACxE,mBAAmB,CAAC,EAAE,CAAC,EACvB,OAAO,CACR,GACC,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,gCAAgC,CAAA;CAAE,CAAC,CAAC;AAQzD,wBAAgB,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAC3D,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,GAClC,IAAI,CAiCN;AAED,wBAAgB,0BAA0B,CAAC,EAAE,SAAS,MAAM,EAC1D,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,GAClC,2BAA2B,CAAC,EAAE,CAAC,CAWjC;AAED,wBAAgB,sBAAsB,CAAC,EAAE,SAAS,MAAM,EACtD,KAAK,EAAE,wBAAwB,CAAC,EAAE,CAAC,GAClC,IAAI,CAqBN;AAED,eAAO,MAAM,mBAAmB;;;;CAI4B,CAAC"}