@supersoniks/concorde 5.0.0 → 5.0.2

package/src/core/utils/positioning.ts

@@ -0,0 +1,183 @@
+import HTML, { SearchableDomElement } from "./HTML";
+
+export type FloatingSide = "top" | "right" | "bottom" | "left";
+export type FloatingAlign = "start" | "center" | "end";
+export type FloatingPlacement =
+  | FloatingSide
+  | `${FloatingSide}-${FloatingAlign}`;
+
+const SIDES: readonly string[] = ["top", "right", "bottom", "left"];
+const ALIGNS: readonly string[] = ["start", "center", "end"];
+
+/** Découpe `"côté-alignement"` ; une valeur inconnue retombe sur le défaut. */
+export function parsePlacement(
+  placement: string | undefined,
+  defaultSide: FloatingSide,
+  defaultAlign: FloatingAlign,
+): { side: FloatingSide; align: FloatingAlign } {
+  const [side, align] = (placement ?? "").split("-");
+  return {
+    side: SIDES.includes(side) ? (side as FloatingSide) : defaultSide,
+    align: ALIGNS.includes(align) ? (align as FloatingAlign) : defaultAlign,
+  };
+}
+
+export type FloatingBounds = {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+};
+
+type Rect = Pick<DOMRect, "left" | "top" | "right" | "bottom" | "width" | "height">;
+type Size = Pick<DOMRect, "width" | "height">;
+
+export const supportsPopover = "popover" in HTMLElement.prototype;
+
+const OPPOSITE_SIDE: Record<FloatingSide, FloatingSide> = {
+  top: "bottom",
+  bottom: "top",
+  left: "right",
+  right: "left",
+};
+
+/**
+ * Zone dans laquelle un élément flottant doit rester visible :
+ * le viewport, restreint par le premier ancêtre qui scrolle ou clippe `node`.
+ */
+export function getFloatingBounds(
+  node: SearchableDomElement,
+  padding = 0,
+): FloatingBounds {
+  const clipRect = (
+    HTML.getScrollableAncestor(node) as HTMLElement | null
+  )?.getBoundingClientRect();
+
+  // `||` et non `??` : un bord à 0 (ancêtre non rendu) retombe sur le viewport, comme historiquement dans sonic-pop.
+  return {
+    minX: Math.max(0, clipRect?.left || 0) + padding,
+    minY: Math.max(0, clipRect?.top || 0) + padding,
+    maxX:
+      Math.min(window.innerWidth, clipRect?.right || window.innerWidth) -
+      padding,
+    maxY:
+      Math.min(window.innerHeight, clipRect?.bottom || window.innerHeight) -
+      padding,
+  };
+}
+
+function alignOnAxis(
+  start: number,
+  length: number,
+  floatingLength: number,
+  align: FloatingAlign,
+) {
+  if (align === "start") return start;
+  if (align === "end") return start + length - floatingLength;
+  return start + (length - floatingLength) / 2;
+}
+
+function placeOnSide(
+  anchor: Rect,
+  floating: Size,
+  side: FloatingSide,
+  align: FloatingAlign,
+  gap: number,
+) {
+  switch (side) {
+    case "top":
+      return {
+        x: alignOnAxis(anchor.left, anchor.width, floating.width, align),
+        y: anchor.top - floating.height - gap,
+      };
+    case "bottom":
+      return {
+        x: alignOnAxis(anchor.left, anchor.width, floating.width, align),
+        y: anchor.bottom + gap,
+      };
+    case "left":
+      return {
+        x: anchor.left - floating.width - gap,
+        y: alignOnAxis(anchor.top, anchor.height, floating.height, align),
+      };
+    case "right":
+      return {
+        x: anchor.right + gap,
+        y: alignOnAxis(anchor.top, anchor.height, floating.height, align),
+      };
+    default:
+      return { x: anchor.left, y: anchor.top };
+  }
+}
+
+function overflowsSide(
+  position: { x: number; y: number },
+  floating: Size,
+  side: FloatingSide,
+  bounds: FloatingBounds,
+) {
+  switch (side) {
+    case "top":
+      return position.y < bounds.minY;
+    case "bottom":
+      return position.y + floating.height > bounds.maxY;
+    case "left":
+      return position.x < bounds.minX;
+    case "right":
+      return position.x + floating.width > bounds.maxX;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Position (coordonnées viewport) d'un élément flottant accolé à `anchor` :
+ * bascule sur le côté opposé s'il déborde, puis le contraint dans `bounds`.
+ * S'il est plus grand que `bounds`, c'est le bord bas / droit qui l'emporte.
+ */
+export function computeFloatingPosition({
+  anchor,
+  floating,
+  side,
+  align = "center",
+  gap = 0,
+  bounds,
+}: {
+  anchor: Rect;
+  floating: Size;
+  side: FloatingSide;
+  align?: FloatingAlign;
+  gap?: number;
+  bounds: FloatingBounds;
+}) {
+  let placedSide = side;
+  let position = placeOnSide(anchor, floating, placedSide, align, gap);
+
+  if (overflowsSide(position, floating, placedSide, bounds)) {
+    placedSide = OPPOSITE_SIDE[placedSide];
+    position = placeOnSide(anchor, floating, placedSide, align, gap);
+  }
+
+  return {
+    side: placedSide,
+    x: Math.min(
+      Math.max(position.x, bounds.minX),
+      bounds.maxX - floating.width,
+    ),
+    y: Math.min(
+      Math.max(position.y, bounds.minY),
+      bounds.maxY - floating.height,
+    ),
+  };
+}
+
+/** Appelle `callback` à chaque frame ; renvoie la fonction d'arrêt. */
+export function startFrameLoop(callback: () => void) {
+  let frame = 0;
+  const tick = () => {
+    callback();
+    frame = requestAnimationFrame(tick);
+  };
+  tick();
+  return () => cancelAnimationFrame(frame);
+}

package/src/directives.ts

@@ -1,6 +1,5 @@
 import * as directives from "@supersoniks/concorde/core/directives/DataProvider";
 import {dp as pubDp, dataProvider as pubDataProvider, get as pubGet, set as pubSet} from "@supersoniks/concorde/core/utils/PublisherProxy";
-import type {DirectiveResult} from "lit/async-directive.js";
 
 import {ConcordeWindow} from "./core/_types/types";
 /**
@@ -11,8 +10,8 @@ export const dp = pubDp;
  * @deprecated @see pubDataProvider
  */
 export const dataProvider = pubDataProvider;
-export const subscribe = directives.subscribe as DirectiveResult;
-export const sub = directives.sub as DirectiveResult;
+export const subscribe = directives.subscribe;
+export const sub = directives.sub;
 
 /**
  * @deprecated @see pubGet

package/src/docs/_getting-started/concorde-outside.md

@@ -1,8 +1,8 @@
 # Installation
 
-<sonic-alert status="success" label="Recommended — use the starter" size="xl" background>
-  <p><strong>For almost all new projects, use <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a>.</strong></p>
-  <p>You get Vite + TypeScript + Lit + Tailwind, an example component, <code>npx concorde enable-short-paths</code> ready to run, and <code>yarn ai:sync</code> for <a href="#docs/_getting-started/ai-agents.md/ai-agents">AI agent skills</a> (<code>AGENTS.md</code>, Cursor / JetBrains rules) without extra setup.</p>
+<sonic-alert status="info" label="Recommended — use the starter" background>
+<p>For almost all new projects, use <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a></p>
+<p>You get Vite + TypeScript + Lit + Tailwind, an example component, <code>npx concorde enable-short-paths</code> ready to run, and <code>yarn ai:sync</code> for <a href="#docs/_getting-started/ai-agents.md/ai-agents">AI agent skills</a> (<code>AGENTS.md</code>, Cursor / JetBrains rules) without extra setup.</p>
 </sonic-alert>
 
 ## Starter

package/src/docs/code.ts

@@ -36,6 +36,8 @@ export class DocsCode extends LitElement {
       pre {
         font-size: 13px !important;
         padding-right: 5rem !important;
+        border: 1px solid var(--sc-base-200);
+        border-radius: var(--sc-rounded);
       }
       .custom-scroll {
         overflow: auto !important;
@@ -239,7 +241,7 @@ export class DocsCode extends LitElement {
     return html`
       <div
         class="relative ${this.language === "markup"
-          ? "border border-neutral-100 p-4 rounded-md"
+          ? "rounded-md border border-neutral-200 bg-neutral-50/80 dark:border-neutral-700/80 dark:bg-neutral-900/40 p-4"
           : ""}"
       >
         ${this.language === "markup" && !this.noOutput