@anyknown/axis 0.0.0-stage → 0.2.1

package/dist/utils/is-scroll-key.js

@@ -0,0 +1,7 @@
+import { SCROLL_KEYS } from "./constants.js";
+import { isInsideEditable } from "./is-inside-editable.js";
+export function isScrollKey(event) {
+    if (!SCROLL_KEYS.has(event.key))
+        return false;
+    return !isInsideEditable(event.target);
+}

package/dist/utils/max-scroll.d.ts

@@ -0,0 +1,2 @@
+import type { Vector } from "./types.js";
+export declare const maxScroll: (el: Element) => Vector;

package/dist/utils/max-scroll.js

@@ -0,0 +1,4 @@
+export const maxScroll = (el) => ({
+    x: Math.max(0, el.scrollWidth - el.clientWidth),
+    y: Math.max(0, el.scrollHeight - el.clientHeight),
+});

package/dist/utils/measure-snaps.d.ts

@@ -0,0 +1 @@
+export declare function measureSnaps(win: Window, el: Element): Record<"x" | "y", number[]>;

package/dist/utils/measure-snaps.js

@@ -0,0 +1,31 @@
+import { cssLengthToPx } from "./css-length-to-px.js";
+import { maxScroll } from "./max-scroll.js";
+import { snapItems } from "./snap-items.js";
+import { snapPositions } from "./snap-positions.js";
+export function measureSnaps(win, el) {
+    const style = win.getComputedStyle(el);
+    const rect = el.getBoundingClientRect();
+    const max = maxScroll(el);
+    const items = snapItems(win, el);
+    const padding = (side, basis) => cssLengthToPx(style.getPropertyValue(`scroll-padding-${side}`), basis);
+    return {
+        x: snapPositions({
+            start: rect.left + el.clientLeft,
+            size: el.clientWidth,
+            paddingStart: padding("left", el.clientWidth),
+            paddingEnd: padding("right", el.clientWidth),
+            scroll: el.scrollLeft,
+            maxScroll: max.x,
+            rtl: style.direction === "rtl",
+        }, items.x),
+        y: snapPositions({
+            start: rect.top + el.clientTop,
+            size: el.clientHeight,
+            paddingStart: padding("top", el.clientHeight),
+            paddingEnd: padding("bottom", el.clientHeight),
+            scroll: el.scrollTop,
+            maxScroll: max.y,
+            rtl: false,
+        }, items.y),
+    };
+}

package/dist/utils/momentum-distance.d.ts

@@ -0,0 +1 @@
+export declare function momentumDistance(velocity: number): number;

package/dist/utils/momentum-distance.js

@@ -0,0 +1,4 @@
+import { DECAY, FRAME_MS } from "./constants.js";
+export function momentumDistance(velocity) {
+    return (velocity * FRAME_MS) / (1 - DECAY);
+}

package/dist/utils/momentum-step.d.ts

@@ -0,0 +1,4 @@
+export declare function momentumStep(velocity: number, dt: number): {
+    distance: number;
+    velocity: number;
+};

package/dist/utils/momentum-step.js

@@ -0,0 +1,4 @@
+import { DECAY, FRAME_MS } from "./constants.js";
+export function momentumStep(velocity, dt) {
+    return { distance: velocity * dt, velocity: velocity * DECAY ** (dt / FRAME_MS) };
+}

package/dist/utils/nearest-snap.d.ts

@@ -0,0 +1 @@
+export declare function nearestSnap(positions: readonly number[], target: number): number;

package/dist/utils/nearest-snap.js

@@ -0,0 +1,12 @@
+export function nearestSnap(positions, target) {
+    let best = target;
+    let bestDistance = Infinity;
+    for (const position of positions) {
+        const distance = Math.abs(position - target);
+        if (distance < bestDistance) {
+            best = position;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}

package/dist/utils/parse-snap-align.d.ts

@@ -0,0 +1,5 @@
+import type { SnapAlign } from "./types.js";
+export declare function parseSnapAlign(value: string): {
+    x: SnapAlign;
+    y: SnapAlign;
+};

package/dist/utils/parse-snap-align.js

@@ -0,0 +1,5 @@
+const toAlign = (value) => value === "start" || value === "center" || value === "end" ? value : "none";
+export function parseSnapAlign(value) {
+    const [block, inline = block] = value.trim().split(/\s+/);
+    return { x: toAlign(inline), y: toAlign(block) };
+}

package/dist/utils/parse-snap-type.d.ts

@@ -0,0 +1,4 @@
+export declare function parseSnapType(value: string): {
+    x: boolean;
+    y: boolean;
+};

package/dist/utils/parse-snap-type.js

@@ -0,0 +1,7 @@
+export function parseSnapType(value) {
+    const axis = value.trim().split(/\s+/)[0];
+    return {
+        x: axis === "x" || axis === "both" || axis === "inline",
+        y: axis === "y" || axis === "both" || axis === "block",
+    };
+}

package/dist/utils/pointer-sample.d.ts

@@ -0,0 +1,2 @@
+import type { Sample } from "./types.js";
+export declare const pointerSample: (event: PointerEvent) => Sample;

package/dist/utils/pointer-sample.js

@@ -0,0 +1,5 @@
+export const pointerSample = (event) => ({
+    t: event.timeStamp,
+    x: event.clientX,
+    y: event.clientY,
+});

package/dist/utils/prefers-reduced-motion.d.ts

@@ -0,0 +1 @@
+export declare const prefersReducedMotion: (win: Window) => boolean;

package/dist/utils/prefers-reduced-motion.js

@@ -0,0 +1 @@
+export const prefersReducedMotion = (win) => win.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;

package/dist/utils/read-scroll.d.ts

@@ -0,0 +1,2 @@
+import type { Vector } from "./types.js";
+export declare const readScroll: (el: Element, rtl: boolean, max: Vector) => Vector;

package/dist/utils/read-scroll.js

@@ -0,0 +1,6 @@
+import { clamp } from "./clamp.js";
+import { toLogical } from "./to-logical.js";
+export const readScroll = (el, rtl, max) => ({
+    x: clamp(toLogical(el.scrollLeft, rtl), 0, max.x),
+    y: clamp(el.scrollTop, 0, max.y),
+});

package/dist/utils/snap-items.d.ts

@@ -0,0 +1,2 @@
+import type { SnapItem } from "./types.js";
+export declare function snapItems(win: Window, el: Element): Record<"x" | "y", SnapItem[]>;

package/dist/utils/snap-items.js

@@ -0,0 +1,18 @@
+import { cssLengthToPx } from "./css-length-to-px.js";
+import { parseSnapAlign } from "./parse-snap-align.js";
+export function snapItems(win, el) {
+    const items = { x: [], y: [] };
+    for (const child of el.children) {
+        const childStyle = win.getComputedStyle(child);
+        const align = parseSnapAlign(childStyle.scrollSnapAlign);
+        if (align.x === "none" && align.y === "none")
+            continue;
+        const box = child.getBoundingClientRect();
+        const margin = (side) => cssLengthToPx(childStyle.getPropertyValue(`scroll-margin-${side}`), 0);
+        const left = margin("left");
+        const top = margin("top");
+        items.x.push({ start: box.left - left, size: box.width + left + margin("right"), align: align.x });
+        items.y.push({ start: box.top - top, size: box.height + top + margin("bottom"), align: align.y });
+    }
+    return items;
+}

package/dist/utils/snap-positions.d.ts

@@ -0,0 +1,2 @@
+import type { SnapAxis, SnapItem } from "./types.js";
+export declare function snapPositions(axis: SnapAxis, items: readonly SnapItem[]): number[];

package/dist/utils/snap-positions.js

@@ -0,0 +1,28 @@
+import { clamp } from "./clamp.js";
+import { toLogical } from "./to-logical.js";
+export function snapPositions(axis, items) {
+    const { rtl } = axis;
+    const portLow = axis.start + axis.paddingStart;
+    const portHigh = axis.start + axis.size - axis.paddingEnd;
+    const positions = [];
+    for (const item of items) {
+        if (item.align === "none")
+            continue;
+        const high = item.start + item.size;
+        const alignsLowEdge = (item.align === "start") !== rtl;
+        const delta = item.align === "center"
+            ? (item.start + high) / 2 - (portLow + portHigh) / 2
+            : alignsLowEdge
+                ? item.start - portLow
+                : high - portHigh;
+        positions.push(clamp(toLogical(axis.scroll + delta, rtl), 0, axis.maxScroll));
+    }
+    positions.sort((a, b) => a - b);
+    const unique = [];
+    for (const position of positions) {
+        const previous = unique.at(-1);
+        if (previous === undefined || position - previous > 1)
+            unique.push(position);
+    }
+    return unique;
+}

package/dist/utils/supported-user-select.d.ts

@@ -0,0 +1 @@
+export declare const supportedUserSelect: (style: CSSStyleDeclaration) => "user-select" | "-webkit-user-select";

package/dist/utils/supported-user-select.js

@@ -0,0 +1 @@
+export const supportedUserSelect = (style) => "userSelect" in style ? "user-select" : "-webkit-user-select";

package/dist/utils/to-logical.d.ts

@@ -0,0 +1 @@
+export declare function toLogical(scrollLeft: number, rtl: boolean): number;

package/dist/utils/to-logical.js

@@ -0,0 +1,3 @@
+export function toLogical(scrollLeft, rtl) {
+    return rtl ? -scrollLeft : scrollLeft;
+}

package/dist/utils/to-physical.d.ts

@@ -0,0 +1 @@
+export declare function toPhysical(logical: number, rtl: boolean): number;

package/dist/utils/to-physical.js

@@ -0,0 +1,3 @@
+export function toPhysical(logical, rtl) {
+    return rtl ? -logical : logical;
+}

package/dist/utils/try-capture-pointer.d.ts

@@ -0,0 +1 @@
+export declare function tryCapturePointer(el: Element, pointerId: number): void;

package/dist/utils/try-capture-pointer.js

@@ -0,0 +1,6 @@
+export function tryCapturePointer(el, pointerId) {
+    try {
+        el.setPointerCapture(pointerId);
+    }
+    catch { }
+}

package/dist/utils/try-release-pointer.d.ts

@@ -0,0 +1 @@
+export declare function tryReleasePointer(el: Element, pointerId: number): void;

package/dist/utils/try-release-pointer.js

@@ -0,0 +1,7 @@
+export function tryReleasePointer(el, pointerId) {
+    try {
+        if (el.hasPointerCapture(pointerId))
+            el.releasePointerCapture(pointerId);
+    }
+    catch { }
+}

package/dist/utils/types.d.ts

@@ -0,0 +1,22 @@
+export interface Vector {
+    x: number;
+    y: number;
+}
+export interface Sample extends Vector {
+    t: number;
+}
+export type SnapAlign = "start" | "center" | "end" | "none";
+export interface SnapAxis {
+    start: number;
+    size: number;
+    paddingStart: number;
+    paddingEnd: number;
+    scroll: number;
+    maxScroll: number;
+    rtl: boolean;
+}
+export interface SnapItem {
+    start: number;
+    size: number;
+    align: SnapAlign;
+}

package/dist/utils/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/velocity-from-samples.d.ts

@@ -0,0 +1,2 @@
+import type { Sample, Vector } from "./types.js";
+export declare function velocityFromSamples(samples: readonly Sample[], window?: number): Vector;

package/dist/utils/velocity-from-samples.js

@@ -0,0 +1,21 @@
+import { clamp } from "./clamp.js";
+import { MAX_VELOCITY, VELOCITY_WINDOW } from "./constants.js";
+export function velocityFromSamples(samples, window = VELOCITY_WINDOW) {
+    const last = samples.at(-1);
+    if (!last)
+        return { x: 0, y: 0 };
+    let first = last;
+    for (let i = samples.length - 2; i >= 0; i--) {
+        const sample = samples[i];
+        if (last.t - sample.t > window)
+            break;
+        first = sample;
+    }
+    const dt = last.t - first.t;
+    if (dt <= 0)
+        return { x: 0, y: 0 };
+    return {
+        x: clamp((last.x - first.x) / dt, -MAX_VELOCITY, MAX_VELOCITY),
+        y: clamp((last.y - first.y) / dt, -MAX_VELOCITY, MAX_VELOCITY),
+    };
+}

package/dist/utils/wheel-delta-y-px.d.ts

@@ -0,0 +1 @@
+export declare function wheelDeltaYPx(event: WheelEvent, pagePx: number): number;

package/dist/utils/wheel-delta-y-px.js

@@ -0,0 +1,5 @@
+import { LINE_HEIGHT } from "./constants.js";
+export function wheelDeltaYPx(event, pagePx) {
+    const unitPx = event.deltaMode === 1 ? LINE_HEIGHT : event.deltaMode === 2 ? pagePx : 1;
+    return event.deltaY * unitPx;
+}

package/dist/utils/write-scroll.d.ts

@@ -0,0 +1,2 @@
+import type { Vector } from "./types.js";
+export declare function writeScroll(el: Element, position: Partial<Vector>, rtl: boolean): void;

package/dist/utils/write-scroll.js

@@ -0,0 +1,7 @@
+import { toPhysical } from "./to-physical.js";
+export function writeScroll(el, position, rtl) {
+    if (position.x !== undefined)
+        el.scrollLeft = toPhysical(position.x, rtl);
+    if (position.y !== undefined)
+        el.scrollTop = position.y;
+}

package/package.json

@@ -1,6 +1,85 @@
 {
-  "name": "@anyknown/axis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@anyknown/axis",
+	"version": "0.2.1",
+	"description": "Headless scroll primitive for x, y and 2D panning: native scroll first, mouse drag as an enhancement",
+	"keywords": [
+		"carousel",
+		"drag-scroll",
+		"headless",
+		"kanban",
+		"pan",
+		"react",
+		"scroll",
+		"scroll-snap"
+	],
+	"bugs": {
+		"url": "https://github.com/anyknown-com/axis/issues"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/anyknown-com/axis.git"
+	},
+	"files": [
+		"dist",
+		"LICENSE"
+	],
+	"type": "module",
+	"sideEffects": false,
+	"types": "./dist/index.d.ts",
+	"typesVersions": {
+		"*": {
+			"react": [
+				"./dist/react/index.d.ts"
+			]
+		}
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./react": {
+			"types": "./dist/react/index.d.ts",
+			"default": "./dist/react/index.js"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/esm-extensions.mjs",
+		"typecheck": "tsc --noEmit",
+		"lint": "oxlint --deny-warnings src test playground scripts vitest.config.ts",
+		"fmt": "oxfmt",
+		"fmt:check": "oxfmt --check",
+		"check": "pnpm typecheck && pnpm lint && pnpm fmt:check",
+		"test": "vitest run",
+		"dev": "vite --config playground/vite.config.ts",
+		"prepublishOnly": "pnpm check && pnpm test && pnpm build"
+	},
+	"devDependencies": {
+		"@stylistic/eslint-plugin": "5.10.0",
+		"@types/node": "^26.4.0",
+		"@types/react": "^19.2.0",
+		"@types/react-dom": "^19.2.5",
+		"@vitest/browser-playwright": "^4.1.11",
+		"oxfmt": "^0.65.0",
+		"oxlint": "^1.80.0",
+		"playwright": "^1.55.0",
+		"react": "^19.2.8",
+		"react-dom": "^19.2.8",
+		"typescript": "^5.9.0",
+		"vite": "^8.2.2",
+		"vitest": "^4.1.11"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
+	},
+	"packageManager": "pnpm@10.30.3"
+}