@astryxdesign/core 0.7.8 → 0.7.9-canary.7400c1f

package/dist/hooks/useClickableContainer.js

@@ -5,11 +5,13 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ * @output onClick, onMouseUp and onPointerDown handlers for the container;
+ *   INTERACTIVE_SELECTORS list;
  *   hasInteractiveAncestor and the shared innermostInteractive walk
  * @position Core hook for clickable containers with nested interactive
  *   elements. A click on a nested button or link does not run the card's
- *   action. Each navigation passes the rule in utils/safeUrl.ts first.
+ *   action, and a finger press there shows no press on the card. Each navigation
+ *   passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
@@ -17,6 +19,7 @@
 import { useCallback, useEffect } from 'react';
 import { isLayerSurface } from "../Layer/layerSurfacePress.js";
 import { isSafeUrl } from "../utils/safeUrl.js";
+import { cancelPress } from "../utils/pressFeedback.js";
 
 /**
  * The attribute this hook sets on the container it makes clickable. A click
@@ -90,6 +93,24 @@ function belongsToSomethingElse(element) {
   return matchesInteractiveSelectors(element) || isLayerSurface(element);
 }
 
+/**
+ * The touch half of a container's press rule: a finger press that starts on a nested interactive element
+ * other than the container's own action does not activate the container, so
+ * it ends the press controller's paint on `container`. A mouse or pen press,
+ * and a press on the container's surface or on `ownAction`, are left alone.
+ * Not part of the package's public API.
+ */
+export function cancelNestedTouchPress(event, container, ownAction) {
+  const target = event.target;
+  if (event.pointerType !== 'touch' || container == null || !(target instanceof Element) || target === event.currentTarget || !hasInteractiveAncestor(target, container) ||
+  // The container's own action, such as the control it delegates to: a
+  // press on it activates the container.
+  ownAction?.contains(target) === true) {
+    return;
+  }
+  cancelPress(container);
+}
+
 /**
  * Check if there's a text selection inside the node (don't navigate on text select)
  *
@@ -123,12 +144,16 @@ export function hasTextSelection(node) {
  * @example
  * ```
  * const containerRef = useRef<HTMLDivElement>(null);
- * const { onClick, onMouseUp } = useClickableContainer({
+ * const { onClick, onMouseUp, onPointerDown } = useClickableContainer({
  *   containerRef,
  *   onClick: () => console.log('card clicked'),
  * });
  * return (
- *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *   <div
+ *     ref={containerRef}
+ *     onClick={onClick}
+ *     onMouseUp={onMouseUp}
+ *     onPointerDown={onPointerDown}>
  *     <p>Click anywhere on this card</p>
  *     <button onClick={() => alert('button')}>Nested button</button>
  *   </div>
@@ -226,8 +251,19 @@ export function useClickableContainer({
       window.open(href, '_blank', 'noopener');
     }
   }, [containerRef, href, disabled]);
+
+  // The press-state counterpart of onClick's rule, for touch: a finger press
+  // that would not activate the container shows no press on it. A mouse or
+  // pen press keeps its `:active` paint.
+  const onPointerDown = useCallback(event => {
+    if (disabled) {
+      return;
+    }
+    cancelNestedTouchPress(event, containerRef.current, interactiveRef?.current ?? null);
+  }, [containerRef, interactiveRef, disabled]);
   return {
     onClick,
-    onMouseUp
+    onMouseUp,
+    onPointerDown
   };
 }

package/dist/hooks/useMenuPress.d.ts

@@ -2,7 +2,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -119,6 +120,30 @@ export interface UseMenuPressReturn {
     /** End the gesture in flight with nothing acting (the menu closed). */
     cancel: () => void;
 }
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+export interface DropdownMenuPressOptions extends UseMenuPressOptions {
+    /**
+     * How the finger that opened the menu from the trigger picks.
+     * `'pointer'`: its opening press follows the settle rule. `'uikit'`: it
+     * picks only after UIMenu's handoff distance, so the row that appeared
+     * under it never acts on a still lift. A mouse is unaffected.
+     * @default 'pointer'
+     */
+    touchModel?: 'pointer' | 'uikit';
+}
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+export type DropdownMenuPressReturn = UseMenuPressReturn;
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -155,4 +180,12 @@ export interface UseMenuPressReturn {
  * ```
  */
 export declare function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn;
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export declare function useDropdownMenuPress(options: DropdownMenuPressOptions): DropdownMenuPressReturn;
 //# sourceMappingURL=useMenuPress.d.ts.map

package/dist/hooks/useMenuPress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMenuPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuPress.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,EAML,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAC,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAiBpD,OAAO,EAAC,iBAAiB,EAAC,CAAC;AAE3B;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,MAAwB,CAAC;AAC/D,iFAAiF;AACjF,eAAO,MAAM,wBAAwB,MAAyB,CAAC;AAC/D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAM9C,oFAAoF;AACpF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAUhD;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,4DAA4D;AAC5D,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,CAAC,WAAW,EAAE,oBAAoB,KAAK,OAAO,CAAC;IAChE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/D,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACnD,mBAAmB;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,SAAS,EAAE;QACT,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAAC;KACzB,CAAC;IACF,yEAAyE;IACzE,YAAY,EAAE;QACZ,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;QAChE,aAAa,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;KAC/D,CAAC;IACF;;;;OAIG;IACH,uBAAuB,EAAE,MAAM,OAAO,CAAC;IACvC,uEAAuE;IACvE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AA0DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAglB7E"}
+{"version":3,"file":"useMenuPress.d.ts","sourceRoot":"","sources":["../../src/hooks/useMenuPress.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useMenuPress.js

@@ -6,7 +6,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -19,13 +20,14 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { currentGesture } from "../Layer/gestureCounter.js";
-import { IDLE_MENU_PRESS, menuPressStep } from "./menuPressGesture.js";
+import { IDLE_MENU_PRESS, menuPressTransition } from "./menuPressGesture.js";
 import { MENU_PRESS_MARKER } from "./menuPressMarker.js";
 import { useLongPressDetector } from "./useLongPress.js";
 import { edgeAutoscroll } from "../utils/edgeAutoscroll.js";
 import { focusForLastInput } from "../utils/focusReturn.js";
 import { useInteractionModalityTrackingFor } from "../utils/interactionModality.js";
 import { LONG_PRESS_DURATION_MS } from "../motion/uikit/longPress.js";
+import { clearMenuPressLit, holdMenuPressPaint, markMenuPressLit, releaseMenuPressPaint } from "../privateAttributes/menuPressLit.stylex.js";
 import { __resetClickGuardForTest, armClickGuard, CLICK_GUARD_WINDOW_MS, withoutClickGuard } from "../utils/clickGuard.js";
 export { MENU_PRESS_MARKER };
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
@@ -124,6 +126,34 @@ function isInMenuTree(element, root) {
   const owner = element.closest(MENU_PRESS_ROOT_SELECTOR);
   return owner != null && getOutermostRoot(owner) === root;
 }
+
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+
+/**
+ * Where a pointer is, for a finger's handoff distance. Positions reach the
+ * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
+ * rule.
+ */
+function handoffPosition(event, hasHandoff) {
+  return hasHandoff ? {
+    x: event.clientX,
+    y: event.clientY
+  } : {};
+}
+
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -160,6 +190,26 @@ function isInMenuTree(element, root) {
  * ```
  */
 export function useMenuPress(options) {
+  // The touch model is DropdownMenu's alone; an untyped caller's
+  // `touchModel` does not reach the model.
+  const {
+    touchModel: _touchModel,
+    ...publicOptions
+  } = options;
+  return useDropdownMenuPress({
+    ...publicOptions,
+    touchModel: 'pointer'
+  });
+}
+
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export function useDropdownMenuPress(options) {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
@@ -247,8 +297,18 @@ export function useMenuPress(options) {
     autoscroll.stop();
     autoscrollRef.current = null;
   }, [autoscroll]);
+  const litRowRef = useRef(null);
+  const heldMenuRef = useRef(null);
   const endGesture = useCallback(() => {
     longPressApiRef.current?.cancel();
+    if (litRowRef.current != null) {
+      clearMenuPressLit(litRowRef.current);
+      litRowRef.current = null;
+    }
+    if (heldMenuRef.current != null) {
+      releaseMenuPressPaint(heldMenuRef.current);
+      heldMenuRef.current = null;
+    }
     touchMovePreventerRef.current?.();
     touchMovePreventerRef.current = null;
     stopAutoscroll();
@@ -259,10 +319,36 @@ export function useMenuPress(options) {
     gestureRef.current = IDLE_MENU_PRESS;
   }, [stopAutoscroll]);
   const highlight = useCallback(row => {
+    // A held finger or pen marks the row it lights, for the row's pressed
+    // paint. A held mouse keeps the hover tint, as on a desktop.
+    const gesture = gestureRef.current;
+    const isHeld = gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
+    const lit = isHeld ? row : null;
+    if (litRowRef.current !== lit) {
+      if (litRowRef.current != null) {
+        clearMenuPressLit(litRowRef.current);
+      }
+      litRowRef.current = lit;
+      if (lit != null) {
+        markMenuPressLit(lit);
+      }
+    }
     const {
       onHighlight,
       menuRef
     } = optionsRef.current;
+    // The row the press began on stays :active where a pointer hovers, so
+    // the menu holds every row but the lit one off that paint.
+    const held = isHeld ? menuRef.current : null;
+    if (heldMenuRef.current !== held) {
+      if (heldMenuRef.current != null) {
+        releaseMenuPressPaint(heldMenuRef.current);
+      }
+      heldMenuRef.current = held;
+      if (held != null) {
+        holdMenuPressPaint(held);
+      }
+    }
     if (onHighlight != null) {
       onHighlight(row);
       return;
@@ -369,7 +455,7 @@ export function useMenuPress(options) {
     }
   }, [activate, endGesture, getDocument, highlight]);
   const step = useCallback((event, native) => {
-    const result = menuPressStep(gestureRef.current, event);
+    const result = menuPressTransition(gestureRef.current, event);
     gestureRef.current = result.gesture;
     applyEffect(result.effect, result.gesture, native);
   }, [applyEffect]);
@@ -466,7 +552,8 @@ export function useMenuPress(options) {
         type: 'move',
         row: point.row,
         isInMenu: point.isInMenu,
-        time: Date.now()
+        time: Date.now(),
+        ...handoffPosition(event, optionsRef.current.touchModel === 'uikit')
       }, event);
       updateAutoscroll(event);
     };
@@ -480,7 +567,8 @@ export function useMenuPress(options) {
         row: point.row,
         isInMenu: point.isInMenu,
         isOnTrigger: point.isOnTrigger,
-        time: Date.now()
+        time: Date.now(),
+        ...handoffPosition(event, optionsRef.current.touchModel === 'uikit')
       }, event);
     };
     const onCancel = event => {

package/dist/hooks/usePressFeedback.d.ts

@@ -7,11 +7,11 @@ import { pressableProps } from '../utils/pressFeedback.js';
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -27,7 +27,7 @@ import { pressableProps } from '../utils/pressFeedback.js';
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export declare function usePressFeedback(): typeof pressableProps;

package/dist/hooks/usePressFeedback.js

@@ -25,11 +25,11 @@ import { installPressFeedback, pressableProps } from "../utils/pressFeedback.js"
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -45,7 +45,7 @@ import { installPressFeedback, pressableProps } from "../utils/pressFeedback.js"
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export function usePressFeedback() {

package/dist/motion/carryAnimations.d.ts

@@ -0,0 +1,58 @@
+type Writable = Record<string, unknown>;
+/** One animation's state, read before the browser starts it afresh. */
+export interface SavedAnimation {
+    animation: Animation;
+    name: string;
+    target: Element | null;
+    pseudoElement: string | null;
+    values: Writable;
+    effectValues: Writable;
+    timing: EffectTiming | null;
+    keyframes: ComputedKeyframe[] | null;
+    playState: AnimationPlayState;
+    replaceState: AnimationReplaceState;
+}
+/**
+ * Reads one animation's state generically, from what the platform exposes.
+ * That is every accessor with a setter on the animation's and its effect's
+ * prototype chains, every field of the effect's timing, and its keyframes. Only values
+ * that differ from the recreated animation's are written back, so a value the
+ * stylesheet controls stays under its control. A few members are not plain
+ * state and are written in their own step (`ORDERED`). The Animation and
+ * effect objects themselves cannot be carried over: the old ones keep their
+ * listeners and promises.
+ */
+export declare function saveAnimation(animation: Animation): SavedAnimation;
+/**
+ * Puts each state `saved` holds on the CSS animations and transitions of
+ * `root` and its subtree that are not among `survivors`. Each CSS animation
+ * the browser started afresh takes the state of the one it replaces. It is
+ * matched by element, pseudo-element and name, in order, and then by name
+ * alone (an effect script moved to another element or pseudo-element). Each
+ * transition whose animation no longer runs resumes as a script animation in
+ * its state. One started afresh that replaces none is finished: an entrance
+ * that had played and been dropped, or a transition from `@starting-style`.
+ * Script animations are left as they are.
+ */
+export declare function restoreAnimations(root: Element, saved: ReadonlyArray<SavedAnimation>, survivors: ReadonlySet<Animation>): void;
+/** The CSS animations and transitions `saveAnimations` read. */
+export type SavedAnimations = ReadonlyArray<SavedAnimation>;
+/**
+ * Reads the state of every CSS animation and transition of `root` and its
+ * subtree, for `carryAnimations` to give a copy of it.
+ */
+export declare function saveAnimations(root: Element): SavedAnimations;
+/**
+ * Carries on in `copy`, a clone of the root `saved` was read from, now laid
+ * out, the CSS animations and transitions its element ran. A clone starts
+ * each CSS animation again and runs no transition but a `@starting-style`
+ * one. So each CSS animation the clone started takes the state of its
+ * element's, and each transition runs on as a script animation. One the
+ * clone started that its element no longer ran is finished: an entrance that
+ * had played, or a `@starting-style` transition. `copyOf` maps each element
+ * of the cloned subtree to its copy. The element's own animations keep
+ * running, so the copy's take no id or event handler.
+ */
+export declare function carryAnimations(saved: SavedAnimations, copy: Element, copyOf: (element: Element) => Element | null): void;
+export {};
+//# sourceMappingURL=carryAnimations.d.ts.map

package/dist/motion/carryAnimations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carryAnimations.d.ts","sourceRoot":"","sources":["../../src/motion/carryAnimations.ts"],"names":[],"mappings":"AA+BA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAsDxC,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,QAAQ,CAAC;IACjB,YAAY,EAAE,QAAQ,CAAC;IACvB,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACrC,SAAS,EAAE,kBAAkB,CAAC;IAC9B,YAAY,EAAE,qBAAqB,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,cAAc,CAyBlE;AAsJD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,EACpC,SAAS,EAAE,WAAW,CAAC,SAAS,CAAC,GAChC,IAAI,CA8CN;AAED,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAQ7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,IAAI,GAC3C,IAAI,CASN"}