tyrell-components 1.0.0-RC6

package/lib/styles/wizard.js

@@ -0,0 +1,325 @@
+/**
+ * Wizard Component Styles
+ *
+ * Styles for the ty-wizard container component including:
+ * - Flexbox layout with step indicators and content carousel
+ * - Progress line with animated completion overlay
+ * - Step circles with completed/active/pending states
+ * - Carousel viewport with transform animations
+ * - Responsive design with prefers-reduced-motion support
+ * - Fully customizable via CSS Parts (::part)
+ *
+ * Uses global design system tokens (no component-specific variables):
+ * - Surfaces: --ty-surface-floating, --ty-surface-content, --ty-surface-elevated
+ * - Colors: --ty-color-success, --ty-color-primary, --ty-color-danger
+ * - Borders: --ty-border, --ty-border-soft
+ * - Text: --ty-text, --ty-text-soft
+ *
+ * CSS Parts (for styling via ::part):
+ * - indicators-wrapper: The header containing step indicators
+ * - progress-line: The background progress track
+ * - step-circle: Individual step circle indicators
+ * - panels-container: The content viewport
+ */
+export const wizardStyles = `
+:host {
+  display: block;
+  width: var(--wizard-width, 100%);
+  height: var(--wizard-height, 700px);
+  box-sizing: border-box;
+  /* Note: --step-circle-size is NOT set here to allow inheritance from light DOM.
+     Use fallbacks in var() calls instead. Set on ty-wizard element to customize. */
+}
+
+.wizard-container {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  box-sizing: border-box;
+  border-radius: 12px;
+  border: 1px solid var(--ty-border);
+  background: var(--ty-surface-floating);
+  box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1);
+  overflow: hidden;
+}
+
+/* ===================================== */
+/* Step Indicators Wrapper */
+/* Expose as CSS Part for full styling control */
+/* ===================================== */
+
+.step-indicators-wrapper {
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  position: relative;
+  padding: 24px 24px 16px;
+  border-bottom: 1px solid var(--ty-border-soft, var(--ty-border));
+  background: var(--ty-surface-content);
+}
+
+/* ===================================== */
+/* Progress Line (behind step circles) */
+/* Expose as CSS Part for custom styling */
+/* ===================================== */
+
+.progress-line {
+  position: absolute;
+  /*
+   * With equal-width indicators (flex: 1), each takes 100%/N of the width.
+   * Circle centers are at: 50%/N, 150%/N, 250%/N, ... from left.
+   * Line spans from first center (50%/N) to last center (100% - 50%/N).
+   * Inset = 50% / step-count from each side.
+   */
+  left: calc(50% / var(--step-count, 4));
+  right: calc(50% / var(--step-count, 4));
+  /* Vertically center with step circles - uses circle size variable */
+  top: calc(var(--step-circle-size, 32px) / 2 - 1px);
+  height: 2px;
+  background: var(--ty-border);
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity var(--transition-duration, 300ms) var(--transition-easing, ease-in-out);
+}
+
+.progress-overlay {
+  position: absolute;
+  left: 0;
+  top: 0;
+  height: 100%;
+  background: var(--ty-color-success);
+  transition: width var(--transition-duration, 500ms) var(--transition-easing, ease-in-out);
+  will-change: width;
+}
+
+/* ===================================== */
+/* Step Indicators Container */
+/* ===================================== */
+
+.step-indicators {
+  display: flex;
+  align-items: flex-start;
+  position: relative;
+  /* No padding - let equal-width indicators fill the space */
+}
+
+/* ===================================== */
+/* Individual Step Indicator */
+/* Expose as CSS Part for step styling */
+/* ===================================== */
+
+.step-indicator {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  cursor: pointer;
+  background: transparent;
+  border: none;
+  padding: 0;
+  font: inherit;
+  transition: opacity 200ms;
+  /* Equal width for all indicators - makes progress line alignment predictable */
+  flex: 1;
+  min-width: 0;
+}
+
+.step-indicator[aria-disabled="true"] {
+  opacity: 0.4;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+.step-indicator:focus-visible {
+  outline: 2px solid var(--ty-color-primary);
+  outline-offset: 4px;
+  border-radius: 50%;
+}
+
+/* ===================================== */
+/* Step Circle - Smaller, cleaner */
+/* Expose as CSS Part for circle styling */
+/* ===================================== */
+
+.step-circle {
+  /* Circle size - set --step-circle-size on ty-wizard element to customize */
+  width: var(--step-circle-size, 32px);
+  height: var(--step-circle-size, 32px);
+  border-radius: 50%;
+  border: 2px solid;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  z-index: 10;
+  transition: all var(--transition-duration, 300ms) var(--transition-easing, ease-in-out);
+  box-sizing: border-box;
+  flex-shrink: 0;
+}
+
+/* Completed state - green with success glow */
+.step-circle[data-state="completed"] {
+  background: var(--ty-color-success);
+  border-color: var(--ty-color-success-600, var(--ty-color-success));
+  color: white;
+  box-shadow: 0 0 0 4px rgba(34, 197, 94, 0.1);
+}
+
+/* Active state - primary with primary glow */
+.step-circle[data-state="active"] {
+  background: var(--ty-color-primary);
+  border-color: var(--ty-color-primary-600, var(--ty-color-primary));
+  color: white;
+  box-shadow: 0 0 0 4px rgba(99, 102, 241, 0.1);
+}
+
+/* Pending state - neutral gray */
+.step-circle[data-state="pending"] {
+  background: var(--ty-surface-elevated, #f3f4f6);
+  border-color: var(--ty-border, #d1d5db);
+  color: var(--ty-text-soft, #6b7280);
+}
+
+/* Error state - red with danger glow */
+.step-circle[data-state="error"] {
+  background: var(--ty-color-danger, #ef4444);
+  border-color: var(--ty-color-danger-600, #dc2626);
+  color: white;
+  box-shadow: 0 0 0 4px rgba(239, 68, 68, 0.1);
+}
+
+/* ===================================== */
+/* Step Text Container */
+/* Wraps label and description */
+/* ===================================== */
+
+.step-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  align-items: center;
+}
+
+/* ===================================== */
+/* Step Label - Main title */
+/* ===================================== */
+
+.step-label {
+  font-size: var(--ty-font-sm, 14px);
+  font-weight: var(--ty-font-semibold, 600);
+  color: var(--ty-text, inherit);
+  transition: color 200ms;
+}
+
+.step-indicator[aria-selected="true"] .step-label {
+  color: var(--ty-text-strong, inherit);
+}
+
+.step-indicator[aria-selected="false"] .step-label {
+  color: var(--ty-text-soft, inherit);
+}
+
+/* ===================================== */
+/* Step Description - Subtitle */
+/* ===================================== */
+
+.step-description {
+  font-size: var(--ty-font-xs, 12px);
+  font-weight: var(--ty-font-normal, 400);
+  color: var(--ty-text-soft, #9ca3af);
+  transition: color 200ms;
+  text-align: center;
+  max-width: 120px;
+}
+
+.step-indicator[aria-selected="true"] .step-description {
+  color: var(--ty-text, inherit);
+}
+
+/* ===================================== */
+/* Custom Indicator Content via Slots */
+/* ===================================== */
+
+::slotted([slot^="indicator-"]) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+}
+
+/* ===================================== */
+/* Panels Viewport */
+/* Expose as CSS Part for panels container styling */
+/* ===================================== */
+
+.panels-viewport {
+  position: relative;
+  flex: 1;
+  overflow: hidden;
+  /* Critical: hides off-screen panels */
+  min-height: 0;
+  /* Allows flex child to shrink */
+  background: var(--ty-surface-elevated);
+}
+
+/* ===================================== */
+/* Panels Wrapper (slides horizontally) */
+/* ===================================== */
+
+.panels-wrapper {
+  display: flex;
+  height: 100%;
+  transition: transform var(--transition-duration, 300ms) var(--transition-easing, ease-in-out);
+  will-change: transform;
+}
+
+/* ===================================== */
+/* Slotted Step Panels */
+/* ===================================== */
+
+::slotted(ty-step) {
+  width: var(--wizard-width, 100%);
+  height: 100%;
+  flex-shrink: 0;
+}
+
+/* ===================================== */
+/* Accessibility & Motion Preferences */
+/* ===================================== */
+
+/* Respect user's motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  .panels-wrapper {
+    transition-duration: 0ms !important;
+  }
+
+  .progress-overlay {
+    transition-duration: 0ms !important;
+  }
+
+  .step-circle {
+    transition-duration: 0ms !important;
+  }
+
+  .progress-line {
+    transition-duration: 0ms !important;
+  }
+}
+
+/* Screen reader only content */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+`;
+//# sourceMappingURL=wizard.js.map

package/lib/styles/wizard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wizard.js","sourceRoot":"","sources":["../../src/styles/wizard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4S3B,CAAC"}

package/lib/types/common.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Ty Component Common Types
+ */
+/**
+ * Built-in semantic color flavor names. Append `+` for a stronger shade or `-`
+ * for a softer shade — e.g. `primary`, `primary+`, `primary-`. Matches the
+ * design system's `ty-bg-primary+` / `ty-text-primary-` class convention.
+ */
+export type FlavorBase = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'neutral';
+/**
+ * A flavor with optional shade suffix: `primary | primary+ | primary-`.
+ */
+export type FlavorShaded<F extends string = FlavorBase> = F | `${F}+` | `${F}-`;
+/**
+ * Semantic color flavors used throughout Ty components.
+ *
+ * Built-in flavors get themed styles. Add `+` / `-` for a stronger / softer
+ * shade. Any other string is also accepted — pass a custom flavor name and
+ * theme it via `--ty-button-*` (or component-specific) CSS variables on the
+ * host. The `(string & {})` keeps editor autocomplete on the literals while
+ * leaving the type open.
+ */
+export type Flavor = FlavorShaded | (string & {});
+/** Component size variants */
+export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Input types supported by ty-input */
+export type InputType = 'text' | 'password' | 'email' | 'url' | 'tel' | 'date' | 'time' | 'datetime-local' | 'number' | 'currency' | 'percent' | 'compact' | 'checkbox';
+/** Base properties shared by all Ty components */
+export interface TyBaseElement extends HTMLElement {
+    /** Semantic color flavor */
+    flavor?: Flavor;
+}
+/** Button appearance variant */
+export type ButtonAppearance = 'solid' | 'outlined' | 'ghost';
+/** Button component interface */
+export interface TyButtonElement extends TyBaseElement {
+    /** Button size */
+    size?: Size;
+    /** Visual appearance: solid (filled, default), outlined (border only), ghost (text only) */
+    appearance?: ButtonAppearance;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Pill shape (fully rounded) */
+    pill?: boolean;
+    /** Action (icon-only square) */
+    action?: boolean;
+    /** Full-width */
+    wide?: boolean;
+    /** Button type for forms */
+    type?: 'button' | 'submit' | 'reset';
+}
+/** CSS style content */
+/** Icon size variants */
+export type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '12' | '14' | '16' | '18' | '20' | '24' | '32' | '48' | '64' | '80' | '96';
+/** Icon animation tempo */
+export type IconTempo = 'slow' | 'fast';
+/** Icon component interface */
+export interface TyIconElement extends HTMLElement {
+    /** Icon name to display */
+    name?: string;
+    /** Icon size */
+    size?: IconSize;
+    /** Spin animation */
+    spin?: boolean;
+    /** Pulse animation */
+    pulse?: boolean;
+    /** Animation tempo */
+    tempo?: IconTempo;
+}
+/** Tag component custom event detail */
+export interface TyTagEventDetail {
+    /** Target tag element */
+    target: HTMLElement;
+}
+/** Tag component interface */
+export interface TyTagElement extends TyBaseElement {
+    /** Tag value */
+    value?: string;
+    /** Tag size */
+    size?: Size;
+    /** Selected state */
+    selected?: boolean;
+    /** Pill shape (fully rounded) - default true */
+    pill?: boolean;
+    /** Clickable state */
+    clickable?: boolean;
+    /** Dismissible state */
+    dismissible?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+}
+/** Option component interface - omit 'hidden' from HTMLElement to avoid conflict */
+export interface TyOptionElement extends Omit<HTMLElement, 'hidden'> {
+    /** Option value */
+    value?: string;
+    /** Selected state */
+    selected?: boolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Highlighted state (keyboard navigation) */
+    highlighted?: boolean;
+    /** Hidden state - overrides HTMLElement's hidden */
+    hidden?: boolean;
+}
+/** Input component interface */
+export interface TyInputElement extends TyBaseElement {
+    /** Input type */
+    type?: InputType;
+    /** Input value */
+    value?: string;
+    /** Input name (for forms) */
+    name?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Label text */
+    label?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Required field */
+    required?: boolean;
+    /** Error message */
+    error?: string;
+    /** Input size */
+    size?: Size;
+    /** Associated form */
+    readonly form?: HTMLFormElement | null;
+    /** Currency code for currency type (e.g., 'USD', 'EUR', 'HRK') */
+    currency?: string;
+    /** Locale for formatting (e.g., 'en-US', 'hr-HR') */
+    locale?: string;
+    /** Number of decimal places */
+    precision?: number | string;
+    /** Debounce in milliseconds before firing input/change events (0-5000ms) */
+    debounce?: number | string;
+}
+/** CSS style content */
+export interface StyleContent {
+    /** CSS text content */
+    css: string;
+    /** Optional style ID for caching */
+    id?: string;
+}
+//# sourceMappingURL=common.d.ts.map

package/lib/types/common.d.ts.map

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

package/lib/types/common.js

@@ -0,0 +1,5 @@
+/**
+ * Ty Component Common Types
+ */
+export {};
+//# sourceMappingURL=common.js.map

package/lib/types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/lib/utils/calendar-utils.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Calendar Utilities
+ *
+ * Pure TypeScript utilities for calendar month generation and localization.
+ * Ported from ClojureScript ty/date/core.cljs
+ *
+ * Key Features:
+ * - 42-day calendar grid generation (6 weeks × 7 days)
+ * - Monday-first week ordering
+ * - Rich day context with metadata
+ * - Localized weekday names
+ * - No external dependencies (native Date API only)
+ *
+ * Note on Timestamps:
+ * - `value`: UTC timestamp at midnight UTC (timezone-independent, use for storage/server)
+ * - `localValue`: Local timestamp at midnight local time (use for display/local calculations)
+ * - `year/month/dayInMonth`: Calendar date components (user's mental model)
+ *
+ * Example for October 13, 2025:
+ * - value = Date.UTC(2025, 9, 13) = consistent worldwide
+ * - localValue = new Date(2025, 9, 13).getTime() = varies by timezone
+ * - Both represent the same calendar date, different moments in time
+ */
+/**
+ * Rich context for a single calendar day
+ * Contains all metadata needed for rendering and event handling
+ */
+export interface DayContext {
+    /** Timestamp in milliseconds (UTC midnight) - use for server communication and storage */
+    value: number;
+    /** Timestamp in milliseconds (local midnight) - use for local calculations and display */
+    localValue: number;
+    /** Year (e.g., 2025) */
+    year: number;
+    /** Month (1-12, 1 = January) */
+    month: number;
+    /** Day of month (1-31) */
+    dayInMonth: number;
+    /** Is this a weekend day? (Saturday or Sunday) */
+    weekend: boolean;
+    /** Is this day from a different month? */
+    otherMonth: boolean;
+    /** Is this from the previous month? */
+    prevMonth?: boolean;
+    /** Is this from the next month? */
+    nextMonth?: boolean;
+    /** Is this today? */
+    today?: boolean;
+    /** Is this a holiday? (extensible for future use) */
+    holiday?: boolean;
+    /** Is this day selected? (from calendar's internal state) */
+    isSelected?: boolean;
+    /** Calendar's selected year (if any) */
+    selectedYear?: number;
+    /** Calendar's selected month (if any) */
+    selectedMonth?: number;
+    /** Calendar's selected day (if any) */
+    selectedDay?: number;
+}
+/**
+ * Generate a 42-day calendar grid for a given month
+ *
+ * Returns 6 weeks (42 days) starting from the Monday at or before
+ * the first day of the month. This ensures a complete calendar view
+ * with days from the previous and next months as needed.
+ *
+ * @param year - Year (e.g., 2025)
+ * @param month - Month (1-12, 1 = January)
+ * @param selection - Optional selection state to include in day contexts
+ * @returns Array of 42 day contexts with rich metadata
+ *
+ * @throws {RangeError} If year or month are invalid
+ *
+ * @example
+ * const days = getCalendarMonthDays(2025, 10); // October 2025
+ * console.log(days.length); // 42
+ * console.log(days[0].dayInMonth); // First day shown (might be from September)
+ */
+export declare function getCalendarMonthDays(year: number, month: number, selection?: {
+    year?: number;
+    month?: number;
+    day?: number;
+}): DayContext[];
+/**
+ * Get localized weekday names in Monday-first order
+ *
+ * Note: Intl.DateTimeFormat returns Sunday-first by default,
+ * so we reorder to Monday-first: [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
+ *
+ * @param locale - Locale string (e.g., "en-US", "de-DE", "ja-JP")
+ * @param style - Display style: "long" (Monday), "short" (Mon), "narrow" (M)
+ * @returns Array of 7 weekday names starting with Monday
+ *
+ * @example
+ * getLocalizedWeekdays("en-US", "short")
+ * // Returns: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+ *
+ * getLocalizedWeekdays("de-DE", "long")
+ * // Returns: ["Montag", "Dienstag", "Mittwoch", ...]
+ */
+export declare function getLocalizedWeekdays(locale: string, style?: 'long' | 'short' | 'narrow'): string[];
+/**
+ * Get month name in specified locale
+ *
+ * @param month - Month (1-12)
+ * @param locale - Locale string
+ * @param style - Display style
+ * @returns Localized month name
+ *
+ * @throws {RangeError} If month is invalid
+ */
+export declare function getMonthName(month: number, locale?: string, style?: 'long' | 'short' | 'narrow'): string;
+/**
+ * Format a day context as an ISO date string
+ *
+ * @param dayContext - Day context to format
+ * @returns ISO date string (YYYY-MM-DD)
+ *
+ * @example
+ * formatDayContext({ year: 2025, month: 10, dayInMonth: 13, ... })
+ * // Returns: "2025-10-13"
+ */
+export declare function formatDayContext(dayContext: DayContext): string;
+/**
+ * Check if a day context matches a specific date
+ *
+ * @param dayContext - Day context to check
+ * @param year - Target year
+ * @param month - Target month (1-12)
+ * @param day - Target day
+ * @returns True if the day context matches
+ *
+ * @example
+ * isDayContext(dayCtx, 2025, 10, 13) // true if context is Oct 13, 2025
+ */
+export declare function isDayContext(dayContext: DayContext, year: number, month: number, day: number): boolean;
+/**
+ * Parse an ISO date string (YYYY-MM-DD) into year, month, day components
+ *
+ * @param isoString - ISO date string (YYYY-MM-DD)
+ * @returns Object with year, month (1-12), and day, or null if invalid
+ *
+ * @example
+ * parseISODate("2025-10-13")
+ * // Returns: { year: 2025, month: 10, day: 13 }
+ */
+export declare function parseISODate(isoString: string): {
+    year: number;
+    month: number;
+    day: number;
+} | null;
+/**
+ * Convert a UTC timestamp to an ISO date string
+ * Interprets the timestamp as UTC midnight and returns the date
+ *
+ * @param utcTimestamp - UTC timestamp in milliseconds
+ * @returns ISO date string (YYYY-MM-DD)
+ *
+ * @example
+ * const ctx = getCalendarMonthDays(2025, 10)[0];
+ * utcTimestampToISO(ctx.value) // "2025-10-13"
+ */
+export declare function utcTimestampToISO(utcTimestamp: number): string;
+/**
+ * Convert a local timestamp to an ISO date string
+ * Interprets the timestamp in local timezone and returns the date
+ *
+ * @param localTimestamp - Local timestamp in milliseconds
+ * @returns ISO date string (YYYY-MM-DD)
+ *
+ * @example
+ * const ctx = getCalendarMonthDays(2025, 10)[0];
+ * localTimestampToISO(ctx.localValue) // "2025-10-13"
+ */
+export declare function localTimestampToISO(localTimestamp: number): string;
+//# sourceMappingURL=calendar-utils.d.ts.map

package/lib/utils/calendar-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar-utils.d.ts","sourceRoot":"","sources":["../../src/utils/calendar-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IAEd,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IAEnB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IAEb,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IAEd,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IAEnB,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IAEjB,0CAA0C;IAC1C,UAAU,EAAE,OAAO,CAAC;IAEpB,uCAAuC;IACvC,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,qBAAqB;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAiND;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D,UAAU,EAAE,CAOd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAM,GAAG,OAAO,GAAG,QAAkB,GAC3C,MAAM,EAAE,CAeV;AAMD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,MAAgB,EACxB,KAAK,GAAE,MAAM,GAAG,OAAO,GAAG,QAAiB,GAC1C,MAAM,CAMR;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAK/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAIT;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoBnG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAMlE"}