@agent-native/toolkit 0.18.0 → 0.18.1-nightly-20260829003721

package/dist/ui/cube-loader.d.ts

@@ -1,5 +1,5 @@
 export type CubeLoaderProps = Omit<React.SVGProps<SVGSVGElement>, "children"> & {
     size?: number | string;
 };
-export declare function CubeLoader({ className, size, width, height, ...props }: CubeLoaderProps): import("react").JSX.Element;
+export declare function CubeLoader({ className, size, width, height, ref, ...props }: CubeLoaderProps): import("react").JSX.Element;
 //# sourceMappingURL=cube-loader.d.ts.map

package/dist/ui/cube-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cube-loader.d.ts","sourceRoot":"","sources":["../../src/ui/cube-loader.tsx"],"names":[],"mappings":"AAIA,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,EAC7B,UAAU,CACX,GAAG;IACF,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,IAAI,EACJ,KAAK,EACL,MAAM,EACN,GAAG,KAAK,EACT,EAAE,eAAe,+BA8CjB"}
+{"version":3,"file":"cube-loader.d.ts","sourceRoot":"","sources":["../../src/ui/cube-loader.tsx"],"names":[],"mappings":"AAyBA,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,EAC7B,UAAU,CACX,GAAG;IACF,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,IAAI,EACJ,KAAK,EACL,MAAM,EACN,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BAqDjB"}

package/dist/ui/cube-loader.js

@@ -1,11 +1,26 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback } from "react";
 import { cn } from "../utils.js";
 const CUBE_DELAYS = [90, 180, 270, 0, 90, 180, 90, 180, 270];
-export function CubeLoader({ className, size, width, height, ...props }) {
+const CUBE_ANIMATION_DURATION_MS = 650;
+function setRef(ref, value) {
+    if (typeof ref === "function")
+        ref(value);
+    else if (ref)
+        ref.current = value;
+}
+function setCubeAnimationPhase(svg, ref) {
+    if (svg && typeof window !== "undefined") {
+        svg.style.setProperty("--an-cube-loader-phase", `${window.performance.now() % CUBE_ANIMATION_DURATION_MS}ms`);
+    }
+    setRef(ref, svg);
+}
+export function CubeLoader({ className, size, width, height, ref, ...props }) {
     const hasRole = Object.prototype.hasOwnProperty.call(props, "role");
     const hasExplicitSize = size !== undefined || width !== undefined || height !== undefined;
     const ariaLabel = props["aria-label"] ?? (hasRole ? undefined : "Loading");
-    return (_jsxs("svg", { ...props, role: hasRole ? props.role : "status", "aria-label": ariaLabel, width: width ?? size ?? 24, height: height ?? size ?? 24, viewBox: "0 0 24 24", fill: "currentColor", className: cn(!hasExplicitSize && "size-4", className), "data-agent-native-cube-loader": "true", children: [_jsx("style", { children: `
+    const setRefs = useCallback((svg) => setCubeAnimationPhase(svg, ref), [ref]);
+    return (_jsxs("svg", { ...props, ref: setRefs, role: hasRole ? props.role : "status", "aria-label": ariaLabel, width: width ?? size ?? 24, height: height ?? size ?? 24, viewBox: "0 0 24 24", fill: "currentColor", className: cn(!hasExplicitSize && "size-4", className), "data-agent-native-cube-loader": "true", children: [_jsx("style", { children: `
         @keyframes an-cube-pulse {
           0%, 100% { opacity: 0.15; }
           50% { opacity: 0.95; }
@@ -18,6 +33,8 @@ export function CubeLoader({ className, size, width, height, ...props }) {
         @media (prefers-reduced-motion: reduce) {
           .an-cube-cell { animation: none; }
         }
-      ` }), CUBE_DELAYS.map((delay, index) => (_jsx("rect", { className: "an-cube-cell", x: 2.5 + (index % 3) * 7, y: 2.5 + Math.floor(index / 3) * 7, width: 5, height: 5, rx: 1, style: { animationDelay: `${delay}ms` } }, index)))] }));
+      ` }), CUBE_DELAYS.map((delay, index) => (_jsx("rect", { className: "an-cube-cell", x: 2.5 + (index % 3) * 7, y: 2.5 + Math.floor(index / 3) * 7, width: 5, height: 5, rx: 1, style: {
+                    animationDelay: `calc(${delay}ms - var(--an-cube-loader-phase, 0ms))`,
+                } }, index)))] }));
 }
 //# sourceMappingURL=cube-loader.js.map

package/dist/ui/cube-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"cube-loader.js","sourceRoot":"","sources":["../../src/ui/cube-loader.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAS7D,MAAM,UAAU,UAAU,CAAC,EACzB,SAAS,EACT,IAAI,EACJ,KAAK,EACL,MAAM,EACN,GAAG,KAAK,EACQ;IAChB,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,eAAe,GACnB,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC;IACpE,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAE3E,OAAO,CACL,kBACM,KAAK,EACT,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,gBACzB,SAAS,EACrB,KAAK,EAAE,KAAK,IAAI,IAAI,IAAI,EAAE,EAC1B,MAAM,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,EAC5B,OAAO,EAAC,WAAW,EACnB,IAAI,EAAC,cAAc,EACnB,SAAS,EAAE,EAAE,CAAC,CAAC,eAAe,IAAI,QAAQ,EAAE,SAAS,CAAC,mCACxB,MAAM,aAEpC,0BAAQ;;;;;;;;;;;;;OAaP,GAAS,EACT,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CACjC,eAEE,SAAS,EAAC,cAAc,EACxB,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,EACxB,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,EAClC,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,EACT,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,EAAE,cAAc,EAAE,GAAG,KAAK,IAAI,EAAE,IAPlC,KAAK,CAQV,CACH,CAAC,IACE,CACP,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cube-loader.js","sourceRoot":"","sources":["../../src/ui/cube-loader.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAY,MAAM,OAAO,CAAC;AAE9C,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,MAAM,WAAW,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAC7D,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAEvC,SAAS,MAAM,CAAU,GAA6B,EAAE,KAAqB;IAC3E,IAAI,OAAO,GAAG,KAAK,UAAU;QAAE,GAAG,CAAC,KAAK,CAAC,CAAC;SACrC,IAAI,GAAG;QAAE,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC;AACpC,CAAC;AAED,SAAS,qBAAqB,CAC5B,GAAyB,EACzB,GAAwB;IAExB,IAAI,GAAG,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACzC,GAAG,CAAC,KAAK,CAAC,WAAW,CACnB,wBAAwB,EACxB,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,0BAA0B,IAAI,CAC7D,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACnB,CAAC;AASD,MAAM,UAAU,UAAU,CAAC,EACzB,SAAS,EACT,IAAI,EACJ,KAAK,EACL,MAAM,EACN,GAAG,EACH,GAAG,KAAK,EACQ;IAChB,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,eAAe,GACnB,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,CAAC;IACpE,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,WAAW,CACzB,CAAC,GAAyB,EAAE,EAAE,CAAC,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,EAC9D,CAAC,GAAG,CAAC,CACN,CAAC;IAEF,OAAO,CACL,kBACM,KAAK,EACT,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,gBACzB,SAAS,EACrB,KAAK,EAAE,KAAK,IAAI,IAAI,IAAI,EAAE,EAC1B,MAAM,EAAE,MAAM,IAAI,IAAI,IAAI,EAAE,EAC5B,OAAO,EAAC,WAAW,EACnB,IAAI,EAAC,cAAc,EACnB,SAAS,EAAE,EAAE,CAAC,CAAC,eAAe,IAAI,QAAQ,EAAE,SAAS,CAAC,mCACxB,MAAM,aAEpC,0BAAQ;;;;;;;;;;;;;OAaP,GAAS,EACT,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CACjC,eAEE,SAAS,EAAC,cAAc,EACxB,CAAC,EAAE,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,EACxB,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,EAClC,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,EACT,EAAE,EAAE,CAAC,EACL,KAAK,EAAE;oBACL,cAAc,EAAE,QAAQ,KAAK,wCAAwC;iBACtE,IATI,KAAK,CAUV,CACH,CAAC,IACE,CACP,CAAC;AACJ,CAAC"}

package/dist/ui/cube-loader.spec.js

@@ -1,23 +1,57 @@
-import { describe, expect, it } from "vitest";
+import { jsx as _jsx } from "react/jsx-runtime";
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { CubeLoader } from "./cube-loader.js";
 describe("CubeLoader", () => {
+    let container;
+    let root;
+    beforeEach(() => {
+        vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+        container = document.createElement("div");
+        document.body.appendChild(container);
+        root = createRoot(container);
+    });
+    afterEach(() => {
+        act(() => root.unmount());
+        container.remove();
+        vi.unstubAllGlobals();
+    });
     it("honors explicit sizing and decorative semantics", () => {
-        const loader = CubeLoader({
+        const loader = renderToStaticMarkup(createElement(CubeLoader, {
             "aria-label": undefined,
             role: undefined,
             size: 10,
-        });
-        expect(loader.props.width).toBe(10);
-        expect(loader.props.height).toBe(10);
-        expect(loader.props.className).not.toContain("size-4");
-        expect(loader.props.role).toBeUndefined();
-        expect(loader.props["aria-label"]).toBeUndefined();
+        }));
+        expect(loader).toContain('width="10"');
+        expect(loader).toContain('height="10"');
+        expect(loader).not.toContain('class="size-4"');
+        expect(loader).not.toContain("role=");
+        expect(loader).not.toContain("aria-label=");
     });
     it("adds accessible defaults when role semantics are omitted", () => {
-        const loader = CubeLoader({});
-        expect(loader.props.role).toBe("status");
-        expect(loader.props["aria-label"]).toBe("Loading");
-        expect(loader.props.className).toContain("size-4");
+        const loader = renderToStaticMarkup(createElement(CubeLoader));
+        expect(loader).toContain('role="status"');
+        expect(loader).toContain('aria-label="Loading"');
+        expect(loader).toContain('class="size-4"');
+    });
+    it("anchors its cells to the page timeline when mounted again", () => {
+        expect(renderToStaticMarkup(createElement(CubeLoader))).toContain("calc(90ms - var(--an-cube-loader-phase, 0ms))");
+    });
+    it("preserves a caller ref without reattaching on rerenders", () => {
+        const callerRef = vi.fn();
+        act(() => {
+            root.render(_jsx(CubeLoader, { ref: callerRef, "data-testid": "first-render" }));
+        });
+        expect(callerRef).toHaveBeenCalledTimes(1);
+        expect(callerRef).toHaveBeenLastCalledWith(expect.any(SVGSVGElement));
+        act(() => {
+            root.render(_jsx(CubeLoader, { ref: callerRef, "data-testid": "second-render" }));
+        });
+        expect(callerRef).toHaveBeenCalledTimes(1);
     });
 });
 //# sourceMappingURL=cube-loader.spec.js.map

package/dist/ui/cube-loader.spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"cube-loader.spec.js","sourceRoot":"","sources":["../../src/ui/cube-loader.spec.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,MAAM,GAAG,UAAU,CAAC;YACxB,YAAY,EAAE,SAAS;YACvB,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,EAAE;SACT,CAA0C,CAAC;QAE5C,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACvD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IACrD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAA0C,CAAC;QAEvE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cube-loader.spec.js","sourceRoot":"","sources":["../../src/ui/cube-loader.spec.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/toolkit",
-  "version": "0.18.0",
+  "version": "0.18.1-nightly-20260829003721",
   "description": "Reusable app-building UI and helpers for Agent-Native apps.",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/src/ui/cube-loader.spec.tsx

@@ -1,28 +1,73 @@
-import type { ReactElement } from "react";
-import { describe, expect, it } from "vitest";
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { CubeLoader } from "./cube-loader.js";
 
 describe("CubeLoader", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.unstubAllGlobals();
+  });
+
   it("honors explicit sizing and decorative semantics", () => {
-    const loader = CubeLoader({
-      "aria-label": undefined,
-      role: undefined,
-      size: 10,
-    }) as ReactElement<Record<string, unknown>>;
-
-    expect(loader.props.width).toBe(10);
-    expect(loader.props.height).toBe(10);
-    expect(loader.props.className).not.toContain("size-4");
-    expect(loader.props.role).toBeUndefined();
-    expect(loader.props["aria-label"]).toBeUndefined();
+    const loader = renderToStaticMarkup(
+      createElement(CubeLoader, {
+        "aria-label": undefined,
+        role: undefined,
+        size: 10,
+      }),
+    );
+
+    expect(loader).toContain('width="10"');
+    expect(loader).toContain('height="10"');
+    expect(loader).not.toContain('class="size-4"');
+    expect(loader).not.toContain("role=");
+    expect(loader).not.toContain("aria-label=");
   });
 
   it("adds accessible defaults when role semantics are omitted", () => {
-    const loader = CubeLoader({}) as ReactElement<Record<string, unknown>>;
+    const loader = renderToStaticMarkup(createElement(CubeLoader));
+
+    expect(loader).toContain('role="status"');
+    expect(loader).toContain('aria-label="Loading"');
+    expect(loader).toContain('class="size-4"');
+  });
+
+  it("anchors its cells to the page timeline when mounted again", () => {
+    expect(renderToStaticMarkup(createElement(CubeLoader))).toContain(
+      "calc(90ms - var(--an-cube-loader-phase, 0ms))",
+    );
+  });
+
+  it("preserves a caller ref without reattaching on rerenders", () => {
+    const callerRef = vi.fn();
+
+    act(() => {
+      root.render(<CubeLoader ref={callerRef} data-testid="first-render" />);
+    });
+    expect(callerRef).toHaveBeenCalledTimes(1);
+    expect(callerRef).toHaveBeenLastCalledWith(expect.any(SVGSVGElement));
+
+    act(() => {
+      root.render(<CubeLoader ref={callerRef} data-testid="second-render" />);
+    });
 
-    expect(loader.props.role).toBe("status");
-    expect(loader.props["aria-label"]).toBe("Loading");
-    expect(loader.props.className).toContain("size-4");
+    expect(callerRef).toHaveBeenCalledTimes(1);
   });
 });

package/src/ui/cube-loader.tsx

@@ -1,6 +1,27 @@
+import { useCallback, type Ref } from "react";
+
 import { cn } from "../utils.js";
 
 const CUBE_DELAYS = [90, 180, 270, 0, 90, 180, 90, 180, 270];
+const CUBE_ANIMATION_DURATION_MS = 650;
+
+function setRef<Element>(ref: Ref<Element> | undefined, value: Element | null) {
+  if (typeof ref === "function") ref(value);
+  else if (ref) ref.current = value;
+}
+
+function setCubeAnimationPhase(
+  svg: SVGSVGElement | null,
+  ref?: Ref<SVGSVGElement>,
+) {
+  if (svg && typeof window !== "undefined") {
+    svg.style.setProperty(
+      "--an-cube-loader-phase",
+      `${window.performance.now() % CUBE_ANIMATION_DURATION_MS}ms`,
+    );
+  }
+  setRef(ref, svg);
+}
 
 export type CubeLoaderProps = Omit<
   React.SVGProps<SVGSVGElement>,
@@ -14,16 +35,22 @@ export function CubeLoader({
   size,
   width,
   height,
+  ref,
   ...props
 }: CubeLoaderProps) {
   const hasRole = Object.prototype.hasOwnProperty.call(props, "role");
   const hasExplicitSize =
     size !== undefined || width !== undefined || height !== undefined;
   const ariaLabel = props["aria-label"] ?? (hasRole ? undefined : "Loading");
+  const setRefs = useCallback(
+    (svg: SVGSVGElement | null) => setCubeAnimationPhase(svg, ref),
+    [ref],
+  );
 
   return (
     <svg
       {...props}
+      ref={setRefs}
       role={hasRole ? props.role : "status"}
       aria-label={ariaLabel}
       width={width ?? size ?? 24}
@@ -56,7 +83,9 @@ export function CubeLoader({
           width={5}
           height={5}
           rx={1}
-          style={{ animationDelay: `${delay}ms` }}
+          style={{
+            animationDelay: `calc(${delay}ms - var(--an-cube-loader-phase, 0ms))`,
+          }}
         />
       ))}
     </svg>