@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/carousel/engine/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Engine vocabulary. Pure types — no React, no DOM, no axis literals leaking
+ * into anything below the engine.
+ *
+ * The kernel idea, unchanged from 0.1.0 because it is the good part:
+ * `position` is an unbounded FLOAT in *index space*, not pixels. A slot at
+ * integer index `g` is `g - position` slots away from the centre. Everything
+ * visual is a pure function of that one signed number.
+ */
+/** Which of the four writers currently owns `position`. */
+export type EngineMode = "idle" | "dragging" | "settling" | "animating" | "swapping";
+export type Axis = "x" | "y";
+/**
+ * How a slot's box gets its size.
+ *
+ * `measured` is the default and the only one that supports CSS-driven
+ * responsiveness: the engine reads its own probe element, so breakpoints stay
+ * in the stylesheet instead of being duplicated in TypeScript.
+ */
+export type SlotSizing = {
+    readonly kind: "measured";
+} | {
+    readonly kind: "fixed";
+    readonly main: number;
+    readonly cross: number;
+} | {
+    readonly kind: "fn";
+    readonly of: (viewport: {
+        main: number;
+        cross: number;
+    }) => {
+        main: number;
+        cross: number;
+    };
+};
+/**
+ * Everything measured off the DOM, resolved onto the main/cross axes so that
+ * nothing downstream ever says "width" or "height".
+ */
+export interface Metrics {
+    readonly slotMain: number;
+    readonly slotCross: number;
+    readonly viewportMain: number;
+    readonly viewportCross: number;
+    /** Engine-owned gutter between slot boxes. Cards can never influence this. */
+    readonly gap: number;
+    /** Centre-to-centre distance along the main axis. `slotMain + gap`. */
+    readonly pitch: number;
+    /** Main-axis offset that lands slot 0 in the middle of the viewport. */
+    readonly centerOffset: number;
+    /** False until the probe has produced a real measurement. */
+    readonly ready: boolean;
+}
+/**
+ * Global, one per frame, identical for every slot. Computed once and read by
+ * all of them — which is why `velocity` lives here and NOT on SlotState: every
+ * slot's distance changes at the same rate, and putting it per-slot invites
+ * someone to compute N of them.
+ */
+export interface CarouselFrame extends Metrics {
+    readonly axis: Axis;
+    /** The unbounded float index. */
+    readonly position: number;
+    /** Index units per second, signed. */
+    readonly velocity: number;
+    readonly mode: EngineMode;
+    /** Ring length — how many slots before the data repeats. */
+    readonly count: number;
+    /** Real items only, excluding placeholders. Pagination uses THIS. */
+    readonly itemCount: number;
+}
+/** Per slot, per frame. */
+export interface SlotState {
+    /** Position on the unbounded integer line. May be negative. */
+    readonly index: number;
+    /** `((index % count) + count) % count` — where this slot reads its data. */
+    readonly ringIndex: number;
+    /** Index into `items`, or null when this ring position is a placeholder. */
+    readonly itemIndex: number | null;
+    /** `index - frame.position`. Signed, fractional. 0 is dead centre. */
+    readonly distance: number;
+}
+/**
+ * Fixed shape, preallocated once per slot and reused forever.
+ *
+ * No optional fields on purpose: a missing `rotateY` would be ambiguous between
+ * "identity" and "keep last frame's value", and two presets would eventually
+ * disagree about which. Reset to identity before each layout pass instead.
+ */
+export interface SlotFrameBuffer {
+    /** 0 = no perspective. Per slot, never on a container. See docs/3d. */
+    perspective: number;
+    x: number;
+    y: number;
+    z: number;
+    scaleX: number;
+    scaleY: number;
+    /** Depth scale. CSS `scale()` leaves z alone, so a turned card scaled in 3D needs it. */
+    scaleZ: number;
+    rotateX: number;
+    rotateY: number;
+    rotateZ: number;
+    skewX: number;
+    skewY: number;
+    originX: number;
+    originY: number;
+    opacity: number;
+    zIndex: number;
+    filter: string;
+    pointerEvents: "auto" | "none";
+}
+/** The identity buffer. Cloned, never shared. */
+export declare function createSlotFrameBuffer(): SlotFrameBuffer;
+/** In-place reset. Avoids an allocation per slot per frame. */
+export declare function resetSlotFrameBuffer(b: SlotFrameBuffer): void;

package/dist/carousel/engine/types.js

@@ -0,0 +1,53 @@
+/**
+ * Engine vocabulary. Pure types — no React, no DOM, no axis literals leaking
+ * into anything below the engine.
+ *
+ * The kernel idea, unchanged from 0.1.0 because it is the good part:
+ * `position` is an unbounded FLOAT in *index space*, not pixels. A slot at
+ * integer index `g` is `g - position` slots away from the centre. Everything
+ * visual is a pure function of that one signed number.
+ */
+/** The identity buffer. Cloned, never shared. */
+export function createSlotFrameBuffer() {
+    return {
+        perspective: 0,
+        x: 0,
+        y: 0,
+        z: 0,
+        scaleX: 1,
+        scaleY: 1,
+        scaleZ: 1,
+        rotateX: 0,
+        rotateY: 0,
+        rotateZ: 0,
+        skewX: 0,
+        skewY: 0,
+        originX: 0.5,
+        originY: 0.5,
+        opacity: 1,
+        zIndex: 0,
+        filter: "none",
+        pointerEvents: "auto",
+    };
+}
+/** In-place reset. Avoids an allocation per slot per frame. */
+export function resetSlotFrameBuffer(b) {
+    b.perspective = 0;
+    b.x = 0;
+    b.y = 0;
+    b.z = 0;
+    b.scaleX = 1;
+    b.scaleY = 1;
+    b.scaleZ = 1;
+    b.rotateX = 0;
+    b.rotateY = 0;
+    b.rotateZ = 0;
+    b.skewX = 0;
+    b.skewY = 0;
+    b.originX = 0.5;
+    b.originY = 0.5;
+    b.opacity = 1;
+    b.zIndex = 0;
+    b.filter = "none";
+    b.pointerEvents = "auto";
+}

package/dist/carousel/engine/useCarouselEngine.d.ts

@@ -0,0 +1,10 @@
+import { type CarouselConfig, type CarouselOptions } from "../config.js";
+import { type CarouselFilter } from "../types.js";
+import type { CarouselHandle } from "./handle.js";
+export interface UseCarouselEngineArgs<T> {
+    readonly items: readonly T[];
+    readonly filters?: readonly CarouselFilter<T>[];
+    readonly options?: CarouselOptions;
+    readonly base?: CarouselConfig;
+}
+export declare function useCarouselEngine<T>({ items, filters, options, base, }: UseCarouselEngineArgs<T>): CarouselHandle<T>;