@kabel-project/kabel 1.0.7

package/util/uid.ts

@@ -0,0 +1,184 @@
+// uid.ts
+
+/**
+ * Strategy used to generate UIDs.
+ */
+export type UIDStrategy = "uuidv4" | "ulid" | "nanoid" | "short";
+
+export interface UIDOptions {
+    /** For "nanoid": length of the id (default 21) */
+    size?: number;
+    /** For "nanoid": custom alphabet (default URL-safe) */
+    alphabet?: string;
+}
+
+/** Web Crypto shim (browser + Node 16+) */
+const cryptoAPI: Crypto | null =
+    (typeof globalThis !== "undefined" && (globalThis as any).crypto) || null;
+
+/**
+ * Returns a Uint8Array of random bytes.
+ * Uses Web Crypto if available; falls back to Math.random otherwise (not cryptographically secure).
+ *
+ * @param {number} len - Number of random bytes to generate.
+ * @returns {Uint8Array} Random bytes array.
+ */
+function randBytes(len: number): Uint8Array {
+    if (cryptoAPI?.getRandomValues) {
+        const buf = new Uint8Array(len);
+        cryptoAPI.getRandomValues(buf);
+        return buf;
+    }
+    // Last resort (very old envs). Not cryptographically strong.
+    const buf = new Uint8Array(len);
+    for (let i = 0; i < len; i++) buf[i] = Math.floor(Math.random() * 256);
+    return buf;
+}
+
+/**
+ * Generates an RFC4122-compliant UUID v4.
+ * Uses `crypto.randomUUID` if available.
+ *
+ * @returns {string} UUID v4 string.
+ */
+export function uuidv4(): string {
+    const g: any = globalThis as any;
+    if (g?.crypto?.randomUUID) return g.crypto.randomUUID();
+
+    const b = randBytes(16);
+    // Per RFC: set version + variant bits
+    // @ts-ignore
+    b[6] = (b[6] & 0x0f) | 0x40;
+    // @ts-ignore
+    b[8] = (b[8] & 0x3f) | 0x80;
+
+    const hex: string[] = [];
+    for (let i = 0; i < 256; i++) hex.push(i.toString(16).padStart(2, "0"));
+
+    return (
+        // @ts-ignore
+        hex[b[0]] + hex[b[1]] + hex[b[2]] + hex[b[3]] + "-" +
+        // @ts-ignore
+        hex[b[4]] + hex[b[5]] + "-" +
+        // @ts-ignore
+        hex[b[6]] + hex[b[7]] + "-" +
+        // @ts-ignore
+        hex[b[8]] + hex[b[9]] + "-" +
+        // @ts-ignore
+        hex[b[10]] + hex[b[11]] + hex[b[12]] + hex[b[13]] + hex[b[14]] + hex[b[15]]
+    );
+}
+
+/** Crockford Base32 alphabet for ULID */
+const CROCK32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // no I L O U
+
+/**
+ * Generates a 26-character ULID (time-sortable unique ID).
+ *
+ * @param {number} [date] - Optional timestamp in milliseconds. Defaults to `Date.now()`.
+ * @returns {string} ULID string.
+ */
+export function ulid(date?: number): string {
+    const time = (typeof date === "number" ? date : Date.now()) >>> 0; // low 32 bits
+    const timeHi = Math.floor((typeof date === "number" ? date : Date.now()) / 0x100000000) >>> 0; // high 32
+    // ULID uses 48-bit time; do base32 encode 48 bits
+    const time48 = new Uint8Array(6);
+    // write 48-bit big-endian
+    let t = BigInt(typeof date === "number" ? date : Date.now());
+    for (let i = 5; i >= 0; i--) {
+        time48[i] = Number(t & 0xffn);
+        t >>= 8n;
+    }
+    // first 10 chars = time
+    let out = "";
+    let acc = 0;
+    let bits = 0;
+    for (let i = 0; i < 6; i++) {
+        // @ts-ignore
+        acc = (acc << 8) | time48[i];
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += CROCK32[(acc >>> bits) & 31];
+        }
+    }
+    if (bits > 0) out += CROCK32[(acc << (5 - bits)) & 31];
+    out = out.slice(0, 10);
+
+    // last 16 chars = randomness (80 bits)
+    const rnd = randBytes(10);
+    acc = 0; bits = 0;
+    for (let i = 0; i < rnd.length; i++) {
+        // @ts-ignore
+        acc = (acc << 8) | rnd[i];
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += CROCK32[(acc >>> bits) & 31];
+        }
+    }
+    if (bits > 0) out += CROCK32[(acc << (5 - bits)) & 31];
+
+    return out.slice(0, 26);
+}
+
+/** NanoID-style: URL-safe alphabet by default, configurable length/alphabet */
+const DEFAULT_ALPHABET =
+    "_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+ * Generates a NanoID-style string.
+ *
+ * @param {number} [size=21] - Length of the generated ID.
+ * @param {string} [alphabet=DEFAULT_ALPHABET] - Alphabet to use.
+ * @returns {string} Generated NanoID string.
+ */
+export function nanoid(size: number = 21, alphabet: string = DEFAULT_ALPHABET): string {
+    if (size <= 0) throw new Error("size must be > 0");
+    const mask = (1 << Math.ceil(Math.log2(alphabet.length))) - 1;
+    let id = "";
+    while (id.length < size) {
+        const bytes = randBytes(1);
+        // @ts-ignore
+        const idx = bytes[0] & mask;
+        if (idx < alphabet.length) id += alphabet[idx];
+    }
+    return id;
+}
+
+/**
+ * Generates a short, mostly-unique ID (timestamp + counter + random).
+ * Not cryptographically strong.
+ *
+ * @returns {string} Short UID string.
+ */
+let _ctr = 0;
+export function shortId(): string {
+    const ts = Date.now().toString(36);
+    _ctr = (_ctr + 1) & 0xfff; // 0..4095
+    const c = _ctr.toString(36).padStart(3, "0");
+    const r = Array.from(randBytes(3))
+        .map(b => (b & 0x3f).toString(36).padStart(2, "0"))
+        .join("")
+        .slice(0, 4);
+    return `${ts}${c}${r}`;
+}
+
+/**
+ * Generates a UID using the specified strategy.
+ *
+ * @param {UIDStrategy} [strategy="uuidv4"] - The UID strategy to use.
+ * @param {UIDOptions} [opts={}] - Options for the selected strategy.
+ * @returns {string} Generated UID.
+ */
+export function generateUID(strategy: UIDStrategy = "uuidv4", opts: UIDOptions = {}): string {
+    switch (strategy) {
+        case "uuidv4": return uuidv4();
+        case "ulid": return ulid();
+        case "nanoid": return nanoid(opts.size ?? 21, opts.alphabet ?? DEFAULT_ALPHABET);
+        case "short": return shortId();
+        default: {
+            const _exhaustive: never = strategy;
+            return uuidv4();
+        }
+    }
+}

package/util/unescape-html.ts

@@ -0,0 +1,22 @@
+/**
+ * Converts HTML-escaped characters in a string back to their literal form.
+ *
+ * Specifically, it replaces:
+ * - `&lt;` with `<`
+ * - `&gt;` with `>`
+ * - `&quot;` with `"`
+ * - `&apos;` with `'`
+ * - `&amp;` with `&`
+ *
+ * @param {string} s - The string containing HTML-escaped characters.
+ * @returns {string} The unescaped string with HTML entities replaced by their literal characters.
+ */
+function unescapeAttr(s: string): string {
+	return s.replace(/&lt;/g, "<")
+			.replace(/&gt;/g, ">")
+			.replace(/&quot;/g, '"')
+			.replace(/&apos;/g, "'")
+			.replace(/&amp;/g, "&");
+}
+
+export default unescapeAttr;

package/util/user-state.ts

@@ -0,0 +1,68 @@
+type StateChangeCallback = (addedOrRemoved: 0 | 1) => void;
+
+class UserState {
+    private state: Set<string>;
+    private callbacks: Map<string, StateChangeCallback[]>;
+    /**
+     * Stores the user's current UIX state
+     * Ex: 'typing'
+     */
+    constructor() {
+        this.state = new Set();
+        this.callbacks = new Map();
+    }
+
+    /** 
+     * Adds a state
+     * @param name - The name of the state (ex: 'typing')
+     */
+    setState(name: string) {
+        const wasPresent = this.state.has(name);
+        if (!wasPresent) {
+            this.state.add(name);
+            this.triggerCallbacks(name, 1);
+        }
+    }
+
+    /** 
+     * Removes a state
+     * @param name - The name of the state (ex: 'typing')
+     */
+    removeState(name: string) {
+        const wasPresent = this.state.has(name);
+        if (wasPresent) {
+            this.state.delete(name);
+            this.triggerCallbacks(name, 0);
+        }
+    }
+
+    /** 
+     * Checks if a state is active
+     * @param name - The name of the state (ex: 'typing')
+     */
+    hasState(name: string) {
+        return this.state.has(name);
+    }
+
+    /** 
+     * Registers a callback for state changes 
+     * @param name - Name of the state to check changes for.
+     * @param cb - Callback to call on state change.
+     */
+    onStateChange(name: string, cb: StateChangeCallback) {
+        if (!this.callbacks.has(name)) this.callbacks.set(name, []);
+        this.callbacks.get(name)!.push(cb);
+    }
+
+    /** Internal: triggers callbacks for a state */
+    private triggerCallbacks(name: string, addedOrRemoved: 0 | 1) {
+        const cbs = this.callbacks.get(name);
+        if (!cbs) return;
+        for (const cb of cbs) cb(addedOrRemoved);
+    }
+}
+const userState = new UserState();
+export default userState;
+export {
+    UserState
+};

package/util/wait-anim-frames.ts

@@ -0,0 +1,24 @@
+/**
+ * Delays execution of a callback by a specified number of animation frames.
+ *
+ * Uses `requestAnimationFrame` to count frames, then calls the provided callback.
+ *
+ * @param {number} frames - The number of animation frames to wait before executing the callback.
+ * @param {() => void} callback - The function to execute after the specified frames have passed.
+ */
+function waitFrames(frames: number, callback: () => void): void {
+	let count = 0;
+
+	function step() {
+		count++;
+		if (count >= frames) {
+			callback();
+		} else {
+			requestAnimationFrame(step);
+		}
+	}
+
+	requestAnimationFrame(step);
+}
+
+export default waitFrames;

package/util/window-listeners.ts

@@ -0,0 +1,62 @@
+type WindowEventKeys =
+	| 'resize'
+	| 'scroll'
+	| 'blur'
+	| 'focus'
+	| 'visibilitychange'
+	| 'pointerlockchange'
+	| 'beforeunload';
+
+type WindowListenersMap = Record<WindowEventKeys, Array<(event: Event) => void>>;
+
+const windowListeners: WindowListenersMap = {
+	resize: [],
+	scroll: [],
+	blur: [],
+	focus: [],
+	visibilitychange: [],
+	pointerlockchange: [],
+	beforeunload: [],
+};
+
+function handleEvent(type: WindowEventKeys, event: Event) {
+	const list = windowListeners[type];
+	if (!list.length) return;
+	for (const fn of list) {
+		try {
+			fn(event);
+		} catch (err) {
+			console.error(`[Kabel] Error in window listener for '${type}':`, err);
+		}
+	}
+}
+
+// auto attach
+(Object.keys(windowListeners) as WindowEventKeys[]).forEach((type) => {
+	window.addEventListener(type, (e) => handleEvent(type, e));
+});
+
+export function addWindowListener(
+	type: WindowEventKeys,
+	fn: (event: Event) => void
+) {
+	windowListeners[type].push(fn);
+}
+
+export function removeWindowListener(
+	type: WindowEventKeys,
+	fn: (event: Event) => void
+) {
+	const list = windowListeners[type];
+	const i = list.indexOf(fn);
+	if (i !== -1) list.splice(i, 1);
+}
+
+export function clearWindowListeners(type?: WindowEventKeys) {
+	if (type) windowListeners[type].length = 0;
+	else (Object.keys(windowListeners) as WindowEventKeys[]).forEach((k) => {
+		windowListeners[k].length = 0;
+	});
+}
+
+export default windowListeners;

package/webpack.config.js

@@ -0,0 +1,80 @@
+const path = require('path');
+const TerserPlugin = require('terser-webpack-plugin');
+const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
+
+module.exports = {
+    mode: 'production', // <- production enables lots of optimizations automatically
+    entry: './src/index.ts',
+    output: {
+        filename: 'kabel.js',
+        path: path.resolve(__dirname, 'dist'),
+        library: {
+            name: 'Kabel',
+            type: 'umd',
+        },
+        globalObject: 'this',
+        libraryExport: 'default',
+        clean: {
+            keep: /index\.html/,
+        }
+    },
+    resolve: {
+        extensions: ['.ts', '.js'],
+    },
+    module: {
+        rules: [
+            {
+                test: /\.ts$/,
+                use: 'ts-loader',
+                exclude: /node_modules/,
+            },
+            {
+                enforce: 'pre',
+                test: /\.js$/,
+                loader: 'source-map-loader',
+            },
+            {
+                test: /\.(css|svg)$/,
+                use: 'raw-loader'
+            },
+        ],
+    },
+    optimization: {
+        minimize: true,
+        minimizer: [
+            new TerserPlugin({
+                terserOptions: {
+                    compress: {
+                        //drop_console: true,       // kill console.logs
+                        drop_debugger: true,      // kill debugger;
+                        pure_funcs: ['console.info', 'console.debug'],
+                        // aggressive compress flags
+                        booleans_as_integers: true,
+                        hoist_funs: true,
+                        passes: 3,
+                        collapse_vars: true,        // inline single-use vars
+                        reduce_vars: true,          // further optimizes var usage
+                        join_vars: true,            // join consecutive var statements
+                        keep_fargs: false,          // remove unused function args
+                        if_return: true,            // optimize if/return statements
+                        conditionals: true,         // convert if-else to conditional expressions
+                        sequences: true,            // join consecutive statements with comma
+                        unused: true,               // remove unused vars/functions
+                        loops: true,                // optimize loops
+                        side_effects: true,         // remove expressions without side-effects
+                    },
+                    mangle: {
+                        //toplevel: false, // <- don’t scramble top-level/public names
+                    },
+                    format: {
+                        comments: false,
+                    },
+                },
+                extractComments: false,
+                parallel: true,
+            }),
+            new CssMinimizerPlugin(),
+        ],
+    },
+    devtool: 'source-map',
+};