basalt-ui 1.21.0 → 1.23.0

package/dist/charts/hooks/useBandPlot.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The choreography shared by every BANDED x plot — one slot per datum, drawn as a rect, with no
+ * point in between.
+ *
+ * `CartesianChart` cannot host these: its x scale is `scalePoint` (positions, no width) and it
+ * renders `AxisLeftNumeric` unconditionally. `BandStrip` has no numeric y axis at all and
+ * `MirroredBars` has two, in two independent scales. Both are therefore
+ * `basalt/hand-rolled-plot` shapes — and this module is what stops the second one from being a
+ * copy of the first, per `DualPanel`'s own instruction to "promote the shared choreography rather
+ * than copying this file".
+ *
+ * What lives here: width-driven folding, the measured gutters, the band scale and its
+ * half-bandwidth cursor correction, the shared cursor itself, and the source/follower tooltip
+ * anchor arithmetic. What does NOT: any mark. See `docs/CHARTS-SPEC.md` § "The contract".
+ */
+import { scaleBand } from '@visx/scale';
+import type { ReactNode, RefObject } from 'react';
+import type { ChartMargin } from '../../tokens/index.js';
+import type { CursorResolution } from '../cursor/resolve.js';
+import type { ChartCursor, CursorAnchor } from './useChartCursor.js';
+type BandScale = ReturnType<typeof scaleBand<string>>;
+/**
+ * Collapse adjacent data into one drawn band at widths where one-band-per-datum sub-pixels.
+ *
+ * 288 buckets over a 234px plot is a 0.81px pitch: every band draws at a flat 1px and a single
+ * catastrophic slot can be overdrawn by its neighbour. Folding is the only honest answer — the
+ * alternative is a chart that silently loses its worst column.
+ */
+export type BandFold<T> = {
+    /**
+     * Floor on the px pitch of a drawn band. Default 3 — not 2, because a band also has to be wide
+     * enough for a partial-absence split (`absentFraction`) to render as two visibly distinct
+     * pieces, and at 2px the fill and the hatch antialias into one smudge.
+     */
+    minBandPx?: number;
+    /**
+     * Collapse a group of adjacent source data into the one datum drawn in its place.
+     *
+     * The merge is the CONSUMER's, deliberately: whether a folded slot's value is a max, a sum, or
+     * a rate recomputed from summed parts is a question about the measurement, not about the
+     * chart — and averaging a fully-down bucket into its clean neighbours describes a bucket that
+     * never happened. The kind owns only the arithmetic of how many groups there are.
+     *
+     * Identity (`getX`) MUST come from `group[0]`, or the axis stops being monotone and the cursor
+     * key stops naming a real slot start.
+     */
+    merge: (group: T[]) => T;
+};
+/**
+ * The grouping half of {@link BandFold}, exported so a consumer can test their `merge` against the
+ * arithmetic that will actually run rather than re-implementing it in the test file — the merge is
+ * where the honesty rules live (max vs mean vs a rate recomputed from summed parts), and a test
+ * that groups differently from the kind is testing the wrong function.
+ */
+export declare function foldBands<T>(data: readonly T[], cap: number, merge: (group: T[]) => T): T[];
+/** Tooltip seams shared by `BandStrip` and `MirroredBars` — the `CartesianTooltipConfig` subset
+ * that means anything on a banded plot (there is no per-point `follow` distinction to make that
+ * `CartesianChart` doesn't already document identically). */
+export type BandTooltipConfig<T> = {
+    /** Default true — the tooltip tracks the pointer. `false` anchors it to the crosshair at the
+     * plot's top edge, so a column of charts sharing one cursor lines every tooltip up on one x. */
+    follow?: boolean;
+    /** Right-aligned badge in the tooltip header. */
+    label?: (d: T) => {
+        text: string;
+        color: string;
+    } | null;
+    /** Overrides the header's date text — same seam, same reason, as
+     * `CartesianTooltipConfig.formatHeader`. */
+    formatHeader?: (key: string, d: T) => string;
+    /** Rows rendered BEFORE the derived rows. `hidden` is the same legend-toggle set the marks
+     * draw from, so a hand-authored row cannot desync from it. */
+    prependRows?: (d: T, ctx: BandTooltipRowContext) => ReactNode;
+    /** Rows appended after the derived rows. Same `ctx` as {@link prependRows}. */
+    extraRows?: (d: T, ctx: BandTooltipRowContext) => ReactNode;
+    /**
+     * Render this chart's tooltip when it is a cursor FOLLOWER, not only when it is the SOURCE.
+     * Default false. A follower has no pointer under it, so it always anchors to the crosshair
+     * regardless of `follow`; only the SOURCE is `aria-live`. Costs one `getBoundingClientRect`
+     * per hovered frame per opted-in chart — see `CartesianTooltipConfig.onFollow`.
+     */
+    onFollow?: boolean;
+};
+export type BandTooltipRowContext = {
+    hidden: ReadonlySet<string>;
+};
+export type UseBandPlotInput<T> = {
+    data: readonly T[];
+    chartId: string;
+    getX: (d: T) => string;
+    formatX: (key: string) => string;
+    /** The plot rect's width, as handed down by `ChartFrame`. */
+    width: number;
+    fold?: BandFold<T>;
+    cursorResolution?: CursorResolution;
+    /**
+     * Which of the (possibly folded) keys get a tick. Default `smartTicks`. The seam exists because
+     * `smartTicks` appends the final value unconditionally, which on a dense time axis puts the last
+     * two labels on top of each other — a chart whose x labels are richer than `DD.MM` needs its own
+     * rule.
+     */
+    xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[];
+    /** Left-axis tick labels, already formatted. Empty for a plot with no left axis. */
+    leftLabels?: readonly string[];
+    /** Per-side margin overrides — applied last, so the escape hatch always wins. */
+    margin?: Partial<ChartMargin>;
+    tooltip?: BandTooltipConfig<T> | false;
+};
+export type BandPlot<T> = {
+    /** The data actually drawn — `data` when it fits, the folded slots when it does not. */
+    bands: T[];
+    keys: string[];
+    margin: ChartMargin;
+    plotWidth: number;
+    scale: BandScale;
+    cursor: ChartCursor<T>;
+    point: T | null;
+    /** Plot-local x of the crosshair, or null when no point resolves. */
+    crosshairX: number | null;
+    /** Pitch between adjacent band origins. */
+    step: number;
+    /** Drawn width of one band — the pitch minus a 1px separator, floored at 1. */
+    bandWidth: number;
+    tickValues: string[];
+    svgRef: RefObject<SVGSVGElement | null>;
+    tooltipAnchor: CursorAnchor | null;
+    showTooltip: boolean;
+    /** Only the cursor SOURCE announces — N followers on one page would fire N live-region updates
+     * per pointer move. */
+    ariaLive: boolean;
+};
+/**
+ * Wire a banded plot into the framework's measured margins, band scale, shared cursor and tooltip
+ * positioning. Returns everything except the marks.
+ */
+export declare function useBandPlot<T>(input: UseBandPlotInput<T>): BandPlot<T>;
+export {};
+//# sourceMappingURL=useBandPlot.d.ts.map

package/dist/charts/hooks/useBandPlot.d.ts.map

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

package/dist/charts/hooks/useBandPlot.js

@@ -0,0 +1,127 @@
+import { scaleBand } from "@visx/scale";
+import { useCallback, useMemo, useRef } from "react";
+import { VX } from "../../tokens/index.js";
+import { autoMargin } from "../layout/auto-margin.js";
+import { maxTextWidth } from "../utils/measure-text.js";
+import { smartTicks } from "../utils/ticks.js";
+import { useChartCursor } from "./useChartCursor.js";
+const DEFAULT_MIN_BAND_PX = 3;
+const TERMINAL_GUTTER_MAX_FRACTION = { left: 0.14, right: 0.12 };
+function foldBands(data, cap, merge) {
+  if (cap <= 0) return [];
+  if (data.length <= cap) return [...data];
+  const groupSize = Math.ceil(data.length / cap);
+  const out = [];
+  for (let i = 0; i < data.length; i += groupSize) out.push(merge(data.slice(i, i + groupSize)));
+  return out;
+}
+function useBandPlot(input) {
+  const {
+    data,
+    chartId,
+    getX,
+    formatX,
+    width,
+    fold,
+    cursorResolution,
+    xTickValues,
+    leftLabels,
+    margin: marginOverride,
+    tooltip
+  } = input;
+  const hasLeftAxis = leftLabels !== void 0 && leftLabels.length > 0;
+  const xLabelsAll = useMemo(() => data.map((d) => formatX(getX(d))), [data, getX, formatX]);
+  const margin = useMemo(() => {
+    const measured = autoMargin({
+      ...leftLabels !== void 0 && { left: leftLabels },
+      bottom: xLabelsAll,
+      ...marginOverride !== void 0 && { override: marginOverride }
+    });
+    if (marginOverride?.left !== void 0 && marginOverride.right !== void 0) return measured;
+    const halfXLabel = Math.ceil(maxTextWidth(xLabelsAll, VX.axisFont) / 2);
+    const left = hasLeftAxis ? measured.left : Math.max(measured.left, halfXLabel);
+    return {
+      ...measured,
+      ...marginOverride?.left === void 0 && {
+        left: hasLeftAxis ? left : capTerminalGutter(left, width, TERMINAL_GUTTER_MAX_FRACTION.left, VX.margin.left)
+      },
+      ...marginOverride?.right === void 0 && {
+        right: capTerminalGutter(
+          measured.right,
+          width,
+          TERMINAL_GUTTER_MAX_FRACTION.right,
+          VX.margin.right
+        )
+      }
+    };
+  }, [leftLabels, xLabelsAll, marginOverride, hasLeftAxis, width]);
+  const plotWidth = Math.max(width - margin.left - margin.right, 0);
+  const minBandPx = fold?.minBandPx ?? DEFAULT_MIN_BAND_PX;
+  const merge = fold?.merge;
+  const bands = useMemo(
+    () => merge === void 0 ? [...data] : foldBands(data, Math.floor(plotWidth / minBandPx), merge),
+    [data, plotWidth, minBandPx, merge]
+  );
+  const keys = useMemo(() => bands.map(getX), [bands, getX]);
+  const scale = useMemo(
+    () => scaleBand({ domain: keys, range: [0, plotWidth] }),
+    [keys, plotWidth]
+  );
+  const bandCenter = useCallback(
+    (key) => {
+      const v = scale(key);
+      return v === void 0 ? void 0 : v + scale.bandwidth() / 2;
+    },
+    [scale]
+  );
+  const cursor = useChartCursor({
+    data: bands,
+    chartId,
+    getKey: getX,
+    xScale: bandCenter,
+    marginLeft: margin.left,
+    ...cursorResolution !== void 0 && { resolution: cursorResolution }
+  });
+  const tickValues = useMemo(
+    () => [
+      ...xTickValues === void 0 ? smartTicks(keys, plotWidth) : xTickValues(keys, plotWidth)
+    ],
+    [keys, plotWidth, xTickValues]
+  );
+  const svgRef = useRef(null);
+  const point = cursor.point;
+  const crosshairX = point === null ? null : bandCenter(getX(point)) ?? null;
+  const cfg = tooltip === false ? void 0 : tooltip;
+  const isFollowerRender = !cursor.isSource && cfg?.onFollow === true;
+  const showTooltip = tooltip !== false && point !== null && (cursor.isSource || isFollowerRender);
+  const useAnchored = cfg?.follow === false || isFollowerRender;
+  const anchorX = useAnchored ? crosshairX : null;
+  const svgRect = anchorX === null ? void 0 : svgRef.current?.getBoundingClientRect();
+  const tooltipAnchor = svgRect === void 0 || anchorX === null ? cursor.anchor : { x: svgRect.left + margin.left + anchorX, y: svgRect.top + margin.top };
+  const step = bands.length > 0 ? plotWidth / bands.length : 0;
+  const bandWidth = Math.max(step - 1, 1);
+  return {
+    bands,
+    keys,
+    margin,
+    plotWidth,
+    scale,
+    cursor,
+    point,
+    crosshairX,
+    step,
+    bandWidth,
+    tickValues,
+    svgRef,
+    tooltipAnchor,
+    showTooltip,
+    ariaLive: cursor.isSource
+  };
+}
+function capTerminalGutter(gutter, width, fraction, floor) {
+  return Math.min(gutter, Math.max(floor, Math.round(width * fraction)));
+}
+export {
+  foldBands,
+  useBandPlot
+};

package/dist/charts/index.d.ts

@@ -20,6 +20,7 @@ export { CartesianChart, resolveAxisDomain, type CartesianChartProps, type Carte
 export { ChartFrame, type ChartFrameProps, type ChartFrameLegend, type PlotRect, resolveLegend, } from './primitives/ChartFrame.js';
 export { ChartCenter, type ChartCenterProps, ChartPending, type ChartPendingProps, } from './primitives/ChartPending.js';
 export { Crosshair, SeriesDot } from './primitives/Crosshair.js';
+export { HatchPattern, hatchFill, hatchSizeFor } from './primitives/HatchPattern.js';
 export { ChartCard } from './primitives/ChartCard.js';
 export { ChartLegend, type LegendEntry } from './primitives/ChartLegend.js';
 export { ChartTooltipFloat, TooltipHeader, TooltipRow, TooltipBody, } from './primitives/ChartTooltip.js';
@@ -29,6 +30,7 @@ export { ZoneRects, type ZoneSpec } from './primitives/ZoneRects.js';
 export { XZoneRects, type XZoneSpec } from './primitives/XZoneRects.js';
 export { AreaGradient, areaFillUrl } from './primitives/AreaGradient.js';
 export { useChartCursor, type ChartCursor, type CursorAnchor } from './hooks/useChartCursor.js';
+export { foldBands, type BandFold, type BandTooltipConfig, type BandTooltipRowContext, } from './hooks/useBandPlot.js';
 export type { CursorResolution } from './cursor/resolve.js';
 export { useChartSize, type UseChartSizeResult, type ChartSize } from './hooks/useChartSize.js';
 export { fmtAxisDate, fmtTooltipDate } from './utils/format.js';
@@ -42,6 +44,8 @@ export { Donut, type DonutProps, type DonutDatum } from './kinds/Donut.js';
 export { MultiLine, type MultiLineProps } from './kinds/MultiLine.js';
 export { DualPanel, type DualPanelProps } from './kinds/DualPanel.js';
 export { Heatmap, type HeatmapProps } from './kinds/Heatmap.js';
+export { BandStrip, type BandStripProps, type BandStripSeries, type BandSpan, } from './kinds/BandStrip.js';
+export { MirroredBars, type MirroredBarsProps, type MirroredBarPane } from './kinds/MirroredBars.js';
 export { LineSparkline, BarSparkline } from './sparklines/index.js';
 export { Group } from '@visx/group';
 export { GridRows, GridColumns } from '@visx/grid';

package/dist/charts/index.d.ts.map

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

package/dist/charts/index.js

@@ -30,6 +30,7 @@ import {
   ChartPending
 } from "./primitives/ChartPending.js";
 import { Crosshair, SeriesDot } from "./primitives/Crosshair.js";
+import { HatchPattern, hatchFill, hatchSizeFor } from "./primitives/HatchPattern.js";
 import { ChartCard } from "./primitives/ChartCard.js";
 import { ChartLegend } from "./primitives/ChartLegend.js";
 import {
@@ -44,6 +45,9 @@ import { ZoneRects } from "./primitives/ZoneRects.js";
 import { XZoneRects } from "./primitives/XZoneRects.js";
 import { AreaGradient, areaFillUrl } from "./primitives/AreaGradient.js";
 import { useChartCursor } from "./hooks/useChartCursor.js";
+import {
+  foldBands
+} from "./hooks/useBandPlot.js";
 import { useChartSize } from "./hooks/useChartSize.js";
 import { fmtAxisDate, fmtTooltipDate } from "./utils/format.js";
 import { smartTicks, smartTicksEvery } from "./utils/ticks.js";
@@ -60,6 +64,10 @@ import { Donut } from "./kinds/Donut.js";
 import { MultiLine } from "./kinds/MultiLine.js";
 import { DualPanel } from "./kinds/DualPanel.js";
 import { Heatmap } from "./kinds/Heatmap.js";
+import {
+  BandStrip
+} from "./kinds/BandStrip.js";
+import { MirroredBars } from "./kinds/MirroredBars.js";
 import { LineSparkline, BarSparkline } from "./sparklines/index.js";
 import { Group } from "@visx/group";
 import { GridRows, GridColumns } from "@visx/grid";
@@ -80,6 +88,7 @@ export {
   AxisBottomDate,
   AxisLeftNumeric,
   AxisRightNumeric,
+  BandStrip,
   Bar,
   BarGroup,
   BarSparkline,
@@ -99,11 +108,13 @@ export {
   GridColumns,
   GridRows,
   Group,
+  HatchPattern,
   Heatmap,
   HoverOverlay,
   Line,
   LinePath,
   LineSparkline,
+  MirroredBars,
   MultiLine,
   Pie,
   SeriesDot,
@@ -133,8 +144,11 @@ export {
   deriveTooltipRows,
   fmtAxisDate,
   fmtTooltipDate,
+  foldBands,
   globalCursorStore,
   groupTokens,
+  hatchFill,
+  hatchSizeFor,
   maxTextWidth,
   measureText,
   probeAxisLabels,

package/dist/charts/kinds/BandStrip.d.ts

@@ -0,0 +1,113 @@
+import type { ChartMargin } from '../../tokens/index.js';
+import type { CursorResolution } from '../cursor/resolve.js';
+import type { BandFold, BandTooltipConfig } from '../hooks/useBandPlot.js';
+import type { ChartLegendConfig, SeriesStyle } from '../series.js';
+/**
+ * A state a strip can draw. Extends `SeriesStyle` rather than `ChartSeries` because a band has no
+ * numeric value to plot — `formatValue` reads the datum directly.
+ */
+export type BandStripSeries<T> = SeriesStyle & {
+    /** The derived tooltip row's value for a band in this state. Omit for a state whose NAME is the
+     * whole reading ("Not measured"), which then renders as a label with an empty value. */
+    formatValue?: (d: T) => string;
+};
+/** One drawn band — which state it is in, and the three ways a state can be qualified. */
+export type BandSpan = {
+    /**
+     * Series key naming this band's state: the tie to its legend entry, its fill, and its derived
+     * tooltip row. A key not present in `series` draws nothing — the loud failure is deliberate,
+     * since the alternative is a mark no legend entry accounts for.
+     */
+    state: string;
+    /**
+     * Overrides the fill derived from the state's series entry — the seam for an intensity ramp
+     * WITHIN one state (5% loss vs 0.5% loss are the same state at different strengths). Build it
+     * with `alpha(VX.*, …)`, never a raw hex.
+     */
+    fill?: string;
+    /**
+     * 0..1 of this band's width that no source sample covers, drawn hatched from the band's right.
+     *
+     * This is what a fold owes the reader. A 1-of-3-measured slot whose merge reports the one
+     * measured member's reading paints, without this, as a fully-measured band — a reading asserted
+     * over two slots that reported nothing either way.
+     */
+    absentFraction?: number;
+    /**
+     * A shorter, inset bar drawn over the band — for a fact that must NOT be readable off the fill
+     * ramp (a renegotiation, a restart, a config change). Its colour comes from a `series` entry, so
+     * it cannot be drawn in a hue the legend does not name.
+     */
+    marker?: {
+        /** Series key naming the marker's colour. Defaults to the band's own `state`. */
+        state?: string;
+        /** Vertical inset from the band's top and bottom, in px. Default 6. */
+        inset?: number;
+    };
+};
+export type BandStripProps<T> = {
+    data: readonly T[];
+    /** Stable id — identifies this chart as the cursor's source. */
+    chartId: string;
+    /** Extracts the x-domain key. On a band strip this is a SLOT START, so `cursorResolution`
+     * defaults to `'leading'` (see below) rather than `CartesianChart`'s `'nearest'`. */
+    getX: (d: T) => string;
+    /** The states this strip can draw — the single source of truth for legend entries, band fills,
+     * and the derived tooltip row. */
+    series: readonly BandStripSeries<T>[];
+    /** Which state each datum is in. */
+    getBand: (d: T) => BandSpan;
+    /** Fixed height in px, forwarded to `ChartFrame`. The band row gets whatever the measured
+     * margins and the measured legend band leave. Default 240. */
+    height?: number;
+    /** Fill the parent flex/grid cell's measured height instead of a fixed one. */
+    fill?: boolean;
+    /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
+    formatX?: (key: string) => string;
+    /** Which keys get a tick. Default `smartTicks`. */
+    xTickValues?: (keys: readonly string[], plotWidth: number) => readonly string[];
+    /** Collapse adjacent data at widths where one band per datum sub-pixels. */
+    fold?: BandFold<T>;
+    /**
+     * How a sibling's broadcast cursor key resolves against this strip's slots. Default
+     * `'leading'` — strict containment, "the slot that swallowed this key" — because a band IS a
+     * span keyed by its leading edge, and it stays correct at every fold width. `'nearest'` puts
+     * the crosshair one slot right for every source key in the back half of a slot.
+     */
+    cursorResolution?: CursorResolution;
+    tooltip?: BandTooltipConfig<T> | false;
+    legend?: ChartLegendConfig | false;
+    /** Colour of the absence hatch. Names a `series` entry, so absence is legended like any other
+     * state — a hatched band is the one mark a reader cannot decode from an axis. Default
+     * `VX.neutral`, unnamed. */
+    absentState?: string;
+    /** Per-side overrides of the measured margins — applied last. */
+    margin?: Partial<ChartMargin>;
+    /** Accessible text alternative, forwarded to `ChartFrame` (+ `role="group"`) and to the
+     * focusable hover overlay's slider label. */
+    ariaLabel?: string;
+    /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc. */
+    isPending?: boolean;
+};
+/**
+ * A 1-D categorical band strip: one rect per slot over a shared x axis, no y dimension at all.
+ *
+ * `CartesianChart` cannot host this. It renders `AxisLeftNumeric` unconditionally, so composing it
+ * would draw a numeric axis over a chart that measures nothing vertically — and its `scalePoint` x
+ * scale has positions but no widths, which is the whole content of a strip. This is the
+ * non-single-plot escape `docs/CHARTS-SPEC.md` § "The contract" describes, assembled from the same
+ * parts every other chart gets (`ChartFrame`, `autoMargin`, `useChartCursor`, `ChartTooltipFloat`)
+ * via `useBandPlot`, never re-implemented.
+ *
+ * The three qualifications on {@link BandSpan} — `fill`, `absentFraction`, `marker` — are the ones
+ * a state strip cannot do without: an intensity ramp inside a state, the share of a folded slot
+ * nothing measured, and a fact that must not be read off the ramp.
+ */
+declare function BandStripInner<T>(props: BandStripProps<T>): import("react").JSX.Element;
+/**
+ * Hand-memoized: React Compiler does not process the shipped dist, so the hot kind is wrapped in
+ * `React.memo` to retain the auto-memoization it had as source (parity with `DualPanel`).
+ */
+export declare const BandStrip: typeof BandStripInner;
+export {};
+//# sourceMappingURL=BandStrip.d.ts.map

package/dist/charts/kinds/BandStrip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BandStrip.d.ts","sourceRoot":"","sources":["../../../src/charts/kinds/BandStrip.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEzD,OAAO,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAYvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG/D;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,WAAW,GAAG;IAC7C;4FACwF;IACxF,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;CAC/B,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IACrB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACP,iFAAiF;QACjF,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,uEAAuE;QACvE,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;CACF,CAAA;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,IAAI,EAAE,SAAS,CAAC,EAAE,CAAA;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf;yFACqF;IACrF,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAA;IACtB;sCACkC;IAClC,MAAM,EAAE,SAAS,eAAe,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,oCAAoC;IACpC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAA;IAC3B;kEAC8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;IACjC,mDAAmD;IACnD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAA;IAC/E,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IAClB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,KAAK,CAAA;IACtC,MAAM,CAAC,EAAE,iBAAiB,GAAG,KAAK,CAAA;IAClC;;gCAE4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAC7B;iDAC6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAID;;;;;;;;;;;;;GAaG;AACH,iBAAS,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,+BAgBlD;AAuND;;;GAGG;AACH,eAAO,MAAM,SAAS,EAA2B,OAAO,cAAc,CAAA"}