@omnitron-dev/prism 0.2.0 → 0.3.0

package/dist/utils/format-crypto.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Canonical BTC / XMR amount formatter.
+ *
+ * Why this exists
+ * ---------------
+ * Pre-consolidation the platform had ~8 independent formatters,
+ * each shipping its own opinion of precision:
+ *
+ *   - `org-finances/formatBtc`     → BTC 8, XMR 4
+ *   - `org-revenue-card`           → BTC 4, XMR 4
+ *   - `orgs-overview/formatBtc`    → tiered 8 → 4 → 2 by magnitude
+ *   - `shop-dashboard`             → BTC 4
+ *   - `shop-categories`            → BTC 8 with trailing-zero trim
+ *   - `finances/hooks`             → BTC 8, XMR 8 (already canonical
+ *                                    but isolated from everyone else)
+ *   - `pages/finances DEFAULT_ASSETS` → XMR 12 (wire-precision leak)
+ *
+ * Result: a single dashboard showed BTC 4 in the KPI tile, BTC 8
+ * in the Financial Overview tile, and BTC 6 in another corner —
+ * three "truths" for the same value. This module is the single
+ * source of truth from now on; all call sites import from here.
+ *
+ * Display vs wire precision
+ * -------------------------
+ * Wire precision (what the backend stores) is 8 for BTC, 12 for
+ * XMR — those are the on-chain atomic units (satoshi, piconero).
+ * Display precision is 8 for BOTH coins by platform convention:
+ *
+ *   - 8 fractional digits is a satoshi-level read for BTC,
+ *   - 8 fractional digits for XMR is "good enough" for human eyes
+ *     and keeps the column widths symmetric. The last 4 digits of
+ *     XMR's wire value are dropped from display only — never from
+ *     storage, math, or wire transfers.
+ *
+ * The platform-wide symmetric formatting was a direct user-facing
+ * request: the same coin column should align cleanly whether the
+ * row holds BTC or XMR.
+ *
+ * Which way a dropped digit goes
+ * ------------------------------
+ * Those four dropped XMR digits are the reason this module has a
+ * rounding DIRECTION and not just a scale. Display rounding used
+ * to be half-up, so a balance of
+ *
+ *     1.586170199999 XMR   (what the account holds)
+ *
+ * rendered as `1.58617020 XMR` — a tenth of a piconero MORE than
+ * exists. A person who reads that number and types it back into a
+ * withdrawal is refused for insufficient funds, by a figure the
+ * platform itself put on their screen. The same arithmetic seeds
+ * the "max balance" shortcut, so the refusal arrives from a button
+ * whose entire purpose is to be correct.
+ *
+ * So the rule for anything rendered as money is: **the displayed
+ * magnitude is never larger than the real one.** Quantization for
+ * display truncates toward zero (`'down'`), at any precision, in
+ * either sign. That is not a matter of taste at eight decimals
+ * versus twelve — it holds whatever the scale, which is why it is
+ * a separate decision from the 8-vs-12 convention above.
+ *
+ * Half-up remains available and remains the default for the
+ * ARITHMETIC primitives (`toScaledInteger`, `sumDecimalStrings`,
+ * `subtractDecimalStrings`), where the scale is the value's own
+ * and the last digit is a genuine rounding rather than a
+ * truncation of digits that are really there. Arithmetic on money
+ * belongs at `getCoinWireDecimals(coin)`, not at display scale;
+ * quantize once, at the end, downward.
+ *
+ * The other direction is a lie too
+ * --------------------------------
+ * Truncating `0.000000004916 XMR` to eight decimals gives
+ * `0.00000000` — a balance that exists, shown as nothing at all.
+ * `formatCoinAmount` renders that as `< 0.00000001 XMR` instead
+ * (`> -0.00000001` below zero). A threshold marker is honest about
+ * both the amount and the limit of the column; a flat zero is not.
+ * Pass `markDust: false` where a bare numeral is required.
+ *
+ * If you need a *narrower* surface (a dense table, a stat-card
+ * subtitle), use `{ trim: true }` to drop trailing zeros while
+ * keeping the canonical precision as the cap. Don't bypass this
+ * module with an ad-hoc `toFixed(N)` — that's exactly the entropy
+ * we just cleaned up, and `toFixed` rounds the wrong way for money
+ * on top of rounding a double.
+ */
+/**
+ * Canonical display-precision per supported coin. Use this when
+ * you need the raw precision number (e.g. populating an input
+ * field's `.toFixed(...)` to seed a "max balance" button). For
+ * actual rendering of a value, prefer `formatCoinAmount`.
+ */
+export declare const COIN_DISPLAY_DECIMALS: Readonly<Record<string, number>>;
+/**
+ * Atomic-unit precision per coin — what the backend actually stores.
+ *
+ * This is NOT a display precision and must never be used as one; the
+ * platform shows both coins at eight digits on purpose (see the module
+ * docblock). It is the scale to do ARITHMETIC at: totalling balances,
+ * subtracting a lock from a total, comparing an entered amount against
+ * what is available. Doing that at display scale quantizes four XMR
+ * digits away before the sum, and each quantization is a chance to
+ * report a figure the ledger does not agree with.
+ *
+ * The authority is payments's `coins.precision` column (`BTC` 8, `XMR` 12);
+ * main keeps its own copy in `billing.service.ts` as `CRYPTO_PRECISION`.
+ * This is the browser's copy, because a synchronous formatter cannot
+ * query a table. Three copies of one fact: when a coin is added, all
+ * three change, and a mismatch here shows up as arithmetic that silently
+ * drops the coin's last digits.
+ */
+export declare const COIN_WIRE_DECIMALS: Readonly<Record<string, number>>;
+/**
+ * Which way a value that does not fit the requested scale is quantized.
+ *
+ *   `'down'`     toward zero. The displayed magnitude is never larger
+ *                than the real one — the rule for money on a screen.
+ *   `'half-up'`  to the nearest, ties away from zero. The rule for
+ *                arithmetic, where the scale is the value's own.
+ */
+export type DecimalRounding = 'down' | 'half-up';
+export interface FormatCoinAmountOptions {
+    /**
+     * Append the uppercase coin symbol (`"0.00012345 BTC"`).
+     * Default `true`. Disable for places where the symbol is
+     * rendered separately (e.g. a chip beside the number).
+     */
+    withSymbol?: boolean;
+    /**
+     * Trim trailing zeros after the decimal point. Useful in dense
+     * tables where `0 BTC` reads cleaner than `0.00000000 BTC`. The
+     * precision cap (8) is still honoured — we just drop tail
+     * zeros up to and including the decimal point. Default `false`.
+     */
+    trim?: boolean;
+    /**
+     * Override precision. ONLY use this for legacy back-compat
+     * (e.g. a screen that genuinely needs to truncate at a non-
+     * standard width). Prefer the default. Negative values clamp
+     * to 0.
+     */
+    precision?: number;
+    /**
+     * Custom symbol override. Defaults to `coin.toUpperCase()`. Set
+     * this if you need a non-standard label (e.g. "₿" for BTC) —
+     * but be aware that mixing symbols across the platform is what
+     * this module was built to prevent.
+     */
+    symbol?: string;
+    /**
+     * Which way to quantize digits that do not fit `precision`.
+     * Default `'down'` — a rendered amount is never larger than the
+     * amount that exists. Pass `'half-up'` only where the figure is
+     * not a quantity anyone holds (a rate, an average, a chart axis).
+     */
+    rounding?: DecimalRounding;
+    /**
+     * Render a non-zero amount that vanishes at this precision as
+     * `< 0.00000001` rather than `0.00000000`. Default `true`.
+     * Disable where the output has to be a bare numeral.
+     */
+    markDust?: boolean;
+}
+/**
+ * Resolve the canonical display precision for a coin code.
+ * Case-insensitive. Unknown codes fall back to 8.
+ */
+export declare function getCoinDecimals(coin: string): number;
+/**
+ * Resolve the ATOMIC-UNIT precision for a coin code — the scale the value
+ * arrived at and the scale to compute at. Case-insensitive.
+ *
+ * `getCoinDecimals` is for rendering; this is for `sumDecimalStrings`,
+ * `subtractDecimalStrings`, and any comparison between an amount a person
+ * entered and an amount the ledger holds.
+ */
+export declare function getCoinWireDecimals(coin: string): number;
+/**
+ * Format a decimal STRING at a fixed scale without going through a float.
+ *
+ * Exported because more than one surface needs it: `formatCoinAmount` for
+ * coin balances, `AmountCell` for financial tables. Anything that receives a
+ * decimal string from the wire and renders it should use this rather than
+ * `Number(x).toFixed(n)`.
+ *
+ * The docblock above promises that string input "preserves full precision
+ * end-to-end from the RPC wire", but the implementation used to hand the
+ * string straight to `Number()` — inheriting binary floating point along with
+ * its rounding surprises. `'1.005'` is fractionally BELOW 1.005 as a double,
+ * so `toFixed(2)` rendered `'1.00'`: a balance displayed one cent short of
+ * the one actually stored.
+ *
+ * This is the RENDERING half of the pair, so it quantizes DOWN by default:
+ * the string it returns never stands for more than the string it was given.
+ * Its arithmetic counterpart `toScaledInteger` defaults to `'half-up'`;
+ * the two differ on purpose and the module docblock says why.
+ *
+ * Unlike `formatCoinAmount` it always returns a plain parseable decimal —
+ * no threshold marker, no symbol — because its callers feed the result back
+ * into `Number()`.
+ *
+ * @returns the formatted string, or `null` when `raw` is not a plain decimal
+ *          (exponent notation, junk) — the caller then falls back to `Number`.
+ */
+export declare function formatDecimalString(raw: string, decimals: number, rounding?: DecimalRounding): string | null;
+/**
+ * A decimal string as an exact integer at `decimals` scale.
+ *
+ * `'1.005'` at scale 2 is `101n` under the default half-up — which is the
+ * whole point: as a double the same literal sits fractionally BELOW 1.005,
+ * so any arithmetic that starts with `Number('1.005')` has already lost
+ * before it begins.
+ *
+ * The default is `'half-up'` because this is the arithmetic primitive:
+ * callers pass the value's own scale, where the last digit is a rounding
+ * and not a truncation. Rendering goes through `formatDecimalString`, which
+ * defaults to `'down'` — see the module docblock.
+ *
+ * @returns null when `raw` is not a plain decimal (exponent notation, junk).
+ */
+export declare function toScaledInteger(raw: string, decimals: number, rounding?: DecimalRounding): bigint | null;
+/** Render a scaled integer back as a decimal string. Inverse of `toScaledInteger`. */
+export declare function fromScaledInteger(scaled: bigint, decimals: number): string;
+/**
+ * Add decimal strings exactly, returning a decimal string.
+ *
+ * For totalling amounts that arrived from the wire as strings. Accumulating
+ * them with `parseFloat` is the same mistake as formatting with it, one step
+ * earlier and harder to see: `0.1 + 0.2 + 0.3` is `0.6000000000000001`, and
+ * while a formatter capped at eight decimals rounds that back to `0.60000000`,
+ * anything that shows the raw total — a tooltip, a CSV export, a value posted
+ * back to the server — shows the artefact.
+ *
+ * Values that are not plain decimals are skipped rather than poisoning the
+ * total with `NaN`; `null` and `undefined` count as absent, not as zero-ish
+ * junk. Numbers are accepted for callers mid-migration, and go through their
+ * decimal representation rather than their binary one.
+ *
+ * @param decimals scale to accumulate at — use the coin's WIRE precision
+ *        (`getCoinWireDecimals`). Accumulating at display scale quantizes
+ *        each value before it is added, so the total is a sum of roundings;
+ *        `getCoinDecimals` is for the one quantization at the end.
+ * @param options.rounding how each value is quantized to `decimals`. Default
+ *        `'half-up'`; at wire scale nothing is dropped and it does not
+ *        arise. Pass `'down'` if you must accumulate at display scale and
+ *        the total is money — a sum of half-ups can exceed what exists.
+ */
+export declare function sumDecimalStrings(values: Iterable<string | number | null | undefined>, decimals: number, options?: {
+    rounding?: DecimalRounding;
+}): string;
+/**
+ * Subtract decimal strings exactly, returning a decimal string.
+ *
+ * The companion to `sumDecimalStrings`, and the one a wallet needs more
+ * often: available balance is total minus locked, and computing it with
+ * `parseFloat` produces `0.19999999999999998` from `0.30000000 - 0.10000000`.
+ * A formatter capped at the coin's precision rounds that back, but the raw
+ * value does not always reach a formatter — a tooltip, a CSV column, a
+ * "max" button that fills an amount field, or a value posted back to the
+ * server all show it as it is. Small amounts are worse than wrong: they
+ * become exponential notation, and `1.0999999999999999e-7` is not a number
+ * any balance field will accept.
+ *
+ * Unparseable inputs are treated as absent — `null` when the minuend cannot
+ * be read, since a difference from an unknown quantity is unknown, and
+ * subtracting nothing when a subtrahend cannot be read.
+ *
+ * @param decimals scale to compute at — `getCoinWireDecimals(coin)`. At
+ *        display scale the minuend and the subtrahends are each quantized
+ *        first, and an available balance assembled from two roundings can
+ *        come out above the amount the ledger will actually release.
+ * @param clampAtZero return '0' rather than a negative result. On for the
+ *        available-balance case, where a negative would be a display artefact
+ *        of two readings taken a moment apart, not a debt.
+ * @param rounding how each operand is quantized to `decimals`. Default
+ *        `'half-up'`, matching `toScaledInteger`.
+ */
+export declare function subtractDecimalStrings(minuend: string | number | null | undefined, subtrahends: Iterable<string | number | null | undefined>, decimals: number, options?: {
+    clampAtZero?: boolean;
+    rounding?: DecimalRounding;
+}): string | null;
+/**
+ * Format a crypto amount for display.
+ *
+ * Input can be a string (preferred — preserves full precision
+ * end-to-end from the RPC wire) or a number. Non-finite / NaN
+ * inputs render as the zero-shaped placeholder so the UI never
+ * shows `NaN BTC`.
+ *
+ * Digits below the coin's display precision are dropped, not rounded up:
+ * the string returned never stands for more coin than the argument did.
+ * An amount that is real but smaller than the last displayed digit renders
+ * as `< 0.00000001` rather than as a flat zero.
+ *
+ * @example
+ *   formatCoinAmount('0.001', 'BTC')                 // '0.00100000 BTC'
+ *   formatCoinAmount('0.001', 'BTC', { trim: true }) // '0.001 BTC'
+ *   formatCoinAmount(null, 'XMR')                    // '0.00000000 XMR'
+ *   formatCoinAmount('1.23456789', 'BTC', { withSymbol: false }) // '1.23456789'
+ *   formatCoinAmount('1.586170199999', 'XMR')        // '1.58617019 XMR'
+ *   formatCoinAmount('0.000000004916', 'XMR')        // '< 0.00000001 XMR'
+ */
+export declare function formatCoinAmount(value: string | number | null | undefined, coin: string, options?: FormatCoinAmountOptions): string;
+/**
+ * Render a multi-coin total map (e.g. revenue across coins)
+ * as a single inline string: `"0.00010000 BTC · 0.00000000 XMR"`.
+ *
+ * Stable ordering by lower-cased coin code so BTC always appears
+ * before XMR regardless of object-property iteration quirks.
+ */
+export declare function formatCoinAmountList(totals: Partial<Record<string, string | number | null | undefined>>, options?: FormatCoinAmountOptions & {
+    separator?: string;
+}): string;
+//# sourceMappingURL=format-crypto.d.ts.map

package/dist/utils/format-crypto.d.ts.map

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

package/dist/utils/format-date.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Date Formatting Utilities
+ *
+ * Locale-aware date formatting utilities using Intl.DateTimeFormat.
+ * For more complex formatting, consider using dayjs or date-fns.
+ *
+ * @module utils/format-date
+ */
+export type DateInput = Date | string | number | null | undefined;
+export interface FormatDateOptions extends Intl.DateTimeFormatOptions {
+    /** Locale for formatting (default: 'en-US') */
+    locale?: string;
+}
+/**
+ * Format a date with locale-aware formatting.
+ *
+ * @example
+ * ```ts
+ * fDate(new Date())
+ * // => "Jan 15, 2025"
+ *
+ * fDate(new Date(), { locale: 'ru-RU' })
+ * // => "15 янв. 2025 г."
+ *
+ * fDate('2025-01-15')
+ * // => "Jan 15, 2025"
+ * ```
+ */
+export declare function fDate(date: DateInput, options?: FormatDateOptions): string;
+/**
+ * Format a date with time.
+ *
+ * @example
+ * ```ts
+ * fDateTime(new Date())
+ * // => "Jan 15, 2025, 2:30 PM"
+ *
+ * fDateTime(new Date(), { hour12: false })
+ * // => "Jan 15, 2025, 14:30"
+ * ```
+ */
+export declare function fDateTime(date: DateInput, options?: FormatDateOptions): string;
+/**
+ * Format time only.
+ *
+ * @example
+ * ```ts
+ * fTime(new Date())
+ * // => "2:30 PM"
+ *
+ * fTime(new Date(), { hour12: false })
+ * // => "14:30"
+ *
+ * fTime(new Date(), { second: 'numeric' })
+ * // => "2:30:45 PM"
+ * ```
+ */
+export declare function fTime(date: DateInput, options?: FormatDateOptions): string;
+/**
+ * Format a date as ISO string (YYYY-MM-DD).
+ *
+ * @example
+ * ```ts
+ * fDateISO(new Date())
+ * // => "2025-01-15"
+ * ```
+ */
+export declare function fDateISO(date: DateInput): string;
+/**
+ * Format a timestamp as relative time (e.g., "2 hours ago").
+ *
+ * @example
+ * ```ts
+ * fRelativeTime(new Date(Date.now() - 3600000))
+ * // => "1 hour ago"
+ *
+ * fRelativeTime(new Date(Date.now() + 86400000))
+ * // => "in 1 day"
+ *
+ * fRelativeTime(new Date(Date.now() - 86400000 * 7))
+ * // => "1 week ago"
+ * ```
+ */
+export declare function fRelativeTime(date: DateInput, options?: {
+    locale?: string;
+}): string;
+/**
+ * Format a duration in milliseconds to human-readable string.
+ *
+ * @example
+ * ```ts
+ * fDuration(3661000)
+ * // => "1h 1m 1s"
+ *
+ * fDuration(90000)
+ * // => "1m 30s"
+ *
+ * fDuration(1000)
+ * // => "1s"
+ * ```
+ */
+export declare function fDuration(ms: number | null | undefined): string;
+/**
+ * Check if a date is today.
+ *
+ * @example
+ * ```ts
+ * isToday(new Date())
+ * // => true
+ *
+ * isToday(new Date('2020-01-01'))
+ * // => false
+ * ```
+ */
+export declare function isToday(date: DateInput): boolean;
+/**
+ * Check if a date is yesterday.
+ */
+export declare function isYesterday(date: DateInput): boolean;
+/**
+ * Check if a date is within the current week.
+ */
+export declare function isThisWeek(date: DateInput): boolean;
+/**
+ * Check if a date is in the past.
+ */
+export declare function isPast(date: DateInput): boolean;
+/**
+ * Check if a date is in the future.
+ */
+export declare function isFuture(date: DateInput): boolean;
+/**
+ * Get the difference between two dates in days.
+ */
+export declare function diffInDays(date1: DateInput, date2: DateInput): number;
+/**
+ * Generate an array of dates between start and end.
+ *
+ * @param startDate - Start date
+ * @param endDate - End date
+ * @param interval - Interval in milliseconds (default: 1 day)
+ * @returns Array of Date objects
+ *
+ * @example
+ * ```ts
+ * const dates = getDates(
+ *   new Date('2025-01-01'),
+ *   new Date('2025-01-07')
+ * );
+ * // => [Date(Jan 1), Date(Jan 2), ..., Date(Jan 7)]
+ *
+ * // With custom interval (every 2 days)
+ * const dates = getDates(
+ *   new Date('2025-01-01'),
+ *   new Date('2025-01-07'),
+ *   DAY_MS * 2
+ * );
+ * // => [Date(Jan 1), Date(Jan 3), Date(Jan 5), Date(Jan 7)]
+ * ```
+ */
+export declare function getDates(startDate: DateInput, endDate: DateInput, interval?: number): Date[];
+/**
+ * Duration preset for getPastDates.
+ */
+export type DateDurationPreset = 'week' | 'month' | 'quarter' | 'year';
+/**
+ * Get an array of dates for past duration.
+ *
+ * @param duration - Duration preset or number of days
+ * @returns Array of Date objects from past to present
+ *
+ * @example
+ * ```ts
+ * // Last 7 days
+ * const weekDates = getPastDates('week');
+ *
+ * // Last 30 days
+ * const monthDates = getPastDates('month');
+ *
+ * // Last 90 days
+ * const quarterDates = getPastDates('quarter');
+ *
+ * // Last 365 days
+ * const yearDates = getPastDates('year');
+ *
+ * // Custom: last 14 days
+ * const customDates = getPastDates(14);
+ * ```
+ */
+export declare function getPastDates(duration: DateDurationPreset | number): Date[];
+/**
+ * Get an array of dates for future duration.
+ *
+ * @param duration - Duration preset or number of days
+ * @returns Array of Date objects from present to future
+ *
+ * @example
+ * ```ts
+ * // Next 7 days
+ * const weekDates = getFutureDates('week');
+ *
+ * // Next 30 days
+ * const monthDates = getFutureDates('month');
+ *
+ * // Custom: next 14 days
+ * const customDates = getFutureDates(14);
+ * ```
+ */
+export declare function getFutureDates(duration: DateDurationPreset | number): Date[];
+/**
+ * Get start of day (midnight) for a date.
+ *
+ * @param date - Input date
+ * @returns Date set to 00:00:00.000
+ */
+export declare function startOfDay(date: DateInput): Date | null;
+/**
+ * Get end of day (23:59:59.999) for a date.
+ *
+ * @param date - Input date
+ * @returns Date set to 23:59:59.999
+ */
+export declare function endOfDay(date: DateInput): Date | null;
+/**
+ * Add days to a date.
+ *
+ * @param date - Input date
+ * @param days - Number of days to add (can be negative)
+ * @returns New date with days added
+ */
+export declare function addDays(date: DateInput, days: number): Date | null;
+/**
+ * Add months to a date.
+ *
+ * @param date - Input date
+ * @param months - Number of months to add (can be negative)
+ * @returns New date with months added
+ */
+export declare function addMonths(date: DateInput, months: number): Date | null;
+//# sourceMappingURL=format-date.d.ts.map

package/dist/utils/format-date.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-date.d.ts","sourceRoot":"","sources":["../../src/utils/format-date.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,qBAAqB;IACnE,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA0BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAY9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAclF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAW9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAKhD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAqCxF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAgB/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAUhD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAYpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAcnD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAK/C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAKjD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAQrE;AASD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,GAAE,MAAe,GAAG,IAAI,EAAE,CAUpG;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,EAAE,CAc1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,EAAE,CAc5E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAOrD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAOlE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAOtE"}