@pithyjs/ui-kit 0.1.0-beta.0

package/dist/atoms/actions/button/button.scss

@@ -0,0 +1,342 @@
+/// Button component styles
+/// Uses design system tokens and a11y mixins for colors and states.
+/// Color scheme is driven by --_btn-* custom properties, set via data-color.
+///
+/// @group atoms/actions
+
+@use 'sass:map';
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+@use '@pithyjs/design-system/radius/styles/tokens' as radius;
+@use '../../../shared/tokens' as shared;
+@use '@pithyjs/design-system/layout/styles/glass' as glass;
+
+// ============================================
+// Color scheme custom properties
+// ============================================
+
+.ui-button {
+  // Default to primary
+  --_btn-color: var(--color-primary);
+  --_btn-on-color: var(--color-on-primary);
+  --_btn-color-hover: var(--color-primary-hover);
+  --_btn-color-pressed: var(--color-primary-active);
+  // Focus ring matches button color, no offset gap (flush with border)
+  --color-focus-ring: var(--_btn-color);
+  --ring-color: var(--_btn-color);
+  --focus-ring-offset: 0px;
+}
+
+@each $scheme in shared.$semantic-colors {
+  .ui-button[data-color='#{$scheme}'] {
+    --_btn-color: var(--color-#{$scheme});
+    --_btn-on-color: var(--color-on-#{$scheme});
+    --_btn-color-hover: var(--color-#{$scheme}-hover);
+    --_btn-color-pressed: var(--color-#{$scheme}-active);
+  }
+}
+
+// ============================================
+// Base
+// ============================================
+
+.ui-button {
+  // Reset
+  appearance: none;
+  border: none;
+  background: none;
+  outline: none;
+  margin: 0;
+  font: inherit;
+  color: inherit;
+  text-decoration: none;
+  cursor: pointer;
+
+  // Layout
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+
+  // Typography
+  font-weight: var(--font-weight-medium);
+  line-height: 1;
+  white-space: nowrap;
+
+  // Transitions (motion-safe, using design-system motion tokens)
+  @include a11y.motion-safe {
+    transition:
+      var(--motion-transition-background),
+      var(--motion-transition-color),
+      var(--motion-transition-border),
+      var(--motion-transition-shadow),
+      var(--motion-transition-opacity),
+      translate var(--motion-duration-fast) var(--motion-easing-standard);
+  }
+}
+
+// ============================================
+// Full width
+// ============================================
+
+.ui-button[data-full-width] {
+  inline-size: 100%;
+}
+
+// ============================================
+// Sizes
+// Font sizes are one step below the control size on the type scale
+// because u-control-* utilities handle physical dimensions (padding,
+// min-height), so the text stays compact within the control.
+// ============================================
+
+@each $size in shared.$control-sizes {
+  .ui-button[data-size='#{$size}'] {
+    font-size: map.get(shared.$control-font-sizes, $size);
+  }
+}
+
+// ============================================
+// Shape (border-radius)
+// Driven by data-shape (mirrors RadiusSize: none | xs..xl).
+// ============================================
+
+@each $shape, $value in radius.$radius-sizes {
+  .ui-button[data-shape='#{$shape}'] {
+    border-radius: $value;
+  }
+}
+
+// ============================================
+// Variants (all use --_btn-* tokens)
+// ============================================
+
+// --- Solid ---
+.ui-button[data-variant='solid'] {
+  background-color: var(--_btn-color);
+  color: var(--_btn-on-color);
+  // Layered: outer depth + inner highlight (on-color = contrast color for glass effect)
+  @include glass.glass-highlight(var(--_btn-on-color), 12%, var(--shadow-xs));
+
+  // Persistent on-state for toggles (aria-pressed) and disclosure triggers
+  // (aria-expanded). Distinct from :active which is transient (held down).
+  &[aria-pressed='true']:not(:disabled):not([aria-disabled='true']),
+  &[aria-expanded='true']:not(:disabled):not([aria-disabled='true']) {
+    background-color: var(--_btn-color-pressed);
+  }
+
+  &:hover:not(:disabled):not([aria-disabled='true']) {
+    background-color: var(--_btn-color-hover);
+    @include glass.glass-highlight(var(--_btn-on-color), 12%, var(--shadow-sm));
+  }
+
+  &:active:not(:disabled):not([aria-disabled='true']) {
+    background-color: var(--_btn-color-pressed);
+    // Inverted: inset shadow from the button color for pressed feel
+    box-shadow: inset 0 var(--border-width-thin) 0 0
+      color-mix(in oklch, var(--_btn-color-pressed) 80%, transparent);
+  }
+
+  @include a11y.motion-safe {
+    &:hover:not(:disabled):not([aria-disabled='true']) {
+      translate: 0 calc(-1 * var(--border-width-thin));
+    }
+
+    &:active:not(:disabled):not([aria-disabled='true']) {
+      translate: 0 var(--border-width-hairline);
+    }
+  }
+}
+
+// --- Outline ---
+.ui-button[data-variant='outline'] {
+  background-color: transparent;
+  color: var(--_btn-color);
+  box-shadow: inset 0 0 0 var(--border-width-hairline) var(--_btn-color);
+
+  &[aria-pressed='true']:not(:disabled):not([aria-disabled='true']),
+  &[aria-expanded='true']:not(:disabled):not([aria-disabled='true']) {
+    @include a11y.state-background(selected, var(--_btn-color));
+  }
+
+  &:hover:not(:disabled):not([aria-disabled='true']) {
+    @include a11y.state-background(hover, var(--_btn-color));
+  }
+
+  &:active:not(:disabled):not([aria-disabled='true']) {
+    @include a11y.state-background(pressed, var(--_btn-color));
+  }
+
+  @include a11y.motion-safe {
+    &:hover:not(:disabled):not([aria-disabled='true']) {
+      translate: 0 calc(-1 * var(--border-width-thin));
+    }
+
+    &:active:not(:disabled):not([aria-disabled='true']) {
+      translate: 0 var(--border-width-hairline);
+    }
+  }
+}
+
+// --- Ghost ---
+.ui-button[data-variant='ghost'] {
+  background-color: transparent;
+  color: var(--_btn-color);
+
+  &[aria-pressed='true']:not(:disabled):not([aria-disabled='true']),
+  &[aria-expanded='true']:not(:disabled):not([aria-disabled='true']) {
+    @include a11y.state-background(selected, var(--_btn-color));
+  }
+
+  &:hover:not(:disabled):not([aria-disabled='true']) {
+    // Double the normal state-background opacity for ghost since there is
+    // no border or background to anchor the hover feedback visually.
+    background-color: color-mix(
+      in oklch,
+      var(--_btn-color) calc(var(--state-hover-opacity) * 200%),
+      transparent
+    );
+  }
+
+  &:active:not(:disabled):not([aria-disabled='true']) {
+    @include a11y.state-background(pressed, var(--_btn-color));
+  }
+
+  @include a11y.motion-safe {
+    &:hover:not(:disabled):not([aria-disabled='true']) {
+      translate: 0 calc(-1 * var(--border-width-thin));
+    }
+
+    &:active:not(:disabled):not([aria-disabled='true']) {
+      translate: 0 var(--border-width-hairline);
+    }
+  }
+}
+
+// --- Link ---
+.ui-button[data-variant='link'] {
+  background-color: transparent;
+  color: var(--_btn-color);
+  text-decoration: underline;
+  // Reset control-size padding/min-size — link buttons are inline text
+  padding: 0;
+  min-block-size: auto;
+  min-inline-size: auto;
+  position: relative;
+
+  &:hover:not(:disabled):not([aria-disabled='true']) {
+    color: var(--_btn-color-hover);
+    text-decoration: none;
+  }
+
+  &:active:not(:disabled):not([aria-disabled='true']) {
+    color: var(--_btn-color-pressed);
+    text-decoration: none;
+  }
+
+  // Invisible expanded hit area — provides a 44×44 target and exceeds
+  // WCAG 2.5.8 Target Size (Minimum) without changing the visual footprint
+  // of the inline text.
+  &::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: 50%;
+    translate: -50% -50%;
+    min-inline-size: var(--control-min-touch);
+    min-block-size: var(--control-min-touch);
+    inline-size: 100%;
+    block-size: 100%;
+  }
+}
+
+// ============================================
+// Disabled state
+// ============================================
+
+.ui-button:disabled,
+.ui-button[aria-disabled='true'] {
+  opacity: var(--state-disabled-opacity, 0.38);
+  cursor: not-allowed;
+  // No pointer-events: none — aria-disabled keeps button focusable and
+  // interactive for assistive tech. JS click guard handles prevention.
+}
+
+// ============================================
+// Loading state
+// ============================================
+
+.ui-button.ui-button-loading {
+  color: transparent;
+
+  // Hide content visually but preserve accessible name
+  // (opacity: 0 keeps elements in the a11y tree, unlike visibility: hidden
+  // which removes children — leaving the button without an accessible name)
+  > * {
+    opacity: 0;
+  }
+
+  // Spinner via ::after pseudo-element
+  &::after {
+    content: '';
+    position: absolute;
+    inline-size: 1em;
+    block-size: 1em;
+    border: var(--border-width-thin) solid
+      var(--_ui-button-spinner-color, var(--_btn-on-color));
+    border-inline-end-color: transparent;
+    border-radius: 50%;
+
+    @include a11y.motion-safe {
+      animation: var(--motion-animation-spin) var(--motion-duration-deliberate)
+        linear infinite;
+    }
+
+    // Static indicator for reduced motion (full ring at lower opacity)
+    @include a11y.motion-reduced {
+      border-inline-end-color: var(
+        --_ui-button-spinner-color,
+        var(--_btn-on-color)
+      );
+      opacity: 0.5;
+    }
+  }
+}
+
+// Spinner color overrides per variant
+.ui-button[data-variant='outline'].ui-button-loading,
+.ui-button[data-variant='ghost'].ui-button-loading,
+.ui-button[data-variant='link'].ui-button-loading {
+  --_ui-button-spinner-color: var(--_btn-color);
+}
+
+// ============================================
+// High Contrast
+// ============================================
+
+@include a11y.forced-colors {
+  .ui-button {
+    border: var(--border-width-hairline) solid ButtonText;
+  }
+
+  .ui-button[data-variant='ghost'],
+  .ui-button[data-variant='link'] {
+    border-color: transparent;
+  }
+
+  .ui-button[aria-pressed='true'],
+  .ui-button[aria-expanded='true'] {
+    border-color: Highlight;
+  }
+
+  .ui-button:disabled,
+  .ui-button[aria-disabled='true'] {
+    border-color: GrayText;
+    color: GrayText;
+  }
+
+  // Focus ring fallback: box-shadow (used by u-focus-ring) is stripped
+  // in forced-colors mode. Use outline instead so focus stays visible.
+  .ui-button:focus-visible {
+    @include a11y.focus-outline(Highlight);
+  }
+}

package/dist/atoms/actions/icon-button/IconButton.d.ts

@@ -0,0 +1,47 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icon-button",
+  "title": "<IconButton> Action Component",
+  "category": "feature",
+  "risk": "low"
+}
+*/
+import type { ControlSize } from '@pithyjs/design-system';
+import type { IconSizeLevel } from '@pithyjs/design-system/iconography';
+import { type Reactive } from '../../../shared/clickable';
+/** @codexApi {"parent":"pithy.ui-kit.icon-button","name":"IconButtonProps","stability":"stable","signature":"interface IconButtonProps"} */
+export interface IconButtonProps {
+    /** Icon name (from the icon sprite). */
+    icon: string;
+    /** Accessible name — required (icon-only button). */
+    ariaLabel: string;
+    /** Control size — maps to `--control-min-height-{size}` (default `"md"`). */
+    size?: ControlSize;
+    /** Icon size (default `"sm"`). */
+    iconSize?: IconSizeLevel;
+    /**
+     * Active/pressed visual state (e.g. an open popover or a toggled control).
+     * Static or a `() => boolean` accessor for reactive state. Drives both the
+     * `[data-active]` styling hook and `aria-pressed`.
+     */
+    pressed?: Reactive<boolean>;
+    /** Fires on click or keyboard activation. */
+    onClick: () => void;
+}
+/**
+ * A single icon-only button sharing the circular visual of an `<IconGroup>`
+ * option (same `_icon-control` mixin), so standalone icon controls match the
+ * segmented ones pixel-for-pixel.
+ *
+ * @example
+ * ```ts
+ * html`<IconButton icon="'palette'" ariaLabel="'Design system'"
+ *                  pressed="open" onClick="toggle" size="'sm'" />`
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.icon-button","name":"IconButton","stability":"stable","signature":"(props: IconButtonProps) => { el: HTMLButtonElement; destroy: () => void }"} */
+export declare function IconButton({ icon, ariaLabel, size, iconSize, pressed, onClick, }: IconButtonProps): {
+    el: HTMLButtonElement;
+    destroy(): void;
+};
+//# sourceMappingURL=IconButton.d.ts.map

package/dist/atoms/actions/icon-button/IconButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconButton.d.ts","sourceRoot":"","sources":["../../../../src/atoms/actions/icon-button/IconButton.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAGF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGxE,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AAInC,4IAA4I;AAC5I,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC5B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wLAAwL;AACxL,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,SAAS,EACT,IAAW,EACX,QAAe,EACf,OAAO,EACP,OAAO,GACR,EAAE,eAAe;;;EA4DjB"}

package/dist/atoms/actions/icon-button/IconButton.js

@@ -0,0 +1,81 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icon-button",
+  "title": "<IconButton> Action Component",
+  "category": "feature",
+  "risk": "low"
+}
+*/
+import { effect } from '@pithyjs/signals';
+import { resolveIconSvg } from '../../content/icon/resolveIconSvg';
+import { ICON_SIZE_CLASS } from '../../../shared/icon';
+import { hasReactive, readReactive, } from '../../../shared/clickable';
+/**
+ * A single icon-only button sharing the circular visual of an `<IconGroup>`
+ * option (same `_icon-control` mixin), so standalone icon controls match the
+ * segmented ones pixel-for-pixel.
+ *
+ * @example
+ * ```ts
+ * html`<IconButton icon="'palette'" ariaLabel="'Design system'"
+ *                  pressed="open" onClick="toggle" size="'sm'" />`
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.icon-button","name":"IconButton","stability":"stable","signature":"(props: IconButtonProps) => { el: HTMLButtonElement; destroy: () => void }"} */
+export function IconButton({ icon, ariaLabel, size = 'md', iconSize = 'sm', pressed, onClick, }) {
+    if (import.meta.env?.DEV && !ariaLabel?.trim()) {
+        console.warn('[<IconButton>] `ariaLabel` is required and must be a non-empty string (icon-only button).');
+    }
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.classList.add('ui-icon-button');
+    btn.dataset.size = size;
+    btn.setAttribute('aria-label', ariaLabel);
+    const iconWrap = document.createElement('span');
+    // Fall back to the default size class if an invalid `iconSize` slips through
+    // (avoids adding a literal "undefined" class).
+    const iconSizeClass = ICON_SIZE_CLASS[iconSize] ?? ICON_SIZE_CLASS.sm;
+    iconWrap.classList.add('ui-icon', iconSizeClass);
+    iconWrap.setAttribute('aria-hidden', 'true');
+    iconWrap.setAttribute('role', 'none');
+    iconWrap.dataset.icon = icon;
+    const resolved = resolveIconSvg(icon);
+    if (resolved) {
+        iconWrap.appendChild(resolved.svg);
+        if (resolved.missing)
+            iconWrap.dataset.iconMissing = icon;
+    }
+    btn.appendChild(iconWrap);
+    const disposers = [];
+    // Only a TOGGLE button (caller passed `pressed`) gets `aria-pressed` +
+    // `[data-active]`. A plain action button (e.g. the reset affordance) leaves
+    // them off so AT doesn't announce it as a toggle ("not pressed").
+    if (pressed !== undefined) {
+        const applyPressed = () => {
+            const isPressed = readReactive(pressed) === true;
+            btn.dataset.active = String(isPressed);
+            btn.setAttribute('aria-pressed', String(isPressed));
+        };
+        if (hasReactive(pressed)) {
+            disposers.push(effect(applyPressed));
+        }
+        else {
+            applyPressed();
+        }
+    }
+    const handler = () => onClick();
+    btn.addEventListener('click', handler);
+    disposers.push(() => btn.removeEventListener('click', handler));
+    return {
+        el: btn,
+        destroy() {
+            for (const dispose of disposers)
+                dispose();
+            disposers.length = 0;
+            // Clear the icon subtree on destroy (matches Icon/Button) so no stale DOM
+            // lingers when the button is destroyed but `el` is still referenced.
+            btn.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=IconButton.js.map

package/dist/atoms/actions/icon-button/IconButton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconButton.js","sourceRoot":"","sources":["../../../../src/atoms/actions/icon-button/IconButton.ts"],"names":[],"mappings":"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"}

package/dist/atoms/actions/icon-button/icon-button.scss

@@ -0,0 +1,20 @@
+/// IconButton component styles — a standalone circular icon button that shares
+/// the icon-control visual with <IconGroup> options.
+///
+/// @group atoms/actions
+
+@use '../../../shared/tokens' as shared;
+@use '../icon-control' as icon-control;
+
+.ui-icon-button {
+  @include icon-control.icon-control-button;
+}
+
+// Size-based dimensions — maps data-size to --control-min-height-{size}
+// (identical to .ui-icon-group-option sizing).
+@each $size in shared.$control-sizes {
+  .ui-icon-button[data-size='#{$size}'] {
+    inline-size: var(--control-min-height-#{$size});
+    block-size: var(--control-min-height-#{$size});
+  }
+}

package/dist/atoms/actions/icon-group/IconGroup.d.ts

@@ -0,0 +1,60 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.icon-group",
+  "title": "<IconGroup> Action Component",
+  "category": "feature",
+  "risk": "medium"
+}
+*/
+import type { ControlSize } from '@pithyjs/design-system';
+import { type IconSizeLevel } from '@pithyjs/design-system/iconography';
+import { type Reactive } from '../../../shared/clickable';
+/** @codexApi {"parent":"pithy.ui-kit.icon-group","name":"IconGroupItem","stability":"stable","signature":"interface IconGroupItem<T extends string>"} */
+export interface IconGroupItem<T extends string = string> {
+    value: T;
+    icon: string;
+    /** Accessible label per option — required for icon-only buttons. */
+    ariaLabel: string;
+}
+/** @codexApi {"parent":"pithy.ui-kit.icon-group","name":"IconGroupProps","stability":"stable","signature":"interface IconGroupProps<T extends string>"} */
+export interface IconGroupProps<T extends string = string> {
+    /** Options to choose from in display order. */
+    items: ReadonlyArray<IconGroupItem<T>>;
+    /** Currently selected value. Static or `() => T` accessor for reactive state. */
+    value: Reactive<T>;
+    /** Fires with the new value on click or keyboard activation. */
+    onChange: (value: T) => void;
+    /** Required accessible label — announced by screen readers as the radiogroup name. */
+    ariaLabel: string;
+    /** Control size — maps option dimensions to `--control-min-height-{size}` (default: `"md"`). */
+    size?: ControlSize;
+    /** Icon size — defaults to `"sm"`. */
+    iconSize?: IconSizeLevel;
+    /**
+     * Disables the whole group — options become non-interactive and `onChange`
+     * never fires. Static or a `() => boolean` accessor. Pair with a `<Tooltip>`
+     * to explain why it's disabled.
+     */
+    disabled?: Reactive<boolean>;
+}
+/**
+ * Single-select icon-only segmented control. Renders a `role="radiogroup"`
+ * pill with one `role="radio"` button per item. The selected option gets a
+ * circular indicator behind its icon.
+ *
+ * @example
+ * ```html
+ * <IconGroup
+ *   items="viewportItems"
+ *   value="viewport"
+ *   onChange="setViewport"
+ *   ariaLabel="'Viewport size'"
+ * />
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.icon-group","name":"IconGroup","stability":"stable","signature":"<T extends string>(props: IconGroupProps<T>) => { el: HTMLDivElement; destroy: () => void }"} */
+export declare function IconGroup<T extends string = string>(props: IconGroupProps<T>): {
+    el: HTMLDivElement;
+    destroy: () => void;
+};
+//# sourceMappingURL=IconGroup.d.ts.map

package/dist/atoms/actions/icon-group/IconGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconGroup.d.ts","sourceRoot":"","sources":["../../../../src/atoms/actions/icon-group/IconGroup.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAGF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EACL,KAAK,aAAa,EAEnB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,2BAA2B,CAAC;AASnC,yJAAyJ;AACzJ,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACtD,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2JAA2J;AAC3J,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACvD,+CAA+C;IAC/C,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,iFAAiF;IACjF,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnB,gEAAgE;IAChE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;GAcG;AACH,uMAAuM;AACvM,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EACjD,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GACvB;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA4L7C"}