@sentropic/design-system-svelte 0.16.0 → 0.18.0

package/dist/GaugeChart.svelte.d.ts

@@ -0,0 +1,36 @@
+export type GaugeChartTone = "neutral" | "info" | "success" | "warning" | "error" | "category1" | "category2" | "category3" | "category4" | "category5" | "category6" | "category7" | "category8";
+/**
+ * Seuil de coloration. La bande s'étend depuis `value` (ou le minimum)
+ * jusqu'au seuil suivant (ou le maximum). `tone` choisit la couleur.
+ */
+export type GaugeChartThreshold = {
+    value: number;
+    tone: GaugeChartTone;
+};
+export type GaugeChartFormat = "number" | "percent";
+type GaugeChartProps = {
+    value: number;
+    min?: number;
+    max?: number;
+    /** Bandes colorées sur la piste. Triées par `value` croissante. */
+    thresholds?: GaugeChartThreshold[];
+    /** Libellé décrivant la jauge (a11y + texte sous la valeur). */
+    label?: string;
+    /** Format de la valeur centrale. */
+    format?: GaugeChartFormat;
+    /** Suffixe d'unité (ignoré pour `percent`). */
+    unit?: string;
+    /** Diamètre du SVG. */
+    size?: number;
+    /** Épaisseur de l'arc. */
+    thickness?: number;
+    /** Angle de départ en degrés (0 = est, sens horaire). */
+    startAngle?: number;
+    /** Angle de fin en degrés. */
+    endAngle?: number;
+    class?: string;
+};
+declare const GaugeChart: import("svelte").Component<GaugeChartProps, {}, "">;
+type GaugeChart = ReturnType<typeof GaugeChart>;
+export default GaugeChart;
+//# sourceMappingURL=GaugeChart.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GaugeChart.svelte.d.ts","sourceRoot":"","sources":["../src/lib/GaugeChart.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,cAAc,GACtB,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GACpD,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GACrD,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAMpD,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA2JJ,QAAA,MAAM,UAAU,qDAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/KpiCard.svelte

@@ -0,0 +1,318 @@
+<script lang="ts" module>
+  export type KpiCardSize = "sm" | "md" | "lg";
+  export type KpiCardTrend = "up" | "down" | "flat";
+  export type KpiCardFormat = "number" | "currency" | "percent";
+  export type KpiCardDeltaFormat = "percent" | "absolute";
+  export type KpiCardTone =
+    | "category1"
+    | "category2"
+    | "category3"
+    | "category4"
+    | "category5"
+    | "category6"
+    | "category7"
+    | "category8";
+</script>
+
+<script lang="ts">
+  import type { HTMLAttributes } from "svelte/elements";
+  import Sparkline from "./Sparkline.svelte";
+
+  type KpiCardProps = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+    /** Valeur principale affichée en grand. */
+    value: number | string;
+    /** Étiquette de l'indicateur (ex. « Revenu mensuel »). */
+    label: string;
+    /** Variation par rapport à la période précédente. */
+    delta?: number;
+    /** Comment exprimer le delta : en pourcentage ou en valeur absolue. */
+    deltaFormat?: KpiCardDeltaFormat;
+    /** Tendance ; déduite du signe du delta si absente. */
+    trend?: KpiCardTrend;
+    /** Formatage de la valeur principale via Intl.NumberFormat. */
+    format?: KpiCardFormat;
+    /** Unité suffixée à la valeur (ex. « ms », « €/mois »). */
+    unit?: string;
+    /** Code devise ISO 4217 pour format="currency" (défaut EUR). */
+    currency?: string;
+    /** Locale BCP 47 pour le formatage des nombres (défaut undefined = locale du runtime). */
+    locale?: string;
+    /** Mini-graphique de tendance optionnel. */
+    sparkline?: number[];
+    size?: KpiCardSize;
+    /** Couleur catégorielle pour l'accent (bordure de gauche). */
+    tone?: KpiCardTone;
+    class?: string;
+  };
+
+  let {
+    value,
+    label,
+    delta,
+    deltaFormat = "percent",
+    trend,
+    format = "number",
+    unit,
+    currency = "EUR",
+    locale,
+    sparkline,
+    size = "md",
+    tone,
+    class: className,
+    ...rest
+  }: KpiCardProps = $props();
+
+  const resolvedTrend = $derived<KpiCardTrend | undefined>(
+    trend ?? (delta == null ? undefined : delta > 0 ? "up" : delta < 0 ? "down" : "flat")
+  );
+
+  const formattedValue = $derived.by(() => {
+    if (typeof value === "string") {
+      return value;
+    }
+    if (format === "currency") {
+      return new Intl.NumberFormat(locale, { style: "currency", currency }).format(value);
+    }
+    if (format === "percent") {
+      return new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 2 }).format(
+        value
+      );
+    }
+    return new Intl.NumberFormat(locale).format(value);
+  });
+
+  const formattedDelta = $derived.by(() => {
+    if (delta == null) {
+      return undefined;
+    }
+    const sign = delta > 0 ? "+" : "";
+    if (deltaFormat === "percent") {
+      const pct = new Intl.NumberFormat(locale, {
+        style: "percent",
+        maximumFractionDigits: 1
+      }).format(delta);
+      return `${sign}${pct}`;
+    }
+    return `${sign}${new Intl.NumberFormat(locale).format(delta)}`;
+  });
+
+  /** Le sparkline emprunte la couleur sémantique de la tendance. */
+  const sparklineTone = $derived(
+    resolvedTrend === "up" ? "success" : resolvedTrend === "down" ? "error" : "neutral"
+  );
+
+  const arrow = $derived(
+    resolvedTrend === "up" ? "M3 8.5 7 4l4 4.5" : resolvedTrend === "down" ? "M3 5.5 7 10l4-4.5" : "M3 7h8"
+  );
+
+  const trendLabel = $derived(
+    resolvedTrend === "up"
+      ? "en hausse"
+      : resolvedTrend === "down"
+        ? "en baisse"
+        : resolvedTrend === "flat"
+          ? "stable"
+          : undefined
+  );
+
+  const ariaLabel = $derived(
+    [label, formattedValue, unit, formattedDelta && `${formattedDelta} ${trendLabel ?? ""}`.trim()]
+      .filter(Boolean)
+      .join(", ")
+  );
+
+  const classes = $derived(
+    [
+      "st-kpiCard",
+      `st-kpiCard--${size}`,
+      tone && `st-kpiCard--${tone}`,
+      tone && "st-kpiCard--toned",
+      className
+    ]
+      .filter(Boolean)
+      .join(" ")
+  );
+</script>
+
+<article {...rest} class={classes} role="group" aria-label={ariaLabel}>
+  <p class="st-kpiCard__label">{label}</p>
+
+  <p class="st-kpiCard__value">
+    <span class="st-kpiCard__number">{formattedValue}</span>
+    {#if unit}
+      <span class="st-kpiCard__unit">{unit}</span>
+    {/if}
+  </p>
+
+  {#if formattedDelta || sparkline}
+    <div class="st-kpiCard__footer">
+      {#if formattedDelta}
+        <span
+          class="st-kpiCard__delta st-kpiCard__delta--{resolvedTrend ?? 'flat'}"
+          aria-hidden="true"
+        >
+          <svg
+            class="st-kpiCard__arrow"
+            width="14"
+            height="14"
+            viewBox="0 0 14 14"
+            aria-hidden="true"
+            focusable="false"
+          >
+            <path
+              d={arrow}
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.75"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+            />
+          </svg>
+          <span class="st-kpiCard__deltaValue">{formattedDelta}</span>
+        </span>
+      {/if}
+
+      {#if sparkline && sparkline.length > 0}
+        <Sparkline
+          class="st-kpiCard__sparkline"
+          data={sparkline}
+          tone={sparklineTone}
+          area
+        />
+      {/if}
+    </div>
+  {/if}
+</article>
+
+<style>
+  .st-kpiCard {
+    background: var(--st-component-card-background, var(--st-semantic-surface-raised));
+    border-width: var(--st-component-card-anatomy-shape-borderWidth, 1px);
+    border-style: var(--st-component-card-anatomy-shape-borderStyle, solid);
+    border-color: var(--st-component-card-border, var(--st-semantic-border-subtle));
+    border-radius: var(--st-component-card-anatomy-shape-radius, 0.5rem);
+    box-shadow: var(--st-component-card-shadow, 0 1px 2px rgb(15 23 42 / 0.08));
+    color: var(--st-semantic-text-primary);
+    display: flex;
+    flex-direction: column;
+    gap: var(--st-spacing-2, 0.5rem);
+    padding: var(--st-spacing-4, 1rem);
+  }
+
+  .st-kpiCard--sm {
+    gap: var(--st-spacing-1, 0.25rem);
+    padding: var(--st-spacing-3, 0.75rem);
+  }
+
+  .st-kpiCard--lg {
+    gap: var(--st-spacing-3, 0.75rem);
+    padding: var(--st-spacing-6, 1.5rem);
+  }
+
+  /* Accent catégoriel : liseré coloré à gauche. */
+  .st-kpiCard--toned {
+    border-inline-start-width: var(--st-spacing-1, 0.25rem);
+  }
+
+  .st-kpiCard__label {
+    color: var(--st-semantic-text-secondary);
+    font-size: 0.8125rem;
+    font-weight: 500;
+    line-height: 1.25;
+    margin: 0;
+  }
+
+  .st-kpiCard--lg .st-kpiCard__label {
+    font-size: 0.875rem;
+  }
+
+  .st-kpiCard__value {
+    align-items: baseline;
+    color: var(--st-semantic-text-primary);
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--st-spacing-1, 0.25rem);
+    margin: 0;
+  }
+
+  .st-kpiCard__number {
+    font-size: 1.5rem;
+    font-weight: 700;
+    letter-spacing: -0.01em;
+    line-height: 1.1;
+  }
+
+  .st-kpiCard--sm .st-kpiCard__number {
+    font-size: 1.25rem;
+  }
+
+  .st-kpiCard--lg .st-kpiCard__number {
+    font-size: 2.25rem;
+  }
+
+  .st-kpiCard__unit {
+    color: var(--st-semantic-text-secondary);
+    font-size: 0.875rem;
+    font-weight: 500;
+  }
+
+  .st-kpiCard__footer {
+    align-items: center;
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--st-spacing-3, 0.75rem);
+    justify-content: space-between;
+  }
+
+  .st-kpiCard__delta {
+    align-items: center;
+    display: inline-flex;
+    font-size: 0.8125rem;
+    font-weight: 600;
+    gap: var(--st-spacing-1, 0.25rem);
+    line-height: 1;
+  }
+
+  .st-kpiCard__arrow {
+    display: block;
+    flex: 0 0 auto;
+  }
+
+  .st-kpiCard__delta--up {
+    color: var(--st-semantic-feedback-success);
+  }
+
+  .st-kpiCard__delta--down {
+    color: var(--st-semantic-feedback-error);
+  }
+
+  .st-kpiCard__delta--flat {
+    color: var(--st-semantic-text-secondary);
+  }
+
+  /* Liserés catégoriels — alignés sur la palette data des autres composants. */
+  .st-kpiCard--category1 {
+    border-inline-start-color: var(--st-semantic-data-category1);
+  }
+  .st-kpiCard--category2 {
+    border-inline-start-color: var(--st-semantic-data-category2);
+  }
+  .st-kpiCard--category3 {
+    border-inline-start-color: var(--st-semantic-data-category3);
+  }
+  .st-kpiCard--category4 {
+    border-inline-start-color: var(--st-semantic-data-category4);
+  }
+  .st-kpiCard--category5 {
+    border-inline-start-color: var(--st-semantic-data-category5);
+  }
+  .st-kpiCard--category6 {
+    border-inline-start-color: var(--st-semantic-data-category6);
+  }
+  .st-kpiCard--category7 {
+    border-inline-start-color: var(--st-semantic-data-category7);
+  }
+  .st-kpiCard--category8 {
+    border-inline-start-color: var(--st-semantic-data-category8);
+  }
+</style>

package/dist/KpiCard.svelte.d.ts

@@ -0,0 +1,36 @@
+export type KpiCardSize = "sm" | "md" | "lg";
+export type KpiCardTrend = "up" | "down" | "flat";
+export type KpiCardFormat = "number" | "currency" | "percent";
+export type KpiCardDeltaFormat = "percent" | "absolute";
+export type KpiCardTone = "category1" | "category2" | "category3" | "category4" | "category5" | "category6" | "category7" | "category8";
+import type { HTMLAttributes } from "svelte/elements";
+type KpiCardProps = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+    /** Valeur principale affichée en grand. */
+    value: number | string;
+    /** Étiquette de l'indicateur (ex. « Revenu mensuel »). */
+    label: string;
+    /** Variation par rapport à la période précédente. */
+    delta?: number;
+    /** Comment exprimer le delta : en pourcentage ou en valeur absolue. */
+    deltaFormat?: KpiCardDeltaFormat;
+    /** Tendance ; déduite du signe du delta si absente. */
+    trend?: KpiCardTrend;
+    /** Formatage de la valeur principale via Intl.NumberFormat. */
+    format?: KpiCardFormat;
+    /** Unité suffixée à la valeur (ex. « ms », « €/mois »). */
+    unit?: string;
+    /** Code devise ISO 4217 pour format="currency" (défaut EUR). */
+    currency?: string;
+    /** Locale BCP 47 pour le formatage des nombres (défaut undefined = locale du runtime). */
+    locale?: string;
+    /** Mini-graphique de tendance optionnel. */
+    sparkline?: number[];
+    size?: KpiCardSize;
+    /** Couleur catégorielle pour l'accent (bordure de gauche). */
+    tone?: KpiCardTone;
+    class?: string;
+};
+declare const KpiCard: import("svelte").Component<KpiCardProps, {}, "">;
+type KpiCard = ReturnType<typeof KpiCard>;
+export default KpiCard;
+//# sourceMappingURL=KpiCard.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"KpiCard.svelte.d.ts","sourceRoot":"","sources":["../src/lib/KpiCard.svelte.ts"],"names":[],"mappings":"AAGE,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAC7C,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAClD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,UAAU,CAAC;AACxD,MAAM,MAAM,WAAW,GACnB,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAGlB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIpD,KAAK,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,GAAG;IAC/D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAiIJ,QAAA,MAAM,OAAO,kDAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/Popper.svelte

@@ -44,6 +44,23 @@
     class?: string;
     /** Notified whenever the resolved placement changes (after flip). */
     onPlacementChange?: (placement: PopperPlacement) => void;
+    /**
+     * (a11y, opt-in) When true, traps keyboard focus inside the panel while it
+     * is open (Tab cycles through focusable children; Shift+Tab cycles backward).
+     * Intended for modal overlays built on top of Popper. Non-modal usage (menus,
+     * tooltips) should leave this false (default) to keep the natural tab order.
+     */
+    trapFocus?: boolean;
+    /**
+     * (a11y) When true (default when open), pressing Escape calls `onClose` so
+     * the consumer can set `open = false`. Set to false to suppress this behavior.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Called when the panel requests closing (Escape key, or future outside-click).
+     * The consumer is responsible for updating `open` in response.
+     */
+    onClose?: () => void;
     children?: Snippet;
   };
 
@@ -158,6 +175,8 @@
 </script>
 
 <script lang="ts">
+  import { untrack } from "svelte";
+
   let {
     anchor,
     open = false,
@@ -170,6 +189,9 @@
     portal = true,
     class: className,
     onPlacementChange,
+    trapFocus = false,
+    closeOnEscape = true,
+    onClose,
     children
   }: PopperProps = $props();
 
@@ -243,17 +265,152 @@
     };
   });
 
+  // ─── a11y: focus management ────────────────────────────────────────────────
+  // Capture the element that had focus before the panel opened so we can
+  // restore it when the panel closes (only when trapFocus is active).
+  // SSR-safe (guarded by typeof window).
+  // Use a plain variable (not $state) so reads inside the effect are not
+  // tracked and don't cause the effect to re-run on every preFocusEl write.
+  let preFocusEl: HTMLElement | null = null;
+
+  $effect(() => {
+    if (typeof window === "undefined") return;
+    if (open && anchor) {
+      untrack(() => {
+        // Snapshot the active element at open time only when trapFocus is active,
+        // so restoreFocus doesn't steal focus on non-modal usage.
+        if (trapFocus) {
+          preFocusEl = document.activeElement as HTMLElement | null;
+        }
+      });
+    } else {
+      // Panel just closed: restore focus only if trapFocus was active and the
+      // original element is still connected to the DOM.
+      untrack(() => {
+        if (
+          trapFocus &&
+          preFocusEl &&
+          typeof preFocusEl.focus === "function" &&
+          document.contains(preFocusEl)
+        ) {
+          preFocusEl.focus();
+        }
+        preFocusEl = null;
+      });
+    }
+  });
+
+  /** Returns all keyboard-focusable children of `container`. */
+  function getFocusable(container: HTMLElement): HTMLElement[] {
+    if (typeof window === "undefined") return [];
+    return Array.from(
+      container.querySelectorAll<HTMLElement>(
+        'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),' +
+        'textarea:not([disabled]),[tabindex]:not([tabindex="-1"]),[contenteditable="true"]'
+      )
+    ).filter((el) => !el.closest("[disabled]"));
+  }
+
+  // ─── a11y: move focus into the panel on open (trapFocus only) ─────────────
+  $effect(() => {
+    if (typeof window === "undefined") return;
+    if (!open || !trapFocus || !panel) return;
+    // Wait for the panel to be mounted before moving focus.
+    untrack(() => {
+      const focusable = getFocusable(panel!);
+      if (focusable.length > 0) {
+        focusable[0].focus();
+      } else {
+        // If no focusable children, focus the panel itself so Escape works.
+        panel!.focus();
+      }
+    });
+  });
+
+  // ─── a11y: recapture focus that escapes the trap (focusin on document) ─────
+  $effect(() => {
+    if (typeof window === "undefined") return;
+    if (!open || !trapFocus) return;
+
+    function handleFocusIn(e: FocusEvent) {
+      if (!panel) return;
+      const target = e.target as Node | null;
+      // If focus landed outside the panel, bring it back to the first focusable.
+      if (target && !panel.contains(target)) {
+        const focusable = getFocusable(panel);
+        if (focusable.length > 0) {
+          focusable[0].focus();
+        } else {
+          panel.focus();
+        }
+      }
+    }
+
+    document.addEventListener("focusin", handleFocusIn);
+    return () => {
+      document.removeEventListener("focusin", handleFocusIn);
+    };
+  });
+
+  // ─── a11y: Escape on document (closeOnEscape) ─────────────────────────────
+  // Listen on document so the Escape shortcut works even when focus is outside
+  // the panel (e.g. before the first Tab, or in an edge case where focus escaped).
+  $effect(() => {
+    if (typeof window === "undefined") return;
+    if (!open || !closeOnEscape) return;
+
+    function handleDocKeydown(e: KeyboardEvent) {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onClose?.();
+      }
+    }
+
+    document.addEventListener("keydown", handleDocKeydown);
+    return () => {
+      document.removeEventListener("keydown", handleDocKeydown);
+    };
+  });
+
+  /** Keyboard handler attached to the panel for Tab-trap cycling. */
+  function handlePanelKeydown(e: KeyboardEvent) {
+    if (typeof window === "undefined") return;
+
+    // Tab trap: cycle focus within the panel.
+    if (e.key === "Tab" && trapFocus && panel) {
+      const focusable = getFocusable(panel);
+      if (focusable.length === 0) { e.preventDefault(); return; }
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (e.shiftKey) {
+        if (document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        }
+      } else {
+        if (document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    }
+  }
+
   const panelStyle = () =>
     `position: ${strategy}; top: ${top}px; left: ${left}px;`;
   const panelSide = () => splitPlacement(resolvedPlacement).side;
 </script>
 
 {#snippet floating()}
+  <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <!-- svelte-ignore a11y_no_static_element_interactions -->
   <div
     bind:this={panel}
     class={className ? `st-popper ${className}` : "st-popper"}
     data-popper-placement={resolvedPlacement}
     style={panelStyle()}
+    tabindex={trapFocus ? -1 : undefined}
+    onkeydown={trapFocus ? handlePanelKeydown : undefined}
   >
     {@render children?.()}
     {#if arrow}

package/dist/Popper.svelte.d.ts

@@ -26,6 +26,23 @@ export type PopperProps = {
     class?: string;
     /** Notified whenever the resolved placement changes (after flip). */
     onPlacementChange?: (placement: PopperPlacement) => void;
+    /**
+     * (a11y, opt-in) When true, traps keyboard focus inside the panel while it
+     * is open (Tab cycles through focusable children; Shift+Tab cycles backward).
+     * Intended for modal overlays built on top of Popper. Non-modal usage (menus,
+     * tooltips) should leave this false (default) to keep the natural tab order.
+     */
+    trapFocus?: boolean;
+    /**
+     * (a11y) When true (default when open), pressing Escape calls `onClose` so
+     * the consumer can set `open = false`. Set to false to suppress this behavior.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Called when the panel requests closing (Escape key, or future outside-click).
+     * The consumer is responsible for updating `open` in response.
+     */
+    onClose?: () => void;
     children?: Snippet;
 };
 /** Split a placement into its side and (optional) alignment. */

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

@@ -1 +1 @@
-{"version":3,"file":"Popper.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Popper.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,WAAW,GACX,SAAS,GACT,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAC7D,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG;IACxB,yDAAyD;IACzD,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,GAAG;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB,CAGA;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CAEnF;AASD,MAAM,MAAM,IAAI,GAAG;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,IAAI,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IACP,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GACA;IAAE,SAAS,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwD3D;AAsHH,QAAA,MAAM,MAAM,iDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}
+{"version":3,"file":"Popper.svelte.d.ts","sourceRoot":"","sources":["../src/lib/Popper.svelte.ts"],"names":[],"mappings":"AAGE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,WAAW,GACX,SAAS,GACT,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAC7D,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG;IACxB,yDAAyD;IACzD,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4DAA4D;IAC5D,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;IACzD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,GAAG;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;CACpB,CAGA;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,GAAG,eAAe,CAEnF;AASD,MAAM,MAAM,IAAI,GAAG;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,IAAI,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE;IACP,SAAS,EAAE,eAAe,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,GACA;IAAE,SAAS,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwD3D;AAmQH,QAAA,MAAM,MAAM,iDAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}