@dava96/osrs-icons 1.0.15 → 1.0.16

package/README.md

@@ -75,6 +75,85 @@ You can use the package directly in the browser via ESM.sh:
 </script>
 ```
 
+### Cursor Packs
+
+Pre-built thematic icon groups — each pack groups related icons by their in-game state:
+
+```ts
+import { sharkPack, dragonDaggerPack, bucketPack } from '@dava96/osrs-icons';
+
+// Fish: raw → cooked → burnt
+element.style.cursor = sharkPack.cooked;
+
+// Dragon dagger: base → poisoned → p+ → p++
+element.style.cursor = dragonDaggerPack.poisonedPlusPlus;
+
+// Bucket fill progression — great for loading states
+const stages = bucketPack.stages; // [empty, 1/5, 2/5, 3/5, 4/5, full]
+const index = Math.min(Math.floor(progress / 100 * stages.length), stages.length - 1);
+element.style.cursor = stages[index];
+```
+
+**Available packs:**
+
+| Pack | Keys |
+|------|------|
+| `sharkPack` | `raw`, `cooked`, `burnt` |
+| `herringPack` | `raw`, `cooked`, `burnt`, `error` |
+| `anglerfishPack` | `raw`, `cooked`, `burnt` |
+| `dragonDaggerPack` | `base`, `poisoned`, `poisonedPlus`, `poisonedPlusPlus` |
+| `goldPack` | `ore`, `bar` |
+| `ironPack` | `ore`, `bar` |
+| `coinsPack` | `_1` to `_10000` + `stages[]` |
+| `bucketPack` | `empty` to `full` + `stages[]` |
+
+### Flip Cursor
+
+Many OSRS icons face right, but cursors typically point left. Flip any icon horizontally at runtime:
+
+```ts
+import { abyssalWhip, flipCursor } from '@dava96/osrs-icons';
+
+const leftFacing = await flipCursor(abyssalWhip);
+document.body.style.cursor = leftFacing;
+```
+
+Results are cached internally — flipping the same icon twice returns instantly. Browser-only (uses Canvas API); returns the original value in Node.js/SSR.
+
+### Apply Cursors
+
+Map OSRS icons to standard CSS cursor states with a one-liner:
+
+```ts
+import { abyssalWhip, dragonScimitar, bucketPack, applyCursors } from '@dava96/osrs-icons';
+
+const cleanup = applyCursors({
+  default: abyssalWhip,
+  pointer: dragonScimitar,
+  wait: bucketPack.full,
+});
+
+// Later, revert to browser defaults
+cleanup();
+```
+
+You can also scope cursors to a specific element:
+
+```ts
+applyCursors({ default: abyssalWhip }, document.getElementById('game-area')!);
+```
+
+### Error Cursor 🐟
+
+Use the iconic red herring as your error cursor:
+
+```ts
+import { errorCursor } from '@dava96/osrs-icons';
+
+// Also available via herringPack.error
+element.style.cursor = errorCursor;
+```
+
 ## How It Works
 
 The build script fetches every inventory sprite (~17,400 icons) from the

package/dist/cjs/applyCursors.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Standard CSS cursor states that can be mapped to OSRS icons.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/cursor
+ */
+export type CursorState = 'default' | 'pointer' | 'wait' | 'text' | 'move' | 'crosshair' | 'grab' | 'grabbing' | 'not-allowed' | 'help' | 'progress' | 'cell' | 'copy' | 'alias' | 'no-drop' | 'col-resize' | 'row-resize' | 'n-resize' | 'e-resize' | 's-resize' | 'w-resize' | 'zoom-in' | 'zoom-out';
+/**
+ * A mapping of CSS cursor states to OSRS icon cursor strings.
+ *
+ * Only include the states you want to override — unlisted states
+ * keep their default browser cursor.
+ */
+export type CursorMapping = Partial<Record<CursorState, string>>;
+/**
+ * Applies OSRS cursor icons to CSS cursor states on a target element
+ * or globally across the entire page.
+ *
+ * Injects a `<style>` tag with CSS rules that map each specified cursor
+ * state to the given OSRS icon. Returns a cleanup function that removes
+ * the injected styles and restores the previous cursors.
+ *
+ * **Browser-only** — in non-browser environments this is a no-op that
+ * returns an empty cleanup function.
+ *
+ * @param mapping - An object mapping CSS cursor states to OSRS cursor strings.
+ * @param target  - Optional element to scope the cursors to. Defaults to the
+ *                  entire document (global).
+ * @returns A cleanup function that reverts all applied cursors.
+ *
+ * @example
+ * ```ts
+ * import { abyssalWhip, dragonScimitar, applyCursors } from '@dava96/osrs-icons';
+ *
+ * // Apply globally
+ * const remove = applyCursors({
+ *   default: abyssalWhip,
+ *   pointer: dragonScimitar,
+ * });
+ *
+ * // Later, revert to browser defaults
+ * remove();
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { bucketPack, applyCursors } from '@dava96/osrs-icons';
+ *
+ * // Scope to a specific element
+ * const cleanup = applyCursors(
+ *   { wait: bucketPack.full },
+ *   document.getElementById('loading-area')!,
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { herringPack, applyCursors } from '@dava96/osrs-icons';
+ *
+ * // Use the red herring for error states!
+ * applyCursors({ not-allowed: herringPack.error });
+ * ```
+ */
+export declare function applyCursors(mapping: CursorMapping, target?: HTMLElement): () => void;

package/dist/cjs/applyCursors.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyCursors = applyCursors;
+/**
+ * Applies OSRS cursor icons to CSS cursor states on a target element
+ * or globally across the entire page.
+ *
+ * Injects a `<style>` tag with CSS rules that map each specified cursor
+ * state to the given OSRS icon. Returns a cleanup function that removes
+ * the injected styles and restores the previous cursors.
+ *
+ * **Browser-only** — in non-browser environments this is a no-op that
+ * returns an empty cleanup function.
+ *
+ * @param mapping - An object mapping CSS cursor states to OSRS cursor strings.
+ * @param target  - Optional element to scope the cursors to. Defaults to the
+ *                  entire document (global).
+ * @returns A cleanup function that reverts all applied cursors.
+ *
+ * @example
+ * ```ts
+ * import { abyssalWhip, dragonScimitar, applyCursors } from '@dava96/osrs-icons';
+ *
+ * // Apply globally
+ * const remove = applyCursors({
+ *   default: abyssalWhip,
+ *   pointer: dragonScimitar,
+ * });
+ *
+ * // Later, revert to browser defaults
+ * remove();
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { bucketPack, applyCursors } from '@dava96/osrs-icons';
+ *
+ * // Scope to a specific element
+ * const cleanup = applyCursors(
+ *   { wait: bucketPack.full },
+ *   document.getElementById('loading-area')!,
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { herringPack, applyCursors } from '@dava96/osrs-icons';
+ *
+ * // Use the red herring for error states!
+ * applyCursors({ not-allowed: herringPack.error });
+ * ```
+ */
+function applyCursors(mapping, target) {
+    if (typeof document === 'undefined') {
+        return () => { };
+    }
+    const styleElement = document.createElement('style');
+    const selector = target ? `[data-osrs-cursor-id="${generateId()}"]` : '*';
+    if (target) {
+        target.setAttribute('data-osrs-cursor-id', selector.slice(22, -2));
+    }
+    const rules = Object.entries(mapping)
+        .map(([state, cursorValue]) => {
+        const fallback = state === 'default' ? 'auto' : state;
+        return `${selector} { cursor: ${cursorValue.replace(', auto', `, ${fallback}`)}; }`;
+    })
+        .join('\n');
+    styleElement.textContent = rules;
+    styleElement.setAttribute('data-osrs-cursors', 'true');
+    document.head.appendChild(styleElement);
+    return () => {
+        styleElement.remove();
+        if (target) {
+            target.removeAttribute('data-osrs-cursor-id');
+        }
+    };
+}
+/** Generates a short unique ID for scoping cursor styles to elements. */
+let idCounter = 0;
+function generateId() {
+    return `osrs-${++idCounter}-${Date.now().toString(36)}`;
+}

package/dist/cjs/applyCursors_test.d.ts

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

package/dist/cjs/applyCursors_test.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const applyCursors_1 = require("./applyCursors");
+// ── applyCursors tests (Node.js — no DOM) ──────────────────────────
+function testApplyCursorsIsExported() {
+    node_assert_1.default.strictEqual(typeof applyCursors_1.applyCursors, 'function');
+    console.log('✓ applyCursors: is a function export');
+}
+function testApplyCursorsReturnsCleanupInNode() {
+    const cleanup = (0, applyCursors_1.applyCursors)({ default: 'test-cursor' });
+    node_assert_1.default.strictEqual(typeof cleanup, 'function', 'should return a cleanup function');
+    cleanup();
+    console.log('✓ applyCursors: returns no-op cleanup function in Node.js');
+}
+function testCursorStateTypeIsExported() {
+    const validStates = [
+        'default', 'pointer', 'wait', 'text', 'move',
+        'crosshair', 'grab', 'grabbing', 'not-allowed', 'help',
+    ];
+    node_assert_1.default.ok(validStates.length > 0, 'CursorState type should compile');
+    console.log('✓ CursorState: type is exported and usable');
+}
+function testCursorMappingTypeAcceptsPartialStates() {
+    const mapping = {
+        default: 'cursor-a',
+        pointer: 'cursor-b',
+    };
+    node_assert_1.default.strictEqual(Object.keys(mapping).length, 2);
+    console.log('✓ CursorMapping: accepts partial state mappings');
+}
+// ── Runner ─────────────────────────────────────────────────────────
+console.log('\nRunning applyCursors tests...\n');
+testApplyCursorsIsExported();
+testApplyCursorsReturnsCleanupInNode();
+testCursorStateTypeIsExported();
+testCursorMappingTypeAcceptsPartialStates();
+console.log('\nAll applyCursors tests passed!\n');

package/dist/cjs/flip.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Horizontally flips a CSS cursor icon so it points in the opposite direction.
+ *
+ * Many OSRS inventory icons face right, but cursor conventions typically
+ * expect left-facing images. This helper mirrors the embedded base64 PNG
+ * using the Canvas API and returns a new, ready-to-use CSS cursor string.
+ *
+ * Results are cached internally — flipping the same icon twice returns
+ * the cached value instantly.
+ *
+ * **Browser-only** — requires the Canvas API. In non-browser environments
+ * (Node.js, SSR) the original cursor string is returned unchanged.
+ *
+ * @param cursorValue - A CSS cursor string (e.g. `url('data:image/png;base64,...'), auto`).
+ * @returns A promise that resolves to a new cursor string with the image flipped.
+ *
+ * @example
+ * ```ts
+ * import { abyssalWhip, flipCursor } from '@dava96/osrs-icons';
+ *
+ * const leftFacingWhip = await flipCursor(abyssalWhip);
+ * document.body.style.cursor = leftFacingWhip;
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { dragonDaggerPack, flipCursor } from '@dava96/osrs-icons';
+ *
+ * // Flip an entire pack
+ * const flippedDagger = await flipCursor(dragonDaggerPack.base);
+ * ```
+ */
+export declare function flipCursor(cursorValue: string): Promise<string>;

package/dist/cjs/flip.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flipCursor = flipCursor;
+/**
+ * Horizontally flips a CSS cursor icon so it points in the opposite direction.
+ *
+ * Many OSRS inventory icons face right, but cursor conventions typically
+ * expect left-facing images. This helper mirrors the embedded base64 PNG
+ * using the Canvas API and returns a new, ready-to-use CSS cursor string.
+ *
+ * Results are cached internally — flipping the same icon twice returns
+ * the cached value instantly.
+ *
+ * **Browser-only** — requires the Canvas API. In non-browser environments
+ * (Node.js, SSR) the original cursor string is returned unchanged.
+ *
+ * @param cursorValue - A CSS cursor string (e.g. `url('data:image/png;base64,...'), auto`).
+ * @returns A promise that resolves to a new cursor string with the image flipped.
+ *
+ * @example
+ * ```ts
+ * import { abyssalWhip, flipCursor } from '@dava96/osrs-icons';
+ *
+ * const leftFacingWhip = await flipCursor(abyssalWhip);
+ * document.body.style.cursor = leftFacingWhip;
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { dragonDaggerPack, flipCursor } from '@dava96/osrs-icons';
+ *
+ * // Flip an entire pack
+ * const flippedDagger = await flipCursor(dragonDaggerPack.base);
+ * ```
+ */
+async function flipCursor(cursorValue) {
+    if (flipCache.has(cursorValue)) {
+        return flipCache.get(cursorValue);
+    }
+    if (typeof document === 'undefined') {
+        return cursorValue;
+    }
+    const dataUrlMatch = cursorValue.match(/url\('(.*?)'\)/);
+    if (!dataUrlMatch) {
+        return cursorValue;
+    }
+    const originalDataUrl = dataUrlMatch[1];
+    const flippedDataUrl = await mirrorImage(originalDataUrl);
+    const flippedCursor = cursorValue.replace(originalDataUrl, flippedDataUrl);
+    flipCache.set(cursorValue, flippedCursor);
+    return flippedCursor;
+}
+/** Internal cache to avoid re-processing the same icon. */
+const flipCache = new Map();
+/**
+ * Loads a data URL into an off-screen canvas, mirrors it horizontally,
+ * and returns the flipped image as a new data URL.
+ */
+function mirrorImage(dataUrl) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => {
+            const canvas = document.createElement('canvas');
+            canvas.width = img.width;
+            canvas.height = img.height;
+            const ctx = canvas.getContext('2d');
+            if (!ctx) {
+                resolve(dataUrl);
+                return;
+            }
+            ctx.translate(canvas.width, 0);
+            ctx.scale(-1, 1);
+            ctx.drawImage(img, 0, 0);
+            resolve(canvas.toDataURL('image/png'));
+        };
+        img.onerror = () => reject(new Error('Failed to load cursor image for flipping'));
+        img.src = dataUrl;
+    });
+}

package/dist/cjs/flip_test.d.ts

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

package/dist/cjs/flip_test.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = __importDefault(require("node:assert"));
+const flip_1 = require("./flip");
+// ── flipCursor tests (Node.js — no Canvas API) ────────────────────
+function testFlipCursorIsExported() {
+    node_assert_1.default.strictEqual(typeof flip_1.flipCursor, 'function');
+    console.log('✓ flipCursor: is a function export');
+}
+async function testFlipCursorFallsBackInNode() {
+    const input = "url('data:image/png;base64,abc123'), auto";
+    const result = await (0, flip_1.flipCursor)(input);
+    node_assert_1.default.strictEqual(result, input, 'should return original in non-browser environment');
+    console.log('✓ flipCursor: returns original value in Node.js (no Canvas)');
+}
+async function testFlipCursorHandlesPlainString() {
+    const input = 'not-a-cursor-value';
+    const result = await (0, flip_1.flipCursor)(input);
+    node_assert_1.default.strictEqual(result, input, 'should return as-is when no url() pattern');
+    console.log('✓ flipCursor: returns plain strings unchanged');
+}
+async function testFlipCursorReturnsSamePromiseType() {
+    const input = "url('data:image/png;base64,test'), auto";
+    const result = (0, flip_1.flipCursor)(input);
+    node_assert_1.default.ok(result instanceof Promise, 'should return a Promise');
+    console.log('✓ flipCursor: returns a Promise');
+}
+// ── Runner ─────────────────────────────────────────────────────────
+console.log('\nRunning flip tests...\n');
+testFlipCursorIsExported();
+(async () => {
+    await testFlipCursorFallsBackInNode();
+    await testFlipCursorHandlesPlainString();
+    await testFlipCursorReturnsSamePromiseType();
+    console.log('\nAll flip tests passed!\n');
+})();

package/dist/cjs/index.d.ts

@@ -1,5 +1,9 @@
 export * from './generated/icons';
 export * from './generated/meta';
+export * from './packs';
+export * from './flip';
+export * from './applyCursors';
+export { redHerring as errorCursor } from './generated/icons';
 /**
  * Extracts the raw `data:image/png;base64,...` URL from one or more
  * CSS cursor values.

package/dist/cjs/index.js

@@ -14,9 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorCursor = void 0;
 exports.toDataUrl = toDataUrl;
 __exportStar(require("./generated/icons"), exports);
 __exportStar(require("./generated/meta"), exports);
+__exportStar(require("./packs"), exports);
+__exportStar(require("./flip"), exports);
+__exportStar(require("./applyCursors"), exports);
+var icons_1 = require("./generated/icons");
+Object.defineProperty(exports, "errorCursor", { enumerable: true, get: function () { return icons_1.redHerring; } });
 function toDataUrl(input) {
     if (typeof input === 'string') {
         return extractUrl(input);