@vielzeug/orbit 1.0.3

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+/** @vielzeug/orbit — shared public type definitions. */
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+export type Alignment = 'start' | 'end';
+export type Placement = Side | `${Side}-${Alignment}`;
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface VirtualReference {
+    getBoundingClientRect: () => DOMRect | Rect;
+    getClientRects?: () => DOMRectList | DOMRect[];
+}
+export type ReferenceElement = Element | VirtualReference;
+export interface SideObject {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export type Padding = number | Partial<SideObject>;
+export interface ArrowData {
+    x?: number;
+    y?: number;
+    centerOffset: number;
+    /** `true` when the arrow was clamped away from its ideal center position (e.g. floating element shifted by `shift()`). */
+    constrained: boolean;
+}
+export interface FlipData {
+    /** Placements that were evaluated and overflowed before the winning placement was chosen. */
+    skippedPlacements: Placement[];
+}
+export interface ShiftData {
+    /** Amount shifted on the x axis in pixels. */
+    x: number;
+    /** Amount shifted on the y axis in pixels. */
+    y: number;
+}
+export interface HideData {
+    escaped?: boolean;
+    escapedOffsets?: SideObject;
+    referenceHidden?: boolean;
+    referenceHiddenOffsets?: SideObject;
+}
+export interface SizeData {
+    availableWidth: number;
+    availableHeight: number;
+}
+export interface MiddlewareData {
+    arrow?: ArrowData;
+    flip?: FlipData;
+    hide?: HideData;
+    shift?: ShiftData;
+    size?: SizeData;
+    [key: string]: unknown;
+}
+export interface MiddlewareState {
+    x: number;
+    y: number;
+    initialPlacement: Placement;
+    placement: Placement;
+    rects: {
+        floating: Rect;
+        reference: Rect;
+    };
+    elements: {
+        floating: HTMLElement;
+        reference: ReferenceElement;
+    };
+    middlewareData: MiddlewareData;
+    /** Global default boundary for overflow detection. Per-middleware `boundary` takes precedence. */
+    boundary?: Element | Rect;
+    /** Global default padding for overflow detection. Per-middleware `padding` takes precedence. */
+    padding?: Padding;
+}
+/**
+ * Signal that the middleware pipeline should re-run.
+ *
+ * Use `{}` for a bare restart (same rects and placement). Optionally:
+ * - `remeasure: true` — re-read both rects from the DOM before restarting.
+ * - `rects: { floating, reference }` — restart using the provided rects directly.
+ * - `placement` — override the placement for the next pass.
+ *
+ * **Precedence:** `remeasure` takes priority over `rects`. When both are set,
+ * `remeasure` triggers a fresh DOM read and `rects` is ignored.
+ */
+export type MiddlewareReset = {
+    placement?: Placement;
+    /** Provide explicit rects to use for the next pass instead of re-reading the DOM. */
+    rects?: MiddlewareState['rects'];
+    /** Re-read both element rects from the DOM before restarting the pipeline. */
+    remeasure?: boolean;
+};
+export interface MiddlewareResult {
+    x?: number;
+    y?: number;
+    placement?: Placement;
+    data?: MiddlewareData;
+    reset?: MiddlewareReset;
+}
+export type Middleware = (state: MiddlewareState) => MiddlewareResult | void;
+/**
+ * A middleware branded with the key it writes to `middlewareData`.
+ * Built-in middleware return this type. Custom middleware can cast to it if needed.
+ */
+export type TypedMiddleware<K extends string, D> = Middleware & {};
+export interface ComputePositionResult {
+    x: number;
+    y: number;
+    placement: Placement;
+    middlewareData: MiddlewareData;
+}
+export interface ComputePositionOptions {
+    /** Middleware pipeline to run. Falsy entries are ignored. */
+    middleware?: Array<Middleware | null | undefined | false>;
+    /** Initial placement. Defaults to `'bottom'`. */
+    placement?: Placement;
+    /**
+     * The containing block element for `position: absolute` floating elements.
+     * Provide the floating element's `offsetParent` to convert viewport-relative
+     * coordinates to containing-block-relative coordinates.
+     *
+     * Without this option, coordinates are viewport-relative (correct for `position: fixed`).
+     */
+    containingBlock?: Element | null;
+    /**
+     * Default boundary for all overflow-aware middleware (`flip`, `shift`, `autoPlacement`, `size`, `hide`).
+     * Per-middleware `boundary` takes precedence. Defaults to the visual viewport when omitted.
+     */
+    boundary?: Element | Rect;
+    /**
+     * Default padding for all overflow-aware middleware.
+     * Per-middleware `padding` takes precedence. Defaults to `0` when omitted.
+     */
+    padding?: Padding;
+}
+/**
+ * Handle returned by `float()`.
+ *
+ * - `dispose()` — removes all event listeners and observers. Always call this on teardown.
+ * - `update()` — manually trigger a position recalculation.
+ * - `getPosition()` — returns the most recently computed position.
+ *   - When `autoUpdate: false`, the position is computed synchronously during `float()`, so
+ *     `getPosition()` is **never `null`** immediately after `float()` returns.
+ *   - When using the `autoUpdate` loop (default), `getPosition()` returns `null` only before
+ *     the very first update fires, which happens synchronously on construction.
+ *   - Always returns `null` in SSR environments (via `@vielzeug/orbit/ssr`).
+ */
+export interface FloatHandle {
+    /** `AbortSignal` aborted when `dispose()` is called. Use to tie external lifetimes to this handle. */
+    readonly disposalSignal: AbortSignal;
+    dispose(): void;
+    /** `true` after `dispose()` has been called. */
+    readonly disposed: boolean;
+    getPosition(): ComputePositionResult | null;
+    update(): void;
+    [Symbol.dispose](): void;
+}
+export interface DetectOverflowOptions {
+    /** Boundary element or rect. Defaults to the visual viewport. */
+    boundary?: Element | Rect;
+    /** Inset padding inside the boundary that the floating element must respect. */
+    padding?: Padding;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs");require("@vielzeug/arsenal");var t={bottom:`top`,left:`right`,right:`left`,top:`bottom`};function n(e){return e.split(`-`)[0]}function r(e){return e.split(`-`)[1]??null}function i(e,t){return t?`${e}-${t}`:e}function a({height:e,width:t,x:n,y:r}){return{height:e,width:t,x:n,y:r}}function o(e=0){return typeof e==`number`?{bottom:e,left:e,right:e,top:e}:{bottom:e.bottom??0,left:e.left??0,right:e.right??0,top:e.top??0}}function s(e){return typeof Element<`u`&&e instanceof Element}var c=[[`arrow`,`flip`],[`arrow`,`shift`],[`arrow`,`autoPlacement`],[`flip`,`inline`],[`shift`,`inline`],[`autoPlacement`,`inline`],[`size`,`flip`],[`size`,`autoPlacement`]];function l(t){for(let[n,r]of c){let i=t.indexOf(n),a=t.indexOf(r);if(i!==-1&&a!==-1&&i<a)throw new e.OrbitConfigError(`"${n}" must come after "${r}" in the middleware pipeline. Recommended order: inline → offset → flip/autoPlacement → shift → size → arrow.`)}if(t.includes(`flip`)&&t.includes(`autoPlacement`))throw new e.OrbitConfigError(`use either flip() or autoPlacement() in the middleware pipeline, not both.`)}var u=Symbol.for(`@vielzeug/orbit/name`);function d(e,t){return e[u]=t,e}function f(e,t,n,r){return e===`start`?t:e===`end`?t+n-r:t+(n-r)/2}function p(e,t,i){let a=n(e),o=r(e);switch(a){case`bottom`:return{x:f(o,t.x,t.width,i.width),y:t.y+t.height};case`left`:return{x:t.x-i.width,y:f(o,t.y,t.height,i.height)};case`right`:return{x:t.x+t.width,y:f(o,t.y,t.height,i.height)};case`top`:return{x:f(o,t.x,t.width,i.width),y:t.y-i.height}}}exports.MIDDLEWARE_NAME=u,exports.MIDDLEWARE_ORDER_RULES=c,exports.OPPOSITE=t,exports.baseCoords=p,exports.getAlignment=r,exports.getSide=n,exports.isElement=s,exports.tagMiddleware=d,exports.toRect=a,exports.toSideObject=o,exports.validateMiddlewareNames=l,exports.withPlacement=i;
+//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.cjs","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import { clamp } from '@vielzeug/arsenal';\n\nimport type { Alignment, Middleware, Padding, Placement, Rect, Side, SideObject, TypedMiddleware } from './types';\n\nimport { OrbitConfigError } from './errors';\n\nexport { clamp };\n\nexport const OPPOSITE: Record<Side, Side> = { bottom: 'top', left: 'right', right: 'left', top: 'bottom' };\n\n/** Returns the primary side of a placement (`'top' | 'bottom' | 'left' | 'right'`). */\nexport function getSide(p: Placement): Side {\n  return p.split('-')[0] as Side;\n}\n\n/** Returns the alignment of a placement (`'start' | 'end'`), or `null` for center placements. */\nexport function getAlignment(p: Placement): Alignment | null {\n  return (p.split('-')[1] as Alignment) ?? null;\n}\n\n/** @internal */\nexport function withPlacement(side: Side, align: Alignment | null): Placement {\n  return (align ? `${side}-${align}` : side) as Placement;\n}\n\n/** @internal */\nexport function toRect({ height, width, x, y }: DOMRect | Rect): Rect {\n  return { height, width, x, y };\n}\n\n/** @internal */\nexport function toSideObject(padding: Padding = 0): SideObject {\n  if (typeof padding === 'number') {\n    return { bottom: padding, left: padding, right: padding, top: padding };\n  }\n\n  return {\n    bottom: padding.bottom ?? 0,\n    left: padding.left ?? 0,\n    right: padding.right ?? 0,\n    top: padding.top ?? 0,\n  };\n}\n\n/** @internal */\nexport function isElement(value: unknown): value is Element {\n  return typeof Element !== 'undefined' && value instanceof Element;\n}\n\n// ── Middleware helpers ────────────────────────────────────────────────────────\n\n/**\n * Ordering rules for dev-mode middleware validation.\n * Each tuple is `[mustFollow, mustPrecede]` — `mustFollow` must appear **after** `mustPrecede`\n * in the pipeline. Validation throws if `mustFollow` is found at a lower index than `mustPrecede`.\n * @internal\n */\nexport const MIDDLEWARE_ORDER_RULES: Array<[mustFollow: string, mustPrecede: string]> = [\n  ['arrow', 'flip'],\n  ['arrow', 'shift'],\n  ['arrow', 'autoPlacement'],\n  ['flip', 'inline'],\n  ['shift', 'inline'],\n  ['autoPlacement', 'inline'],\n  ['size', 'flip'],\n  ['size', 'autoPlacement'],\n];\n\n/**\n * Validates a list of middleware names for known-bad orderings.\n * Throws a descriptive error in dev mode if an invalid ordering is detected.\n * @internal\n */\nexport function validateMiddlewareNames(names: Array<string | null>): void {\n  for (const [mustFollow, mustPrecede] of MIDDLEWARE_ORDER_RULES) {\n    const followIdx = names.indexOf(mustFollow);\n    const precedeIdx = names.indexOf(mustPrecede);\n\n    if (followIdx !== -1 && precedeIdx !== -1 && followIdx < precedeIdx) {\n      throw new OrbitConfigError(\n        `\"${mustFollow}\" must come after \"${mustPrecede}\" in the middleware pipeline. ` +\n          `Recommended order: inline → offset → flip/autoPlacement → shift → size → arrow.`,\n      );\n    }\n  }\n\n  if (names.includes('flip') && names.includes('autoPlacement')) {\n    throw new OrbitConfigError('use either flip() or autoPlacement() in the middleware pipeline, not both.');\n  }\n}\n\n/**\n * Unique symbol used to tag middleware with a name for dev-mode ordering validation.\n * Using a Symbol avoids collisions with any `__name` property set by transpilers or wrappers.\n * @internal\n */\nexport const MIDDLEWARE_NAME = Symbol.for('@vielzeug/orbit/name');\n\n/**\n * Tags a middleware function with a name for dev-mode ordering validation and brands it\n * as a `TypedMiddleware<K, D>` for compile-time `middlewareData` inference.\n * @internal\n */\nexport function tagMiddleware<K extends string, D, F extends Middleware>(fn: F, name: K): F & TypedMiddleware<K, D> {\n  (fn as Record<symbol, unknown>)[MIDDLEWARE_NAME] = name;\n\n  return fn as F & TypedMiddleware<K, D>;\n}\n\n// ── Geometry ──────────────────────────────────────────────────────────────────\n\nfunction alignedOffset(align: Alignment | null, refStart: number, refSize: number, floatSize: number): number {\n  if (align === 'start') return refStart;\n\n  if (align === 'end') return refStart + refSize - floatSize;\n\n  return refStart + (refSize - floatSize) / 2;\n}\n\n/**\n * Computes the base (un-shifted) x/y coordinates for a floating element\n * given the placement and the reference/floating rects.\n * @internal\n */\nexport function baseCoords(placement: Placement, ref: Rect, float: Rect): { x: number; y: number } {\n  const side = getSide(placement);\n  const align = getAlignment(placement);\n\n  switch (side) {\n    case 'bottom':\n      return { x: alignedOffset(align, ref.x, ref.width, float.width), y: ref.y + ref.height };\n    case 'left':\n      return { x: ref.x - float.width, y: alignedOffset(align, ref.y, ref.height, float.height) };\n    case 'right':\n      return { x: ref.x + ref.width, y: alignedOffset(align, ref.y, ref.height, float.height) };\n    case 'top':\n      return { x: alignedOffset(align, ref.x, ref.width, float.width), y: ref.y - float.height };\n  }\n}\n"],"mappings":"6DAQA,IAAa,EAA+B,CAAE,OAAQ,MAAO,KAAM,QAAS,MAAO,OAAQ,IAAK,QAAS,EAGzG,SAAgB,EAAQ,EAAoB,CAC1C,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,EACtB,CAGA,SAAgB,EAAa,EAAgC,CAC3D,OAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,IAAoB,IAC3C,CAGA,SAAgB,EAAc,EAAY,EAAoC,CAC5E,OAAQ,EAAQ,GAAG,EAAK,GAAG,IAAU,CACvC,CAGA,SAAgB,EAAO,CAAE,SAAQ,QAAO,IAAG,KAA2B,CACpE,MAAO,CAAE,SAAQ,QAAO,IAAG,GAAE,CAC/B,CAGA,SAAgB,EAAa,EAAmB,EAAe,CAK7D,OAJI,OAAO,GAAY,SACd,CAAE,OAAQ,EAAS,KAAM,EAAS,MAAO,EAAS,IAAK,CAAQ,EAGjE,CACL,OAAQ,EAAQ,QAAU,EAC1B,KAAM,EAAQ,MAAQ,EACtB,MAAO,EAAQ,OAAS,EACxB,IAAK,EAAQ,KAAO,CACtB,CACF,CAGA,SAAgB,EAAU,EAAkC,CAC1D,OAAO,OAAO,QAAY,KAAe,aAAiB,OAC5D,CAUA,IAAa,EAA2E,CACtF,CAAC,QAAS,MAAM,EAChB,CAAC,QAAS,OAAO,EACjB,CAAC,QAAS,eAAe,EACzB,CAAC,OAAQ,QAAQ,EACjB,CAAC,QAAS,QAAQ,EAClB,CAAC,gBAAiB,QAAQ,EAC1B,CAAC,OAAQ,MAAM,EACf,CAAC,OAAQ,eAAe,CAC1B,EAOA,SAAgB,EAAwB,EAAmC,CACzE,IAAK,GAAM,CAAC,EAAY,KAAgB,EAAwB,CAC9D,IAAM,EAAY,EAAM,QAAQ,CAAU,EACpC,EAAa,EAAM,QAAQ,CAAW,EAE5C,GAAI,IAAc,IAAM,IAAe,IAAM,EAAY,EACvD,MAAM,IAAI,EAAA,iBACR,IAAI,EAAW,qBAAqB,EAAY,8GAElD,CAEJ,CAEA,GAAI,EAAM,SAAS,MAAM,GAAK,EAAM,SAAS,eAAe,EAC1D,MAAM,IAAI,EAAA,iBAAiB,4EAA4E,CAE3G,CAOA,IAAa,EAAkB,OAAO,IAAI,sBAAsB,EAOhE,SAAgB,EAAyD,EAAO,EAAoC,CAGlH,MAFA,GAAgC,GAAmB,EAE5C,CACT,CAIA,SAAS,EAAc,EAAyB,EAAkB,EAAiB,EAA2B,CAK5G,OAJI,IAAU,QAAgB,EAE1B,IAAU,MAAc,EAAW,EAAU,EAE1C,GAAY,EAAU,GAAa,CAC5C,CAOA,SAAgB,EAAW,EAAsB,EAAW,EAAuC,CACjG,IAAM,EAAO,EAAQ,CAAS,EACxB,EAAQ,EAAa,CAAS,EAEpC,OAAQ,EAAR,CACE,IAAK,SACH,MAAO,CAAE,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,MAAO,EAAM,KAAK,EAAG,EAAG,EAAI,EAAI,EAAI,MAAO,EACzF,IAAK,OACH,MAAO,CAAE,EAAG,EAAI,EAAI,EAAM,MAAO,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,OAAQ,EAAM,MAAM,CAAE,EAC5F,IAAK,QACH,MAAO,CAAE,EAAG,EAAI,EAAI,EAAI,MAAO,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,OAAQ,EAAM,MAAM,CAAE,EAC1F,IAAK,MACH,MAAO,CAAE,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,MAAO,EAAM,KAAK,EAAG,EAAG,EAAI,EAAI,EAAM,MAAO,CAC7F,CACF"}

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+import { clamp } from '@vielzeug/arsenal';
+import type { Alignment, Placement, Side } from './types';
+export { clamp };
+export declare const OPPOSITE: Record<Side, Side>;
+/** Returns the primary side of a placement (`'top' | 'bottom' | 'left' | 'right'`). */
+export declare function getSide(p: Placement): Side;
+/** Returns the alignment of a placement (`'start' | 'end'`), or `null` for center placements. */
+export declare function getAlignment(p: Placement): Alignment | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,KAAK,EAAE,SAAS,EAAuB,SAAS,EAAQ,IAAI,EAA+B,MAAM,SAAS,CAAC;AAIlH,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAkE,CAAC;AAE3G,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAE1C;AAED,iGAAiG;AACjG,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAE3D"}

package/dist/utils.js

@@ -0,0 +1,2 @@
+import{OrbitConfigError as e}from"./errors.js";import{clamp as t}from"@vielzeug/arsenal";var n={bottom:`top`,left:`right`,right:`left`,top:`bottom`};function r(e){return e.split(`-`)[0]}function i(e){return e.split(`-`)[1]??null}function a(e,t){return t?`${e}-${t}`:e}function o({height:e,width:t,x:n,y:r}){return{height:e,width:t,x:n,y:r}}function s(e=0){return typeof e==`number`?{bottom:e,left:e,right:e,top:e}:{bottom:e.bottom??0,left:e.left??0,right:e.right??0,top:e.top??0}}function c(e){return typeof Element<`u`&&e instanceof Element}var l=[[`arrow`,`flip`],[`arrow`,`shift`],[`arrow`,`autoPlacement`],[`flip`,`inline`],[`shift`,`inline`],[`autoPlacement`,`inline`],[`size`,`flip`],[`size`,`autoPlacement`]];function u(t){for(let[n,r]of l){let i=t.indexOf(n),a=t.indexOf(r);if(i!==-1&&a!==-1&&i<a)throw new e(`"${n}" must come after "${r}" in the middleware pipeline. Recommended order: inline → offset → flip/autoPlacement → shift → size → arrow.`)}if(t.includes(`flip`)&&t.includes(`autoPlacement`))throw new e(`use either flip() or autoPlacement() in the middleware pipeline, not both.`)}var d=Symbol.for(`@vielzeug/orbit/name`);function f(e,t){return e[d]=t,e}function p(e,t,n,r){return e===`start`?t:e===`end`?t+n-r:t+(n-r)/2}function m(e,t,n){let a=r(e),o=i(e);switch(a){case`bottom`:return{x:p(o,t.x,t.width,n.width),y:t.y+t.height};case`left`:return{x:t.x-n.width,y:p(o,t.y,t.height,n.height)};case`right`:return{x:t.x+t.width,y:p(o,t.y,t.height,n.height)};case`top`:return{x:p(o,t.x,t.width,n.width),y:t.y-n.height}}}export{d as MIDDLEWARE_NAME,l as MIDDLEWARE_ORDER_RULES,n as OPPOSITE,m as baseCoords,t as clamp,i as getAlignment,r as getSide,c as isElement,f as tagMiddleware,o as toRect,s as toSideObject,u as validateMiddlewareNames,a as withPlacement};
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["import { clamp } from '@vielzeug/arsenal';\n\nimport type { Alignment, Middleware, Padding, Placement, Rect, Side, SideObject, TypedMiddleware } from './types';\n\nimport { OrbitConfigError } from './errors';\n\nexport { clamp };\n\nexport const OPPOSITE: Record<Side, Side> = { bottom: 'top', left: 'right', right: 'left', top: 'bottom' };\n\n/** Returns the primary side of a placement (`'top' | 'bottom' | 'left' | 'right'`). */\nexport function getSide(p: Placement): Side {\n  return p.split('-')[0] as Side;\n}\n\n/** Returns the alignment of a placement (`'start' | 'end'`), or `null` for center placements. */\nexport function getAlignment(p: Placement): Alignment | null {\n  return (p.split('-')[1] as Alignment) ?? null;\n}\n\n/** @internal */\nexport function withPlacement(side: Side, align: Alignment | null): Placement {\n  return (align ? `${side}-${align}` : side) as Placement;\n}\n\n/** @internal */\nexport function toRect({ height, width, x, y }: DOMRect | Rect): Rect {\n  return { height, width, x, y };\n}\n\n/** @internal */\nexport function toSideObject(padding: Padding = 0): SideObject {\n  if (typeof padding === 'number') {\n    return { bottom: padding, left: padding, right: padding, top: padding };\n  }\n\n  return {\n    bottom: padding.bottom ?? 0,\n    left: padding.left ?? 0,\n    right: padding.right ?? 0,\n    top: padding.top ?? 0,\n  };\n}\n\n/** @internal */\nexport function isElement(value: unknown): value is Element {\n  return typeof Element !== 'undefined' && value instanceof Element;\n}\n\n// ── Middleware helpers ────────────────────────────────────────────────────────\n\n/**\n * Ordering rules for dev-mode middleware validation.\n * Each tuple is `[mustFollow, mustPrecede]` — `mustFollow` must appear **after** `mustPrecede`\n * in the pipeline. Validation throws if `mustFollow` is found at a lower index than `mustPrecede`.\n * @internal\n */\nexport const MIDDLEWARE_ORDER_RULES: Array<[mustFollow: string, mustPrecede: string]> = [\n  ['arrow', 'flip'],\n  ['arrow', 'shift'],\n  ['arrow', 'autoPlacement'],\n  ['flip', 'inline'],\n  ['shift', 'inline'],\n  ['autoPlacement', 'inline'],\n  ['size', 'flip'],\n  ['size', 'autoPlacement'],\n];\n\n/**\n * Validates a list of middleware names for known-bad orderings.\n * Throws a descriptive error in dev mode if an invalid ordering is detected.\n * @internal\n */\nexport function validateMiddlewareNames(names: Array<string | null>): void {\n  for (const [mustFollow, mustPrecede] of MIDDLEWARE_ORDER_RULES) {\n    const followIdx = names.indexOf(mustFollow);\n    const precedeIdx = names.indexOf(mustPrecede);\n\n    if (followIdx !== -1 && precedeIdx !== -1 && followIdx < precedeIdx) {\n      throw new OrbitConfigError(\n        `\"${mustFollow}\" must come after \"${mustPrecede}\" in the middleware pipeline. ` +\n          `Recommended order: inline → offset → flip/autoPlacement → shift → size → arrow.`,\n      );\n    }\n  }\n\n  if (names.includes('flip') && names.includes('autoPlacement')) {\n    throw new OrbitConfigError('use either flip() or autoPlacement() in the middleware pipeline, not both.');\n  }\n}\n\n/**\n * Unique symbol used to tag middleware with a name for dev-mode ordering validation.\n * Using a Symbol avoids collisions with any `__name` property set by transpilers or wrappers.\n * @internal\n */\nexport const MIDDLEWARE_NAME = Symbol.for('@vielzeug/orbit/name');\n\n/**\n * Tags a middleware function with a name for dev-mode ordering validation and brands it\n * as a `TypedMiddleware<K, D>` for compile-time `middlewareData` inference.\n * @internal\n */\nexport function tagMiddleware<K extends string, D, F extends Middleware>(fn: F, name: K): F & TypedMiddleware<K, D> {\n  (fn as Record<symbol, unknown>)[MIDDLEWARE_NAME] = name;\n\n  return fn as F & TypedMiddleware<K, D>;\n}\n\n// ── Geometry ──────────────────────────────────────────────────────────────────\n\nfunction alignedOffset(align: Alignment | null, refStart: number, refSize: number, floatSize: number): number {\n  if (align === 'start') return refStart;\n\n  if (align === 'end') return refStart + refSize - floatSize;\n\n  return refStart + (refSize - floatSize) / 2;\n}\n\n/**\n * Computes the base (un-shifted) x/y coordinates for a floating element\n * given the placement and the reference/floating rects.\n * @internal\n */\nexport function baseCoords(placement: Placement, ref: Rect, float: Rect): { x: number; y: number } {\n  const side = getSide(placement);\n  const align = getAlignment(placement);\n\n  switch (side) {\n    case 'bottom':\n      return { x: alignedOffset(align, ref.x, ref.width, float.width), y: ref.y + ref.height };\n    case 'left':\n      return { x: ref.x - float.width, y: alignedOffset(align, ref.y, ref.height, float.height) };\n    case 'right':\n      return { x: ref.x + ref.width, y: alignedOffset(align, ref.y, ref.height, float.height) };\n    case 'top':\n      return { x: alignedOffset(align, ref.x, ref.width, float.width), y: ref.y - float.height };\n  }\n}\n"],"mappings":"yFAQA,IAAa,EAA+B,CAAE,OAAQ,MAAO,KAAM,QAAS,MAAO,OAAQ,IAAK,QAAS,EAGzG,SAAgB,EAAQ,EAAoB,CAC1C,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,EACtB,CAGA,SAAgB,EAAa,EAAgC,CAC3D,OAAQ,EAAE,MAAM,GAAG,CAAC,CAAC,IAAoB,IAC3C,CAGA,SAAgB,EAAc,EAAY,EAAoC,CAC5E,OAAQ,EAAQ,GAAG,EAAK,GAAG,IAAU,CACvC,CAGA,SAAgB,EAAO,CAAE,SAAQ,QAAO,IAAG,KAA2B,CACpE,MAAO,CAAE,SAAQ,QAAO,IAAG,GAAE,CAC/B,CAGA,SAAgB,EAAa,EAAmB,EAAe,CAK7D,OAJI,OAAO,GAAY,SACd,CAAE,OAAQ,EAAS,KAAM,EAAS,MAAO,EAAS,IAAK,CAAQ,EAGjE,CACL,OAAQ,EAAQ,QAAU,EAC1B,KAAM,EAAQ,MAAQ,EACtB,MAAO,EAAQ,OAAS,EACxB,IAAK,EAAQ,KAAO,CACtB,CACF,CAGA,SAAgB,EAAU,EAAkC,CAC1D,OAAO,OAAO,QAAY,KAAe,aAAiB,OAC5D,CAUA,IAAa,EAA2E,CACtF,CAAC,QAAS,MAAM,EAChB,CAAC,QAAS,OAAO,EACjB,CAAC,QAAS,eAAe,EACzB,CAAC,OAAQ,QAAQ,EACjB,CAAC,QAAS,QAAQ,EAClB,CAAC,gBAAiB,QAAQ,EAC1B,CAAC,OAAQ,MAAM,EACf,CAAC,OAAQ,eAAe,CAC1B,EAOA,SAAgB,EAAwB,EAAmC,CACzE,IAAK,GAAM,CAAC,EAAY,KAAgB,EAAwB,CAC9D,IAAM,EAAY,EAAM,QAAQ,CAAU,EACpC,EAAa,EAAM,QAAQ,CAAW,EAE5C,GAAI,IAAc,IAAM,IAAe,IAAM,EAAY,EACvD,MAAM,IAAI,EACR,IAAI,EAAW,qBAAqB,EAAY,8GAElD,CAEJ,CAEA,GAAI,EAAM,SAAS,MAAM,GAAK,EAAM,SAAS,eAAe,EAC1D,MAAM,IAAI,EAAiB,4EAA4E,CAE3G,CAOA,IAAa,EAAkB,OAAO,IAAI,sBAAsB,EAOhE,SAAgB,EAAyD,EAAO,EAAoC,CAGlH,MAFA,GAAgC,GAAmB,EAE5C,CACT,CAIA,SAAS,EAAc,EAAyB,EAAkB,EAAiB,EAA2B,CAK5G,OAJI,IAAU,QAAgB,EAE1B,IAAU,MAAc,EAAW,EAAU,EAE1C,GAAY,EAAU,GAAa,CAC5C,CAOA,SAAgB,EAAW,EAAsB,EAAW,EAAuC,CACjG,IAAM,EAAO,EAAQ,CAAS,EACxB,EAAQ,EAAa,CAAS,EAEpC,OAAQ,EAAR,CACE,IAAK,SACH,MAAO,CAAE,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,MAAO,EAAM,KAAK,EAAG,EAAG,EAAI,EAAI,EAAI,MAAO,EACzF,IAAK,OACH,MAAO,CAAE,EAAG,EAAI,EAAI,EAAM,MAAO,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,OAAQ,EAAM,MAAM,CAAE,EAC5F,IAAK,QACH,MAAO,CAAE,EAAG,EAAI,EAAI,EAAI,MAAO,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,OAAQ,EAAM,MAAM,CAAE,EAC1F,IAAK,MACH,MAAO,CAAE,EAAG,EAAc,EAAO,EAAI,EAAG,EAAI,MAAO,EAAM,KAAK,EAAG,EAAG,EAAI,EAAI,EAAM,MAAO,CAC7F,CACF"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vielzeug/orbit",
+  "version": "1.0.3",
+  "description": "Floating element positioning — tooltip, dropdown, popover, and menu placement with middleware",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./devtools": {
+      "source": "./src/devtools.ts",
+      "types": "./dist/devtools.d.ts",
+      "import": "./dist/devtools.js",
+      "require": "./dist/devtools.cjs"
+    },
+    "./presets": {
+      "source": "./src/presets.ts",
+      "types": "./dist/presets.d.ts",
+      "import": "./dist/presets.js",
+      "require": "./dist/presets.cjs"
+    },
+    "./reactive": {
+      "source": "./src/reactive.ts",
+      "types": "./dist/reactive.d.ts",
+      "import": "./dist/reactive.js",
+      "require": "./dist/reactive.cjs"
+    },
+    "./ssr": {
+      "source": "./src/ssr.ts",
+      "types": "./dist/ssr.d.ts",
+      "import": "./dist/ssr.js",
+      "require": "./dist/ssr.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest",
+    "build:bundle": "vite build --config vite.bundle.config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@vielzeug/arsenal": "workspace:*",
+    "@vielzeug/ripple": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}