@sentropic/design-system-svelte 0.14.0 → 0.16.0

package/dist/ForceGraph.svelte

@@ -249,6 +249,30 @@
      * null when the hover/focus ends. Intended for syncing an external panel.
      */
     onNodeHover?: (node: ForceGraphNode | null) => void;
+    /**
+     * Reconciliation merge animation (CLIENT-ONLY — driven by `$effect`, which
+     * never runs during SSR, so no merge is animated or resolved server-side).
+     *
+     * Pass a `{ id, from, into }` where both `from` and `into` exist in `nodes`:
+     * the `from` node animates toward the position of `into` while fading out
+     * (the node and its incident edges), then `onMergeComplete(pair)` fires
+     * exactly ONCE for that `id`. Purely visual — the component never mutates the
+     * data; the consumer removes `from` from `nodes` after the callback.
+     *
+     * Idempotent on `id`: re-passing the SAME `id` (even with a new identity for
+     * the object) is a no-op — the animation/callback are not replayed. Passing a
+     * NEW `id` (re)plays the merge, even for the same `from`/`into` pair. After
+     * completion the `from` node stays MASKED (hidden) until the consumer removes
+     * it or a new `mergePair` is supplied, so it does not flash back when the
+     * prop returns to null. Pass null (the default) for no merge in flight.
+     */
+    mergePair?: { id: string; from: string; into: string } | null;
+    /**
+     * Fired once the merge animation for the current `mergePair` completes (or
+     * immediately, on a microtask, under reduced motion). Fires at most ONCE per
+     * `id`. Receives the same pair so the consumer can drop `from` from the data.
+     */
+    onMergeComplete?: (pair: { id: string; from: string; into: string }) => void;
     class?: string;
   };
 
@@ -270,6 +294,8 @@
     edgeCurve = 0.15,
     repulsion = 1,
     onNodeHover,
+    mergePair = null,
+    onMergeComplete,
     class: className
   }: ForceGraphProps = $props();
 
@@ -320,6 +346,26 @@
     };
   }
 
+  // Stable seed from the SET of node ids (sorted), not from ns.length/es.length.
+  // A length-based seed reshuffled the whole layout whenever a node was added or
+  // removed (notably after a reconciliation merge), making the graph "jump". A
+  // hash over the sorted ids keeps the same topology → same layout, so removing
+  // one node leaves the rest essentially in place. (FNV-1a 32-bit over the joined
+  // sorted ids; deterministic and order-independent.)
+  function stableSeed(ns: ForceGraphNode[]): number {
+    const ids = ns.map((n) => n.id).sort();
+    let h = 0x811c9dc5; // FNV offset basis
+    const joined = ids.join("|");
+    for (let i = 0; i < joined.length; i++) {
+      h ^= joined.charCodeAt(i);
+      h = Math.imul(h, 0x01000193); // FNV prime
+    }
+    // Fold in the count too so wholly different graphs of equal id-hash still
+    // differ, but the dominant term is the (order-independent) id hash.
+    h ^= ns.length;
+    return h >>> 0;
+  }
+
   function runSimulation(
     ns: ForceGraphNode[],
     es: ForceGraphEdge[],
@@ -330,7 +376,9 @@
   ): Map<string, { x: number; y: number }> {
     const cx = w / 2;
     const cy = h / 2;
-    const rand = mulberry32(ns.length * 2654435761 + es.length);
+    // Seed from the stable id-set hash so adding/removing a node does not
+    // reshuffle the whole layout (same topology → same layout).
+    const rand = mulberry32(stableSeed(ns));
     const idIndex = new Map<string, number>();
     const sim: SimNode[] = ns.map((n, i) => {
       idIndex.set(n.id, i);
@@ -549,6 +597,176 @@
       .filter((e): e is NonNullable<typeof e> => e !== null);
   });
 
+  // ---------------------------------------------------------------------------
+  // Merge animation (reconciliation): when `mergePair` becomes a new valid pair,
+  // the `from` node slides toward `into` while fading out (node + incident
+  // edges), then `onMergeComplete` fires. Purely visual — never mutates props.
+  // Driven by a single $state holding per-merge progress (0→1). Under reduced
+  // motion / SSR we skip straight to completion on a microtask.
+  // ---------------------------------------------------------------------------
+  const MERGE_DURATION_MS = 450;
+  // ease-in-out (cubic) for a smooth glide.
+  const easeInOut = (t: number) =>
+    t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+
+  type MergeState = {
+    id: string;
+    from: string;
+    into: string;
+    /** Animation progress, 0..1. */
+    progress: number;
+    /** Pixel delta from the `from` start position to `into`, captured at start. */
+    dx: number;
+    dy: number;
+  } | null;
+
+  let mergeState = $state<MergeState>(null);
+  let mergeRaf: number | null = null;
+  // The id currently being (or already) handled, so the $effect only reacts to a
+  // genuinely NEW id. Re-passing the same id (even a fresh object) is a no-op.
+  let handledMergeId: string | null = null;
+  // The id of the `from` node to keep MASKED after a completed merge, until the
+  // consumer drops it from `nodes` (or a new pair arrives). Decouples the mask
+  // from `mergePair` returning to null (otherwise the node would flash back).
+  let maskedFromId = $state<string | null>(null);
+  // Set true on the component's own teardown so no queued microtask/frame fires a
+  // callback or touches reactive state after unmount.
+  let disposed = false;
+
+  function cancelMergeRaf() {
+    if (mergeRaf != null && typeof cancelAnimationFrame === "function") {
+      cancelAnimationFrame(mergeRaf);
+    }
+    mergeRaf = null;
+  }
+
+  // Component-lifetime teardown guard (separate from the per-pair effect below):
+  // marks the instance disposed and cancels any in-flight frame on unmount.
+  $effect(() => {
+    return () => {
+      disposed = true;
+      cancelMergeRaf();
+    };
+  });
+
+  $effect(() => {
+    const pair = mergePair;
+    const id = pair ? pair.id : null;
+
+    // Idempotent on id: same id (or still null) means nothing to (re)start. A new
+    // id always (re)plays, even for the same from/into pair.
+    if (id === handledMergeId) return;
+    handledMergeId = id;
+
+    // Tear down any in-flight animation for a previous pair.
+    cancelMergeRaf();
+    mergeState = null;
+
+    if (!pair) return;
+
+    // A genuinely new pair supersedes any lingering mask from a prior merge.
+    maskedFromId = null;
+
+    // Validate: both endpoints must currently exist.
+    const fromPos = layout.get(pair.from);
+    const intoPos = layout.get(pair.into);
+    if (!fromPos || !intoPos) return; // invalid pair: no-op, no crash, no callback
+
+    const captured = { id: pair.id, from: pair.from, into: pair.into };
+
+    const complete = () => {
+      // Keep `from` hidden until the consumer removes it (or a new pair arrives).
+      maskedFromId = captured.from;
+      onMergeComplete?.(captured);
+    };
+
+    // Reduced motion: no animation, resolve on a microtask. Guarded so a late
+    // microtask after unmount or after a newer id took over is a no-op.
+    if (prefersReducedMotion || typeof requestAnimationFrame !== "function") {
+      queueMicrotask(() => {
+        if (disposed || handledMergeId !== id) return;
+        complete();
+      });
+      return;
+    }
+
+    const dx = intoPos.x - fromPos.x;
+    const dy = intoPos.y - fromPos.y;
+    mergeState = { id: captured.id, from: captured.from, into: captured.into, progress: 0, dx, dy };
+
+    // Anchor the clock to the FIRST frame's own timestamp. rAF timestamps and
+    // performance.now() can use different time origins (notably under jsdom), so
+    // mixing them yields a negative/garbage elapsed time. Using the frame clock
+    // for both start and elapsed keeps the easing monotonic everywhere.
+    let start: number | null = null;
+    const tick = (now: number) => {
+      // Bail cleanly if the instance went away or a newer id superseded us — no
+      // callback, no dangling state.
+      if (disposed || handledMergeId !== id) {
+        mergeRaf = null;
+        return;
+      }
+      // Re-validate both endpoints every frame: if either disappears mid-flight
+      // (e.g. the consumer removed a node), cancel the glide WITHOUT firing
+      // onMergeComplete (no double-tir) and without a dangling frame.
+      if (!layout.has(captured.from) || !layout.has(captured.into)) {
+        cancelMergeRaf();
+        mergeState = null;
+        return;
+      }
+      if (start === null) start = now;
+      const t = Math.min(1, Math.max(0, (now - start) / MERGE_DURATION_MS));
+      if (mergeState) mergeState = { ...mergeState, progress: t };
+      if (t < 1) {
+        mergeRaf = requestAnimationFrame(tick);
+      } else {
+        mergeRaf = null;
+        mergeState = null;
+        complete();
+      }
+    };
+    mergeRaf = requestAnimationFrame(tick);
+
+    return () => cancelMergeRaf();
+  });
+
+  // ---------------------------------------------------------------------------
+  // The `from` node is hidden while it is the active merge source AND while it
+  // remains masked post-completion (until the consumer removes it). Both feed the
+  // same opacity helpers below.
+  // ---------------------------------------------------------------------------
+  const mergeFromId = $derived(mergeState?.from ?? null);
+  const mergeEased = $derived(mergeState ? easeInOut(mergeState.progress) : 0);
+
+  /** True when this id is the (post-merge) masked node — render it fully hidden. */
+  function isMasked(id: string): boolean {
+    return maskedFromId === id;
+  }
+
+  /** Extra translation applied to the merging node so it glides toward `into`. */
+  function mergeOffset(id: string): { x: number; y: number } {
+    if (!mergeState || mergeState.from !== id) return { x: 0, y: 0 };
+    return { x: mergeState.dx * mergeEased, y: mergeState.dy * mergeEased };
+  }
+
+  /**
+   * Opacity for a node during/after a merge. The animating `from` fades 1->0; a
+   * masked `from` (merge done, awaiting removal) stays at 0. Others unaffected.
+   */
+  function mergeNodeOpacity(id: string): number | null {
+    if (isMasked(id)) return 0;
+    if (mergeFromId !== id) return null;
+    return 1 - mergeEased;
+  }
+
+  /** Opacity for an edge incident to the merging/masked `from` node (fades too). */
+  function mergeEdgeOpacity(e: ForceGraphEdge): number | null {
+    const fromId = mergeFromId ?? maskedFromId;
+    if (fromId == null) return null;
+    if (e.source !== fromId && e.target !== fromId) return null;
+    return isMasked(fromId) ? 0 : 1 - mergeEased;
+  }
+
   let hoveredNodeIndex: number | null = $state(null);
   let hoveredEdgeIndex: number | null = $state(null);
 
@@ -779,6 +997,7 @@
             onmouseleave={() => { hoveredEdgeIndex = null; }}
           />
         {/if}
+        {@const mEdgeOpacity = mergeEdgeOpacity(e.edge)}
         {#if e.path}
           <path
             class="st-forceGraph__edge"
@@ -786,10 +1005,12 @@
             class:st-forceGraph__edge--emphasis={e.edge.emphasis}
             class:st-forceGraph__edge--hovered={hoveredEdgeIndex === e.i}
             class:st-forceGraph__edge--dim={isEdgeSelectionDimmed(e.edge) || isHoverDimmedEdge(e.edge)}
+            class:st-forceGraph__edge--merging={mEdgeOpacity !== null}
             d={e.path}
             fill="none"
             stroke-dasharray={e.dashArray}
             stroke-width={e.strokeWidth}
+            opacity={mEdgeOpacity}
             pointer-events="none"
           />
         {:else}
@@ -799,12 +1020,14 @@
             class:st-forceGraph__edge--emphasis={e.edge.emphasis}
             class:st-forceGraph__edge--hovered={hoveredEdgeIndex === e.i}
             class:st-forceGraph__edge--dim={isEdgeSelectionDimmed(e.edge) || isHoverDimmedEdge(e.edge)}
+            class:st-forceGraph__edge--merging={mEdgeOpacity !== null}
             x1={e.x1}
             y1={e.y1}
             x2={e.x2}
             y2={e.y2}
             stroke-dasharray={e.dashArray}
             stroke-width={e.strokeWidth}
+            opacity={mEdgeOpacity}
             pointer-events="none"
           />
         {/if}
@@ -813,12 +1036,18 @@
 
     <g class="st-forceGraph__nodes">
       {#each positionedNodes as p (p.node.id)}
+        {@const mOff = mergeOffset(p.node.id)}
+        {@const mOpacity = mergeNodeOpacity(p.node.id)}
+        {@const mMasked = isMasked(p.node.id)}
         <g
           class="st-forceGraph__node st-forceGraph__node--{p.tone}"
           class:st-forceGraph__node--dim={isHoverDimmedNode(p.node.id) || isSelectionDimmed(p.node.id)}
           class:st-forceGraph__node--selected={selectedSet.has(p.node.id)}
           class:st-forceGraph__node--focus={focusId === p.node.id}
-          transform="translate({p.x} {p.y})"
+          class:st-forceGraph__node--merging={mergeFromId === p.node.id || mMasked}
+          aria-hidden={mMasked ? "true" : undefined}
+          opacity={mOpacity}
+          transform="translate({p.x + mOff.x} {p.y + mOff.y})"
         >
           {#if p.shapePath}
             <path
@@ -1022,6 +1251,14 @@
   .st-forceGraph__node { transition: opacity 120ms ease; }
   .st-forceGraph__node--dim { opacity: 0.3; }
 
+  /* During a merge the opacity/transform are driven per-frame via rAF, so the
+     CSS transitions are disabled to avoid a lag that would smear the glide. The
+     fading/masked `from` node is also taken out of hit-testing so the invisible
+     node cannot be hovered, focused or clicked. */
+  .st-forceGraph__node--merging,
+  .st-forceGraph__edge--merging { transition: none; }
+  .st-forceGraph__node--merging { pointer-events: none; }
+
   .st-forceGraph__dot {
     cursor: pointer;
     fill-opacity: 0.9;

package/dist/ForceGraph.svelte.d.ts

@@ -138,6 +138,38 @@ type ForceGraphProps = {
      * null when the hover/focus ends. Intended for syncing an external panel.
      */
     onNodeHover?: (node: ForceGraphNode | null) => void;
+    /**
+     * Reconciliation merge animation (CLIENT-ONLY — driven by `$effect`, which
+     * never runs during SSR, so no merge is animated or resolved server-side).
+     *
+     * Pass a `{ id, from, into }` where both `from` and `into` exist in `nodes`:
+     * the `from` node animates toward the position of `into` while fading out
+     * (the node and its incident edges), then `onMergeComplete(pair)` fires
+     * exactly ONCE for that `id`. Purely visual — the component never mutates the
+     * data; the consumer removes `from` from `nodes` after the callback.
+     *
+     * Idempotent on `id`: re-passing the SAME `id` (even with a new identity for
+     * the object) is a no-op — the animation/callback are not replayed. Passing a
+     * NEW `id` (re)plays the merge, even for the same `from`/`into` pair. After
+     * completion the `from` node stays MASKED (hidden) until the consumer removes
+     * it or a new `mergePair` is supplied, so it does not flash back when the
+     * prop returns to null. Pass null (the default) for no merge in flight.
+     */
+    mergePair?: {
+        id: string;
+        from: string;
+        into: string;
+    } | null;
+    /**
+     * Fired once the merge animation for the current `mergePair` completes (or
+     * immediately, on a microtask, under reduced motion). Fires at most ONCE per
+     * `id`. Receives the same pair so the consumer can drop `from` from the data.
+     */
+    onMergeComplete?: (pair: {
+        id: string;
+        from: string;
+        into: string;
+    }) => void;
     class?: string;
 };
 declare const ForceGraph: import("svelte").Component<ForceGraphProps, {}, "">;

package/dist/ForceGraph.svelte.d.ts.map

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

package/dist/Popper.svelte

@@ -0,0 +1,317 @@
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+  import Portal from "./Portal.svelte";
+
+  export type PopperStrategy = "absolute" | "fixed";
+
+  export type PopperPlacement =
+    | "top"
+    | "bottom"
+    | "left"
+    | "right"
+    | "top-start"
+    | "top-end"
+    | "bottom-start"
+    | "bottom-end"
+    | "left-start"
+    | "left-end"
+    | "right-start"
+    | "right-end";
+
+  export type PopperSide = "top" | "bottom" | "left" | "right";
+  export type PopperAlign = "start" | "center" | "end";
+
+  export type PopperProps = {
+    /** Reference element the panel is positioned against. */
+    anchor: HTMLElement | null;
+    /** Controlled open state. When false (or no anchor) nothing renders. */
+    open?: boolean;
+    /** Wanted placement of the panel relative to the anchor. */
+    placement?: PopperPlacement;
+    /** Main-axis distance (px) between the anchor and the panel. */
+    offset?: number;
+    /** Flip to the opposite side when the panel would overflow the viewport. */
+    flip?: boolean;
+    /** Shift along the cross axis to keep the panel within the viewport. */
+    shift?: boolean;
+    /** Expose a positioned arrow element. */
+    arrow?: boolean;
+    /** CSS positioning strategy. */
+    strategy?: PopperStrategy;
+    /** Render the panel into `document.body` via a Portal. */
+    portal?: boolean;
+    /** Optional class applied to the floating panel. */
+    class?: string;
+    /** Notified whenever the resolved placement changes (after flip). */
+    onPlacementChange?: (placement: PopperPlacement) => void;
+    children?: Snippet;
+  };
+
+  /** Split a placement into its side and (optional) alignment. */
+  export function splitPlacement(placement: PopperPlacement): {
+    side: PopperSide;
+    align: PopperAlign;
+  } {
+    const [side, align] = placement.split("-") as [PopperSide, PopperAlign?];
+    return { side, align: align ?? "center" };
+  }
+
+  /** Recompose a side + alignment into a placement string. */
+  export function joinPlacement(side: PopperSide, align: PopperAlign): PopperPlacement {
+    return (align === "center" ? side : `${side}-${align}`) as PopperPlacement;
+  }
+
+  const OPPOSITE: Record<PopperSide, PopperSide> = {
+    top: "bottom",
+    bottom: "top",
+    left: "right",
+    right: "left"
+  };
+
+  export type Rect = {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+  };
+
+  /**
+   * Pure geometry: compute the panel coordinates (in the chosen strategy's
+   * coordinate space) given the anchor rect, the panel size, and options.
+   * Returns the resolved placement (after flip) and the top/left coordinates,
+   * plus the arrow offset along the main edge.
+   *
+   * Coordinates are viewport-relative; callers add scroll offsets for the
+   * `absolute` strategy. No DOM access here — safe to unit test.
+   */
+  export function computePosition(
+    anchorRect: Rect,
+    panelWidth: number,
+    panelHeight: number,
+    options: {
+      placement: PopperPlacement;
+      offset: number;
+      flip: boolean;
+      shift: boolean;
+      viewportWidth: number;
+      viewportHeight: number;
+    }
+  ): { placement: PopperPlacement; top: number; left: number } {
+    const { offset, flip, shift, viewportWidth, viewportHeight } = options;
+    let { side, align } = splitPlacement(options.placement);
+
+    const place = (s: PopperSide, a: PopperAlign) => {
+      let top = 0;
+      let left = 0;
+      if (s === "top" || s === "bottom") {
+        top = s === "top" ? anchorRect.top - panelHeight - offset : anchorRect.bottom + offset;
+        if (a === "start") left = anchorRect.left;
+        else if (a === "end") left = anchorRect.right - panelWidth;
+        else left = anchorRect.left + anchorRect.width / 2 - panelWidth / 2;
+      } else {
+        left = s === "left" ? anchorRect.left - panelWidth - offset : anchorRect.right + offset;
+        if (a === "start") top = anchorRect.top;
+        else if (a === "end") top = anchorRect.bottom - panelHeight;
+        else top = anchorRect.top + anchorRect.height / 2 - panelHeight / 2;
+      }
+      return { top, left };
+    };
+
+    // Flip: if the panel overflows on the chosen side, try the opposite side.
+    if (flip) {
+      const candidate = place(side, align);
+      const overflows =
+        (side === "top" && candidate.top < 0) ||
+        (side === "bottom" && candidate.top + panelHeight > viewportHeight) ||
+        (side === "left" && candidate.left < 0) ||
+        (side === "right" && candidate.left + panelWidth > viewportWidth);
+      if (overflows) {
+        const flipped = OPPOSITE[side];
+        const flippedPos = place(flipped, align);
+        const flippedOverflows =
+          (flipped === "top" && flippedPos.top < 0) ||
+          (flipped === "bottom" && flippedPos.top + panelHeight > viewportHeight) ||
+          (flipped === "left" && flippedPos.left < 0) ||
+          (flipped === "right" && flippedPos.left + panelWidth > viewportWidth);
+        // Only flip if the opposite side fits better.
+        if (!flippedOverflows) side = flipped;
+      }
+    }
+
+    let { top, left } = place(side, align);
+
+    // Shift: clamp along the cross axis so the panel stays in the viewport.
+    if (shift) {
+      if (side === "top" || side === "bottom") {
+        const max = Math.max(0, viewportWidth - panelWidth);
+        left = Math.min(Math.max(0, left), max);
+      } else {
+        const max = Math.max(0, viewportHeight - panelHeight);
+        top = Math.min(Math.max(0, top), max);
+      }
+    }
+
+    return { placement: joinPlacement(side, align), top, left };
+  }
+</script>
+
+<script lang="ts">
+  let {
+    anchor,
+    open = false,
+    placement = "bottom",
+    offset = 8,
+    flip = true,
+    shift = true,
+    arrow = false,
+    strategy = "absolute",
+    portal = true,
+    class: className,
+    onPlacementChange,
+    children
+  }: PopperProps = $props();
+
+  let panel = $state<HTMLDivElement | undefined>();
+  let top = $state(0);
+  let left = $state(0);
+  // Placement actually applied (may differ from the requested `placement`
+  // after a flip). Initialised lazily; defaults to the requested placement.
+  let flippedPlacement = $state<PopperPlacement | undefined>();
+  const resolvedPlacement = $derived(flippedPlacement ?? placement);
+
+  function reposition() {
+    if (typeof window === "undefined") return;
+    if (!open || !anchor || !panel) return;
+
+    const anchorRect = anchor.getBoundingClientRect();
+    const panelRect = panel.getBoundingClientRect();
+
+    const result = computePosition(
+      {
+        top: anchorRect.top,
+        left: anchorRect.left,
+        right: anchorRect.right,
+        bottom: anchorRect.bottom,
+        width: anchorRect.width,
+        height: anchorRect.height
+      },
+      panelRect.width,
+      panelRect.height,
+      {
+        placement,
+        offset,
+        flip,
+        shift,
+        viewportWidth: window.innerWidth,
+        viewportHeight: window.innerHeight
+      }
+    );
+
+    // `absolute` is positioned relative to the document, so add scroll offsets.
+    // `fixed` is viewport-relative, so coordinates are used as-is.
+    if (strategy === "absolute") {
+      top = result.top + window.scrollY;
+      left = result.left + window.scrollX;
+    } else {
+      top = result.top;
+      left = result.left;
+    }
+
+    if (result.placement !== resolvedPlacement) {
+      flippedPlacement = result.placement;
+      onPlacementChange?.(result.placement);
+    }
+  }
+
+  $effect(() => {
+    // Client-only: register listeners and compute the position once mounted.
+    if (typeof window === "undefined") return;
+    if (!open || !anchor || !panel) return;
+
+    reposition();
+
+    const onScroll = () => reposition();
+    const onResize = () => reposition();
+    window.addEventListener("scroll", onScroll, true);
+    window.addEventListener("resize", onResize);
+
+    return () => {
+      window.removeEventListener("scroll", onScroll, true);
+      window.removeEventListener("resize", onResize);
+    };
+  });
+
+  const panelStyle = () =>
+    `position: ${strategy}; top: ${top}px; left: ${left}px;`;
+  const panelSide = () => splitPlacement(resolvedPlacement).side;
+</script>
+
+{#snippet floating()}
+  <div
+    bind:this={panel}
+    class={className ? `st-popper ${className}` : "st-popper"}
+    data-popper-placement={resolvedPlacement}
+    style={panelStyle()}
+  >
+    {@render children?.()}
+    {#if arrow}
+      <span
+        class="st-popper__arrow"
+        data-popper-side={panelSide()}
+        aria-hidden="true"
+      ></span>
+    {/if}
+  </div>
+{/snippet}
+
+{#if open && anchor}
+  {#if portal}
+    <Portal target="body">
+      {@render floating()}
+    </Portal>
+  {:else}
+    {@render floating()}
+  {/if}
+{/if}
+
+<style>
+  .st-popper {
+    z-index: var(--st-component-popover-zIndex, 80);
+  }
+
+  .st-popper__arrow {
+    position: absolute;
+    width: 0.5rem;
+    height: 0.5rem;
+    background: inherit;
+    border: inherit;
+    transform: rotate(45deg);
+    pointer-events: none;
+  }
+
+  .st-popper__arrow[data-popper-side="bottom"] {
+    top: -0.25rem;
+    left: 50%;
+    margin-left: -0.25rem;
+  }
+
+  .st-popper__arrow[data-popper-side="top"] {
+    bottom: -0.25rem;
+    left: 50%;
+    margin-left: -0.25rem;
+  }
+
+  .st-popper__arrow[data-popper-side="right"] {
+    left: -0.25rem;
+    top: 50%;
+    margin-top: -0.25rem;
+  }
+
+  .st-popper__arrow[data-popper-side="left"] {
+    right: -0.25rem;
+    top: 50%;
+    margin-top: -0.25rem;
+  }
+</style>