@orange-halo/components 2.1.0 → 3.0.0

package/dist/oh-radio.js

@@ -1,28 +1,24 @@
 /**
  * oh-radio
  *
- * A chunky, playful radio button with hand-crafted feel.
- * Matches the inset/pressed aesthetic of oh-input.
- *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. CHUNKY & TACTILE
- *    - Thick border (stroke.control)
- *    - Inset shadow when unchecked (pressed into page)
- *    - Fully circular (radio = circle)
+ * 1. LOOK FROM TOKENS
+ *    - Border: stroke.control in color.border.emphasis
+ *    - Circular: shape.pill
+ *    - Shadow: offset by elevation.offset.* in elevation.color.secondary; hover and
+ *      press move the circle by lift.hoverSm / lift.pressSm
  *
  * 2. CHECKED STATE
- *    - Filled dot in center
- *    - Primary color ring
- *    - Shadow shifts to feel "activated"
+ *    - Filled with color.brand.primary, a centre dot in color.text.onBrand,
+ *      and the shadow in elevation.color.primary
  *
  * 3. ACCESSIBILITY
- *    - Native radio hidden but accessible
+ *    - A native radio, visually hidden but focusable and announced
  *    - Label always required
- *    - Focus ring matches input
- *    - Works in radio groups via name attribute
- *
- * @element oh-radio
+ *    - Focus underlines the label (a solid indicator)
+ *    - Two oh-radios with the same name don't form a group (each native
+ *      radio is in its own shadow root): use oh-radio-group for a set
  */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -33,6 +29,44 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { html, css, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { OhElement, baseStyles } from "./base.js";
+/**
+ * A single radio button with its label.
+ *
+ * **Use it for** a one-off radio you manage yourself. **For a set of
+ * choices, use `oh-radio-group`.** Each `oh-radio` keeps its native radio
+ * inside its own shadow root, so two of them with the same `name` don't form
+ * a group: checking one doesn't uncheck the other, and arrow keys don't move
+ * between them. `oh-radio-group` renders the whole set in one place, with
+ * arrow-key navigation and one label for the group. For an independent
+ * on/off choice use `oh-checkbox`.
+ *
+ * **States:** unchecked, checked, hover, active, focus, error (set `error-text`).
+ *
+ * **Behaviour:** clicking the circle or label checks it. Checking sets
+ * `checked` and fires `oh-change`. The native radio sits in the shadow
+ * root, so it doesn't submit with a native form.
+ *
+ * **Accessibility:** a real native radio, visually hidden, carries the role
+ * and state; the drawn circle is decoration. Always set `label`: it's the
+ * radio's name. Focus underlines the label. The error message shows under
+ * the radio with an icon, sets `aria-invalid` and is linked with
+ * `aria-describedby`; it's announced (`role="alert"`) only when it appears
+ * after first render.
+ *
+ * **Look:** set by tokens — `stroke.control` in `color.border.emphasis`
+ * (border), `shape.pill` (circle), `typography.control.*` (label),
+ * `elevation.offset.*` and `elevation.color.secondary` (shadow), `lift.hoverSm` /
+ * `lift.pressSm` (movement on hover and press), `color.border.hover`
+ * (hover), `color.brand.primary` (and its hover and active tokens),
+ * `color.text.onBrand` and `elevation.color.primary` (checked),
+ * `color.feedback.error` and `elevation.color.error` (error).
+ *
+ * @element oh-radio
+ * @fires oh-change - The radio was checked. detail: { checked, value }
+ * @csspart circle - The drawn radio circle
+ * @csspart label - The label text
+ * @csspart error - The error message
+ */
 let OhRadio = class OhRadio extends OhElement {
     constructor() {
         super(...arguments);
@@ -40,8 +74,11 @@ let OhRadio = class OhRadio extends OhElement {
         this.label = "";
         this.name = "";
         this.value = "";
-        this.error = false;
-        this.errorMessage = "";
+        /**
+         * Error shown with the control and linked to it. Setting it puts the
+         * control in its error state; clear it to leave that state.
+         */
+        this.errorText = "";
         /**
          * Force a visual state (for documentation/Figma sync only)
          * Values: 'hover' | 'focus'
@@ -58,11 +95,6 @@ let OhRadio = class OhRadio extends OhElement {
     static { this.styles = [
         baseStyles,
         css `
-      /* ═══════════════════════════════════════════════════════════════
-         ORANGE HALO RADIO
-         Chunky • Tactile • Playful
-         ═══════════════════════════════════════════════════════════════ */
-
       :host {
         display: inline-block;
       }
@@ -96,25 +128,26 @@ let OhRadio = class OhRadio extends OhElement {
         width: 24px;
         height: 24px;
         flex-shrink: 0;
-        
-        /* Chunky border, fully circular */
+
+        /* Border: stroke.control in color.border.emphasis; circular (shape.pill) */
         border: var(--oh-stroke-control) solid var(--oh-color-border-emphasis);
         border-radius: var(--oh-shape-pill);
-        
-        /* Offset shadow like primary button */
+
+        /* Offset shadow: elevation.offset.md in elevation.color.secondary */
         background-color: var(--oh-color-surface-base);
-        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-secondary);
-        
-        transition: 
-          transform var(--oh-motion-snappy) var(--oh-motion-ease-playful),
-          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-playful),
+        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md)
+          0 0 var(--oh-elevation-color-secondary);
+
+        transition:
+          transform var(--oh-motion-snappy) var(--oh-motion-ease-emphasized),
+          box-shadow var(--oh-motion-snappy) var(--oh-motion-ease-emphasized),
           background-color var(--oh-motion-quick) ease,
           border-color var(--oh-motion-quick) ease;
       }
 
       /* Inner dot (hidden by default) */
       .radio-circle::after {
-        content: '';
+        content: "";
         position: absolute;
         top: 50%;
         left: 50%;
@@ -123,31 +156,35 @@ let OhRadio = class OhRadio extends OhElement {
         background-color: var(--oh-color-text-on-brand);
         border-radius: var(--oh-shape-pill);
         transform: translate(-50%, -50%) scale(0);
-        transition: transform var(--oh-motion-snappy) var(--oh-motion-ease-playful);
+        transition: transform var(--oh-motion-snappy)
+          var(--oh-motion-ease-emphasized);
       }
 
       /* ═══════════════════════════════════════════════════════════════
          STATES
          ═══════════════════════════════════════════════════════════════ */
 
-      /* Hover: lift up-left, shadow grows */
+      /* Hover: moves by lift.hoverSm; shadow offset elevation.offset.lg */
       .radio-wrapper:hover .radio-circle {
         border-color: var(--oh-color-border-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-secondary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-secondary);
       }
 
-      /* Active: press down-right, shadow shrinks */
+      /* Active: moves by lift.pressSm; shadow offset elevation.offset.xs */
       .radio-wrapper:active .radio-circle {
         transform: translate(var(--oh-lift-press-sm), var(--oh-lift-press-sm));
-        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs) 0 0 var(--oh-shadow-secondary);
+        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs)
+          0 0 var(--oh-elevation-color-secondary);
       }
 
-      /* Checked: primary color with warm shadow */
+      /* Checked: color.brand.primary fill, elevation.color.primary shadow */
       .native-radio:checked + .radio-circle {
         background-color: var(--oh-color-brand-primary);
         border-color: var(--oh-color-brand-primary);
-        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md)
+          0 0 var(--oh-elevation-color-primary);
       }
 
       .native-radio:checked + .radio-circle::after {
@@ -159,14 +196,16 @@ let OhRadio = class OhRadio extends OhElement {
         background-color: var(--oh-color-brand-primary-hover);
         border-color: var(--oh-color-brand-primary-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-primary);
       }
 
       /* Checked + Active */
       .radio-wrapper:active .native-radio:checked + .radio-circle {
         background-color: var(--oh-color-brand-primary-active);
         transform: translate(var(--oh-lift-press-sm), var(--oh-lift-press-sm));
-        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-xs) var(--oh-elevation-offset-xs)
+          0 0 var(--oh-elevation-color-primary);
       }
 
       /* Focus: underline the label (accessible indicator) */
@@ -192,14 +231,16 @@ let OhRadio = class OhRadio extends OhElement {
          ERROR STATE
          ═══════════════════════════════════════════════════════════════ */
 
-      :host([error]) .radio-circle {
+      :host([data-invalid]) .radio-circle {
         border-color: var(--oh-color-feedback-error);
-        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md) 0 0 var(--oh-shadow-error);
+        box-shadow: var(--oh-elevation-offset-md) var(--oh-elevation-offset-md)
+          0 0 var(--oh-elevation-color-error);
       }
 
-      :host([error]) .radio-wrapper:hover .radio-circle {
+      :host([data-invalid]) .radio-wrapper:hover .radio-circle {
         border-color: var(--oh-color-feedback-error-hover);
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-error);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-error);
       }
 
       .error-message {
@@ -238,7 +279,8 @@ let OhRadio = class OhRadio extends OhElement {
       :host([force-state="hover"]) .radio-circle {
         border-color: var(--oh-color-border-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-secondary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-secondary);
       }
 
       /* Forced Focus - Unchecked */
@@ -252,7 +294,8 @@ let OhRadio = class OhRadio extends OhElement {
         background-color: var(--oh-color-brand-primary-hover);
         border-color: var(--oh-color-brand-primary-hover);
         transform: translate(var(--oh-lift-hover-sm), var(--oh-lift-hover-sm));
-        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg) 0 0 var(--oh-shadow-primary);
+        box-shadow: var(--oh-elevation-offset-lg) var(--oh-elevation-offset-lg)
+          0 0 var(--oh-elevation-color-primary);
       }
     `,
     ]; }
@@ -261,9 +304,14 @@ let OhRadio = class OhRadio extends OhElement {
         this.checked = target.checked;
         this.emit("oh-change", { checked: this.checked, value: this.value });
     }
+    updated(changed) {
+        // Styling hook for the error state (data-invalid on the host)
+        if (changed.has("errorText"))
+            this.toggleAttribute("data-invalid", !!this.errorText);
+    }
     willUpdate(changed) {
-        if (this.hasUpdated && (changed.has("error") || changed.has("errorMessage"))) {
-            this._announceError = !!(this.error && this.errorMessage);
+        if (this.hasUpdated && changed.has("errorText")) {
+            this._announceError = !!this.errorText;
         }
     }
     render() {
@@ -278,20 +326,34 @@ let OhRadio = class OhRadio extends OhElement {
             name=${this.name}
             .value=${this.value}
             .checked=${this.checked}
-            aria-invalid=${this.error ? "true" : "false"}
-            aria-describedby=${this.error && this.errorMessage ? this._errorId : nothing}
+            aria-invalid=${this.errorText ? "true" : "false"}
+            aria-describedby=${this.errorText ? this._errorId : nothing}
             @change=${this._handleChange}
           />
           <span class="radio-circle" part="circle"></span>
           <span class="label" part="label">${this.label}</span>
         </label>
-        ${this.error && this.errorMessage
+        ${this.errorText
             ? html `
-              <div id=${this._errorId} class="error-message" part="error" role=${this._announceError ? "alert" : nothing}>
-                <svg class="error-icon" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
-                  <path fill-rule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-5a.75.75 0 01.75.75v4.5a.75.75 0 01-1.5 0v-4.5A.75.75 0 0110 5zm0 10a1 1 0 100-2 1 1 0 000 2z" clip-rule="evenodd" />
+              <div
+                id=${this._errorId}
+                class="error-message"
+                part="error"
+                role=${this._announceError ? "alert" : nothing}
+              >
+                <svg
+                  class="error-icon"
+                  viewBox="0 0 20 20"
+                  fill="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    fill-rule="evenodd"
+                    d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-8-5a.75.75 0 01.75.75v4.5a.75.75 0 01-1.5 0v-4.5A.75.75 0 0110 5zm0 10a1 1 0 100-2 1 1 0 000 2z"
+                    clip-rule="evenodd"
+                  />
                 </svg>
-                ${this.errorMessage}
+                ${this.errorText}
               </div>
             `
             : ""}
@@ -312,11 +374,8 @@ __decorate([
     property({ type: String })
 ], OhRadio.prototype, "value", void 0);
 __decorate([
-    property({ type: Boolean, reflect: true })
-], OhRadio.prototype, "error", void 0);
-__decorate([
-    property({ type: String })
-], OhRadio.prototype, "errorMessage", void 0);
+    property({ type: String, attribute: "error-text" })
+], OhRadio.prototype, "errorText", void 0);
 __decorate([
     property({ type: String, reflect: true, attribute: "force-state" })
 ], OhRadio.prototype, "forceState", void 0);

package/dist/oh-radio.js.map

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

package/dist/oh-select.d.ts

@@ -1,31 +1,31 @@
 /**
  * oh-select
  *
- * A chunky, playful dropdown select with hand-crafted feel.
- * Custom-styled dropdown (not native) for full visual control.
+ * A custom dropdown select (not a native <select>), so the trigger and the
+ * list can be styled with tokens.
  *
  * DESIGN DECISIONS:
  * ─────────────────
- * 1. CHUNKY & TACTILE
- *    - Thick border (stroke.control)
- *    - Offset shadow (sticker effect like button)
- *    - shape.control corners
- *    - Solid warm fills
+ * 1. TRIGGER
+ *    - A <button role="combobox">, with the same tokens as the other
+ *      controls: stroke.control border in color.border.emphasis,
+ *      shape.control corners, an outset shadow offset by
+ *      elevation.offset.lg in elevation.color.secondary
+ *    - Hover and press move it by lift.hoverMd / lift.pressSm, like oh-button
  *
  * 2. DROPDOWN PANEL
- *    - Appears below trigger with shadow
- *    - Options have hover/focus states
- *    - Selected option highlighted
- *    - Smooth open/close animation
+ *    - A listbox below the trigger, on color.surface.highlight with
+ *      shape.container corners
+ *    - The highlighted option is underlined; the selected option is marked
+ *      in color.brand.primary and set in typography.emphasis.fontWeight
+ *    - Opens and closes with a transition (none under reduced motion)
  *
  * 3. ACCESSIBILITY
- *    - role="combobox" with proper ARIA
- *    - Keyboard navigation (arrows, enter, escape, home, end)
+ *    - role="combobox" with aria-expanded, aria-controls and
+ *      aria-activedescendant; focus stays on the trigger
+ *    - Keyboard navigation (arrows, Enter, Space, Escape, Home, End, Tab)
  *    - Type-ahead search
- *    - Focus management
  *    - Label always required
- *
- * @element oh-select
  */
 import { type PropertyValues } from "lit";
 import { OhElement } from "./base.js";
@@ -33,6 +33,48 @@ export interface SelectOption {
     label: string;
     value: string;
 }
+/**
+ * A dropdown for choosing one option from a list.
+ *
+ * **Use it for** one choice from a list too long to show every option.
+ * **Don't use it for** a few options (use `oh-radio-group`, which shows them
+ * all), several choices (use `oh-checkbox-group`) or free text (use
+ * `oh-input` with `suggestions`).
+ *
+ * **Parts:** a trigger showing the selected option's label (or
+ * `placeholder`), and a list of `options` (`{ label, value }`). One size.
+ * **States:** rest, hover, active, focus, open, error (set `error-text`),
+ * required.
+ *
+ * **Behaviour:** click the trigger, or press Enter, Space or an arrow key,
+ * to open the list. Arrow keys, Home and End move the highlight, Enter or
+ * Space selects, Escape and Tab close, and clicking outside closes. Typing
+ * letters jumps to a matching option (and selects it while the list is
+ * closed). Selecting sets `value`, returns focus to the trigger and fires
+ * `oh-change`. It isn't form-associated: it doesn't submit with a native
+ * form, so read `value` or listen for `oh-change`. It has no `disabled`
+ * property.
+ *
+ * **Accessibility:** the trigger is a `combobox` controlling a `listbox`,
+ * with `aria-activedescendant` for the highlighted option, so focus stays
+ * on the trigger. Always set `label`: it names the trigger and the list.
+ * The error shows after the label and before the trigger, with an icon, sets
+ * `aria-invalid` and is linked with `aria-describedby`; it's announced
+ * (`role="alert"`) only when it appears after first render. Focus is a
+ * solid underline on the trigger text.
+ *
+ * **Look:** set by tokens — `stroke.control` in `color.border.emphasis`
+ * (border), `shape.control` (trigger corners), `shape.container` (list
+ * corners), `typography.control.*` (type), `elevation.offset.*` and
+ * `elevation.color.secondary` (shadow), `lift.hoverMd` / `lift.pressSm` (movement
+ * on hover and press), `color.border.hover` (hover), `focus.ringColor` and
+ * `color.surface.highlight` (open), `color.surface.hover` and
+ * `color.brand.primary` (selected option), `color.feedback.error` and
+ * `elevation.color.error` (error).
+ *
+ * @element oh-select
+ * @fires oh-change - An option was selected. detail: { value }
+ */
 export declare class OhSelect extends OhElement {
     static styles: import("lit").CSSResult[];
     label: string;
@@ -51,6 +93,7 @@ export declare class OhSelect extends OhElement {
     private _labelId;
     private _listboxId;
     private _errorId;
+    private _helperId;
     private _typeaheadBuffer;
     private _typeaheadTimeout;
     private get _selectedOption();

package/dist/oh-select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oh-select.d.ts","sourceRoot":"","sources":["../src/oh-select.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE9D,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBACa,QAAS,SAAQ,SAAS;IACrC,OAAgB,MAAM,4BAoQpB;IAGF,KAAK,SAAM;IAGX,WAAW,SAAsB;IAGjC,IAAI,SAAM;IAGV,OAAO,EAAE,YAAY,EAAE,CAAM;IAG7B,KAAK,SAAM;IAGX,QAAQ,UAAS;IAGjB,UAAU,SAAM;IAGhB,SAAS,SAAM;IAGf,OAAO,CAAC,KAAK,CAAS;IAGtB,OAAO,CAAC,iBAAiB,CAAM;IAG/B,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,QAAQ,CAAqB;IAGrC,OAAO,CAAC,QAAQ,CAAoB;IAEpC,OAAO,CAAC,QAAQ,CAAgE;IAChF,OAAO,CAAC,UAAU,CAAkE;IACpF,OAAO,CAAC,QAAQ,CAAgE;IAChF,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,iBAAiB,CAAuB;IAEhD,OAAO,KAAK,eAAe,GAE1B;IAED,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,qBAAqB;IAqE7B,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,mBAAmB,CAIzB;IAEO,iBAAiB;IAKjB,oBAAoB;IAK7B;;;;OAIG;IAEH,OAAO,CAAC,cAAc,CAAS;IAE/B,UAAU,CAAC,OAAO,EAAE,cAAc;IAMlC,MAAM;CAyGP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,QAAQ,CAAC;KACvB;CACF"}
+{"version":3,"file":"oh-select.d.ts","sourceRoot":"","sources":["../src/oh-select.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAE9D,OAAO,EAAE,SAAS,EAAc,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBACa,QAAS,SAAQ,SAAS;IACrC,OAAgB,MAAM,4BAqQpB;IAGF,KAAK,SAAM;IAGX,WAAW,SAAsB;IAGjC,IAAI,SAAM;IAGV,OAAO,EAAE,YAAY,EAAE,CAAM;IAG7B,KAAK,SAAM;IAGX,QAAQ,UAAS;IAGjB,UAAU,SAAM;IAGhB,SAAS,SAAM;IAGf,OAAO,CAAC,KAAK,CAAS;IAGtB,OAAO,CAAC,iBAAiB,CAAM;IAG/B,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,QAAQ,CAAqB;IAGrC,OAAO,CAAC,QAAQ,CAAoB;IAEpC,OAAO,CAAC,QAAQ,CAAgE;IAChF,OAAO,CAAC,UAAU,CAAkE;IACpF,OAAO,CAAC,QAAQ,CAAgE;IAChF,OAAO,CAAC,SAAS,CAAiE;IAClF,OAAO,CAAC,gBAAgB,CAAM;IAC9B,OAAO,CAAC,iBAAiB,CAAuB;IAEhD,OAAO,KAAK,eAAe,GAE1B;IAED,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,mBAAmB;IAI3B,OAAO,CAAC,qBAAqB;IAqE7B,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,mBAAmB,CAIzB;IAEO,iBAAiB;IAKjB,oBAAoB;IAK7B;;;;OAIG;IAEH,OAAO,CAAC,cAAc,CAAS;IAE/B,UAAU,CAAC,OAAO,EAAE,cAAc;IAMlC,MAAM;CAoIP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,QAAQ,CAAC;KACvB;CACF"}