solid-route-progress 0.1.0

package/dist/shared.jsx

@@ -0,0 +1,315 @@
+import { batch, createContext, createEffect, createSignal, getOwner, onCleanup, onMount, splitProps, useContext } from "solid-js";
+import { isDev as DEV, isServer } from "solid-js/web";
+//#region src/core.ts
+/** `Symbol.dispose` where the runtime has it. */
+const dispose = Symbol.dispose;
+const DEFAULTS = {
+	trickleTo: .95,
+	delay: 200,
+	stopDelay: 0,
+	speed: 200
+};
+/**
+* Headless progress state machine. Rendering is left to CSS: the controller only
+* exposes a target `value` and a `state`, which `<Progress>` mirrors to
+* `--sp-value` and `data-state`.
+*/
+function createProgress(options = {}) {
+	const [value, setValue] = createSignal(0);
+	const [state, setState] = createSignal("idle");
+	const [error, setError] = createSignal(false);
+	const opt = (key) => options[key] ?? DEFAULTS[key];
+	const holds = /* @__PURE__ */ new Set();
+	/** The one scheduled step: reveal while `idle`, resume trickling while `active`, hide while `done`. */
+	let timer;
+	let stopTimer;
+	/** `true` once the browser has had a chance to paint the visible bar. */
+	let painted = false;
+	/** A hold was released as an `'error'` during the current load. */
+	let failed = false;
+	const schedule = (step, ms) => {
+		clearTimeout(timer);
+		timer = setTimeout(() => {
+			timer = void 0;
+			step();
+		}, ms);
+	};
+	const cancel = () => {
+		clearTimeout(timer);
+		timer = void 0;
+	};
+	/** A reveal is scheduled: the load has not lasted `delay` yet. */
+	const pending = () => state() === "idle" && timer !== void 0;
+	const move = (s, v) => batch(() => {
+		setState(s);
+		setValue(v);
+	});
+	const hide = () => {
+		failed = false;
+		batch(() => {
+			setError(false);
+			move("idle", 0);
+		});
+	};
+	const drop = () => {
+		cancel();
+		hide();
+	};
+	const reveal = (s, v) => {
+		painted = false;
+		requestAnimationFrame(() => painted = true);
+		move(s, v);
+	};
+	const show = () => reveal("trickle", opt("trickleTo"));
+	const finish = () => {
+		if (!painted) return drop();
+		batch(() => {
+			setError(failed);
+			move("done", 1);
+		});
+		schedule(hide, opt("speed"));
+	};
+	/** Every hold is gone: complete or drop the bar, or cancel a reveal that is not due yet. */
+	const settle = (cancelled) => {
+		const s = state();
+		if (s === "trickle" || s === "active") {
+			const end = cancelled && !failed ? drop : finish;
+			const stopDelay = opt("stopDelay");
+			clearTimeout(stopTimer);
+			if (stopDelay > 0) stopTimer = setTimeout(end, stopDelay);
+			else end();
+		} else if (s === "idle") {
+			cancel();
+			failed = false;
+		}
+	};
+	const release = (hold, outcome) => {
+		if (!holds.delete(hold)) return;
+		if (outcome === "error") failed = true;
+		if (!holds.size) settle(outcome === "cancel");
+	};
+	const start = () => {
+		const hold = {};
+		if (!isServer) {
+			holds.add(hold);
+			clearTimeout(stopTimer);
+			const s = state();
+			if (s === "done") {
+				hide();
+				schedule(show, opt("speed"));
+			} else if (s === "idle" && !pending()) {
+				const delay = opt("delay");
+				if (delay > 0) schedule(show, delay);
+				else show();
+			}
+		}
+		const releaseHold = (outcome) => release(hold, outcome);
+		if (dispose) releaseHold[dispose] = releaseHold;
+		return releaseHold;
+	};
+	const done = (outcome) => {
+		holds.clear();
+		if (outcome === "error") failed = true;
+		settle(outcome === "cancel");
+	};
+	const set = (n) => {
+		if (isServer) return;
+		n = Math.min(1, Math.max(0, n));
+		if (n === 1) return done();
+		const s = state();
+		if (s === "done" || pending()) return;
+		if (s === "idle") reveal("active", n);
+		else move("active", n);
+		const trickleTo = opt("trickleTo");
+		if (n < trickleTo) schedule(() => move("trickle", trickleTo), opt("speed"));
+		else cancel();
+	};
+	const track = (promise, options) => {
+		const releaseHold = start();
+		promise.then(() => releaseHold(), () => releaseHold("error"));
+		const timeout = options?.timeout;
+		if (timeout && !isServer) setTimeout(releaseHold, timeout);
+		return promise;
+	};
+	if (getOwner()) onCleanup(() => {
+		clearTimeout(timer);
+		clearTimeout(stopTimer);
+	});
+	return {
+		value,
+		state,
+		error,
+		active: () => state() !== "idle",
+		start,
+		done,
+		set,
+		track,
+		options
+	};
+}
+//#endregion
+//#region src/dev.ts
+const warn = (message) => console.warn(`[sprogress] ${message}`);
+//#endregion
+//#region src/components.tsx
+/** Context carrying the active controller. Exposed for integrations; prefer `useProgress()`. */
+const ProgressContext = createContext();
+/**
+* Read the nearest progress controller — from `<ProgressProvider>`, `<Progress>`,
+* `<RouteProgress>` or `<NavigationProgress>`.
+*/
+function useProgress() {
+	const controller = useContext(ProgressContext);
+	if (!controller) throw new Error("useProgress(): no progress controller in scope. Wrap the app in <ProgressProvider> (the route bar picks it up automatically) or call it inside <Progress>.");
+	return controller;
+}
+/** The props that configure a controller, as opposed to the bar element. */
+const OPTION_KEYS = [
+	"trickleTo",
+	"delay",
+	"stopDelay",
+	"speed"
+];
+/**
+* The controller a bar drives: the `controller` prop, else the nearest `<ProgressProvider>`,
+* else a new one built from `options`. Options only apply in the last case, so development
+* builds say so when they would be dropped.
+*/
+function useController(controller, options) {
+	const provided = controller ?? useContext(ProgressContext);
+	if (!provided) return createProgress(options);
+	if (DEV) {
+		const dropped = OPTION_KEYS.filter((key) => options[key] !== void 0);
+		if (dropped.length) warn(`${dropped.join(", ")} ignored: this bar drives an existing controller, so set options where it is created (createProgress() or <ProgressProvider>).`);
+	}
+	return provided;
+}
+/** Provides a controller to descendants without rendering anything. */
+function ProgressProvider(props) {
+	const [local, options] = splitProps(props, ["controller", "children"]);
+	const controller = local.controller ?? createProgress(options);
+	return <ProgressContext.Provider value={controller}>{local.children}</ProgressContext.Provider>;
+}
+const LOCAL = [
+	"controller",
+	"style",
+	"label",
+	"getValueLabel",
+	"busyAttribute",
+	"ariaBusy",
+	"children",
+	"class"
+];
+/** Bars currently marking the page busy, per attribute: it stays until the last one goes idle. */
+const busyBars = /* @__PURE__ */ new Map();
+function createBusyAttribute(attribute, value, active) {
+	let bars = busyBars.get(attribute);
+	if (!bars) busyBars.set(attribute, bars = /* @__PURE__ */ new Set());
+	const bar = {};
+	const sync = (on) => {
+		if (on) bars.add(bar);
+		else bars.delete(bar);
+		if (bars.size) document.documentElement.setAttribute(attribute, value);
+		else document.documentElement.removeAttribute(attribute);
+	};
+	createEffect(() => sync(active()));
+	onCleanup(() => sync(false));
+}
+/**
+* The bar shell. Renders a fixed, full-width `role="progressbar"` element and mirrors the
+* controller into `--sp-value` / `--sp-speed` / `data-state` / `data-error`; everything
+* visual lives in `style.css`. Renders the idle shell on the server.
+*/
+function Progress(props) {
+	const [local, options, rest] = splitProps(props, LOCAL, OPTION_KEYS);
+	const controller = useController(local.controller, options);
+	let root;
+	const valueNow = () => controller.state() === "trickle" ? void 0 : Math.round(controller.value() * 100);
+	const valueText = () => {
+		const percent = valueNow();
+		return percent === void 0 ? void 0 : local.getValueLabel?.(percent);
+	};
+	if (!isServer) {
+		if (DEV) onMount(() => {
+			if (root.getClientRects().length && getComputedStyle(root).position === "static") warn("style.css is not loaded: import 'solid-route-progress/style.css' once.");
+		});
+		createBusyAttribute("data-sp-busy", "", () => local.busyAttribute !== false && controller.active());
+		createBusyAttribute("aria-busy", "true", () => local.ariaBusy === true && controller.active());
+	}
+	return <ProgressContext.Provider value={controller}>
+      <div {...rest} ref={root} role="progressbar" aria-label={local.label ?? "Loading"} aria-valuemin={0} aria-valuemax={100} aria-valuenow={valueNow()} aria-valuetext={valueText()} data-state={controller.state()} data-error={controller.error() ? "" : void 0} class={local.class ? `sprogress ${local.class}` : "sprogress"} style={{
+		...local.style,
+		"--sp-value": controller.value(),
+		"--sp-speed": `${controller.options.speed ?? DEFAULTS.speed}ms`
+	}}>
+        {local.children ?? <Bar />}
+      </div>
+    </ProgressContext.Provider>;
+}
+/** The sliding bar: a full-width strip slid in from the inline-start edge. */
+function Bar(props) {
+	const [local, rest] = splitProps(props, ["class"]);
+	return <div class={local.class ? `sprogress-bar ${local.class}` : "sprogress-bar"} {...rest} />;
+}
+//#endregion
+//#region src/navigation-api.ts
+/** `window.navigation`, or `undefined` where the Navigation API is unavailable. */
+const getNavigation = () => globalThis.navigation;
+/** Anchors (or their ancestors) carrying this attribute never trigger the bar. */
+const IGNORE_ATTRIBUTE = "data-sp-ignore";
+/** Whether `target` is, or sits inside, an element marked `data-sp-ignore`. */
+const isIgnored = (target) => target instanceof Element && target.closest(`[data-sp-ignore]`) !== null;
+/**
+* An `AbortSignal` that fires when the surrounding Solid owner is disposed. Pass it to
+* `addEventListener` and the listener removes itself.
+*/
+function disposalSignal() {
+	const controller = new AbortController();
+	if (getOwner()) onCleanup(() => controller.abort());
+	return controller.signal;
+}
+//#endregion
+//#region src/cross-document.ts
+/**
+* Show the bar for navigations the page starts that leave the current document: external
+* links, plain form posts, `location` assignments and reloads, back/forward to another
+* document. Browser-UI navigations (the reload button, the address bar, bookmarks) never
+* reach the page, so they show nothing.
+*
+* Uses the Navigation API `navigate` event, which fires before the request is made; where
+* the API is missing this does nothing. Links marked `data-sp-ignore` are skipped. The bar
+* fades out when the navigation is cancelled before the document unloads (`navigateerror`:
+* a stop, a newer navigation) or the page is restored from the back/forward cache, and
+* completes after `timeout`, the only end for a `204` or a server-sent download, which
+* Chromium does not report back. A navigation a router intercepts instead completes on
+* `navigatesuccess` / `navigateerror`.
+*/
+function createCrossDocumentProgress(controller, options = {}) {
+	const navigation = getNavigation();
+	if (isServer || !navigation) return;
+	const signal = disposalSignal();
+	let timer;
+	/** Releases the hold of the navigation still in flight. */
+	let release;
+	const finish = (outcome) => {
+		clearTimeout(timer);
+		release?.(outcome);
+		release = void 0;
+	};
+	navigation.addEventListener("navigate", (event) => {
+		if (event.defaultPrevented || event.destination.sameDocument || event.downloadRequest !== null || !/^https?:/.test(event.destination.url) || isIgnored(event.sourceElement) || options.filter?.(event) === false) return;
+		const previous = release;
+		release = controller.start();
+		previous?.();
+		clearTimeout(timer);
+		const timeout = options.timeout ?? 1e4;
+		if (timeout > 0) timer = setTimeout(finish, timeout);
+	}, { signal });
+	navigation.addEventListener("currententrychange", () => navigation.transition && clearTimeout(timer), { signal });
+	navigation.addEventListener("navigatesuccess", () => finish(), { signal });
+	navigation.addEventListener("navigateerror", (event) => finish(event.error?.name === "AbortError" ? "cancel" : "error"), { signal });
+	window.addEventListener("pageshow", (event) => event.persisted && finish("cancel"), { signal });
+	signal.addEventListener("abort", () => finish());
+}
+//#endregion
+export { isIgnored as a, Progress as c, useController as d, useProgress as f, createProgress as h, getNavigation as i, ProgressContext as l, warn as m, IGNORE_ATTRIBUTE as n, Bar as o, DEV as p, disposalSignal as r, OPTION_KEYS as s, createCrossDocumentProgress as t, ProgressProvider as u };

package/dist/style.css

@@ -0,0 +1,84 @@
+/*
+ * solid-route-progress — all rendering lives here. JS only writes `--sp-value`, `--sp-speed` and `data-state`.
+ *
+ * Tunables (set them anywhere: `:root`, `@theme`, a class, or inline):
+ *   --sp-color            bar colour                       oklch(0.65 0.14 241)
+ *   --sp-height           bar thickness                    3px
+ *   --sp-z-index                                           9999
+ *   --sp-start            value the bar is revealed at     0.08
+ *   --sp-trickle-duration length of the loading drift      10s
+ *   --sp-trickle-easing   shape of the loading drift       linear() curve
+ *
+ * `--sp-speed` mirrors the `speed` option so CSS transitions and JS timers agree: read it in
+ * your own rules, set it through `speed`.
+ *
+ * Everything sits in the `components.sprogress` sublayer, so Tailwind utilities, your own
+ * `@layer components` rules and unlayered CSS all win without `!important`.
+ */
+
+@property --sp-value {
+  syntax: '<number>';
+  inherits: true;
+  initial-value: 0;
+}
+
+@layer components.sprogress {
+  .sprogress {
+    position: fixed;
+    inset: 0 0 auto 0;
+    z-index: var(--sp-z-index, 9999);
+    height: var(--sp-height, 3px);
+    pointer-events: none;
+    visibility: visible;
+    transition:
+      opacity var(--sp-speed) ease,
+      visibility 0s;
+  }
+
+  .sprogress[data-state='idle'] {
+    opacity: 0;
+    visibility: hidden;
+    /* keep painting while the opacity fades, then drop out of the a11y tree / hit-testing */
+    transition:
+      opacity var(--sp-speed) ease,
+      visibility 0s var(--sp-speed);
+  }
+
+  .sprogress-bar {
+    position: absolute;
+    inset: 0;
+    background: var(--sp-color, oklch(0.65 0.14 241));
+    /* full-width bar slid in from the inline-start edge */
+    transform: translateX(calc((var(--sp-value) - 1) * 100%));
+    /* fast out of the gate, then a long crawl — never quite arriving */
+    transition: transform var(--sp-trickle-duration, 10s)
+      var(
+        --sp-trickle-easing,
+        linear(0, 0.25 5%, 0.4 10%, 0.55 18%, 0.7 30%, 0.8 45%, 0.88 60%, 0.94 75%, 0.98 90%, 1)
+      );
+  }
+
+  .sprogress:dir(rtl) .sprogress-bar {
+    transform: translateX(calc((1 - var(--sp-value)) * 100%));
+  }
+
+  /* hidden: park the bar at the start position, but only after the fade-out finished */
+  .sprogress[data-state='idle'] .sprogress-bar {
+    --sp-value: var(--sp-start, 0.08);
+    transition: transform 0s var(--sp-speed);
+  }
+
+  /* explicit set() / done(): short, eased hop instead of the long drift */
+  .sprogress:is([data-state='active'], [data-state='done']) .sprogress-bar {
+    transition-duration: var(--sp-speed);
+    transition-timing-function: ease;
+  }
+
+  /* forced colours strip backgrounds; paint the bar with the system highlight instead */
+  @media (forced-colors: active) {
+    .sprogress-bar {
+      forced-color-adjust: none;
+      background: Highlight;
+    }
+  }
+}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "solid-route-progress",
+  "version": "0.1.0",
+  "description": "Web-native, CSS-driven route progress bar for SolidJS. The loading drift is one CSS transition; Tailwind v4 friendly.",
+  "license": "MIT",
+  "author": "kecan0406 (https://github.com/kecan0406)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kecan0406/solid-route-progress.git"
+  },
+  "homepage": "https://solid-route-progress.vercel.app",
+  "bugs": {
+    "url": "https://github.com/kecan0406/solid-route-progress/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "solid": "./dist/index.jsx",
+      "default": "./dist/index.js"
+    },
+    "./router": {
+      "types": "./dist/router.d.ts",
+      "solid": "./dist/router.jsx",
+      "default": "./dist/router.js"
+    },
+    "./navigation": {
+      "types": "./dist/navigation.d.ts",
+      "solid": "./dist/navigation.jsx",
+      "default": "./dist/navigation.js"
+    },
+    "./style.css": "./dist/style.css",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "router": [
+        "./dist/router.d.ts"
+      ],
+      "navigation": [
+        "./dist/navigation.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "dev": "vite serve dev",
+    "dev:www": "pnpm --filter solid-route-progress-www dev",
+    "build:www": "pnpm --filter solid-route-progress-www build",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "size": "node scripts/size.mjs",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm size",
+    "format": "prettier -w \"{src,test,dev,scripts}/**/*.{ts,tsx,css,mjs}\" \"www/src/**/*.{ts,tsx,css}\" \"www/*.{ts,json}\" \"*.{ts,md,json}\" \".github/**/*.yml\"",
+    "prepublishOnly": "pnpm check",
+    "lint": "oxlint --deny-warnings",
+    "format:check": "prettier --check \"{src,test,dev,scripts}/**/*.{ts,tsx,css,mjs}\" \"www/src/**/*.{ts,tsx,css}\" \"www/*.{ts,json}\" \"*.{ts,md,json}\" \".github/**/*.yml\"",
+    "changeset": "changeset"
+  },
+  "peerDependencies": {
+    "@solidjs/router": ">=1.0.0",
+    "solid-js": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@solidjs/router": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "solid-router",
+    "progress",
+    "progress-bar",
+    "nprogress",
+    "bprogress",
+    "navigation",
+    "tailwindcss"
+  ],
+  "packageManager": "pnpm@10.33.2",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^3.0.3",
+    "@solidjs/router": "^1.0.0",
+    "@solidjs/testing-library": "^0.8.10",
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@vitest/browser-playwright": "^4.1.11",
+    "eslint-plugin-solid": "^0.18.0",
+    "jsdom": "^30.0.1",
+    "oxlint": "^1.83.0",
+    "playwright": "^1.62.1",
+    "prettier": "^3.9.6",
+    "publint": "^0.3.24",
+    "solid-js": "^1.9.15",
+    "tailwindcss": "^4.3.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "unplugin-solid": "^2.0.0",
+    "vite": "^8.2.2",
+    "vite-plugin-solid": "^2.11.14",
+    "vitest": "^4.1.11"
+  }
+}