@vettvangur/framework 0.0.1

package/dist/browser-events.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Run a callback when the DOM is fully parsed (no need to wait for images/CSS).
+ *
+ * - If the document is still `loading`, the callback is attached to the
+ *   `DOMContentLoaded` event and will run once.
+ * - If parsing is already complete, the callback runs immediately.
+ *
+ * @param fn - Function to invoke when the DOM is ready.
+ * @example
+ * onDOMContentLoaded(() => {
+ *   initApp()
+ * })
+ */
+export declare const onDOMContentLoaded: (fn: () => void) => void;
+/**
+ * Subscribe to browser history changes triggered by `history.pushState`,
+ * `history.replaceState`, or user navigation (back/forward).
+ *
+ * @param fn - Handler invoked with the `PopStateEvent`.
+ * @example
+ * onPopState((e) => {
+ *   console.debug('popstate', e.state)
+ *   router.navigate(location.pathname + location.search)
+ * })
+ */
+export declare const onPopState: (fn: (e: PopStateEvent) => void) => void;
+/**
+ * Listen for document visibility changes (e.g., tab hidden/visible switches).
+ *
+ * Useful for pausing timers, videos, or analytics when the page is hidden.
+ *
+ * @param fn - Callback invoked on every `visibilitychange`.
+ * @example
+ * onVisibilityChange(() => {
+ *   if (document.hidden) pause()
+ *   else resume()
+ * })
+ */
+export declare const onVisibilityChange: (fn: () => void) => void;

package/dist/browser-events.js

@@ -0,0 +1,41 @@
+/**
+ * Run a callback when the DOM is fully parsed (no need to wait for images/CSS).
+ *
+ * - If the document is still `loading`, the callback is attached to the
+ *   `DOMContentLoaded` event and will run once.
+ * - If parsing is already complete, the callback runs immediately.
+ *
+ * @param fn - Function to invoke when the DOM is ready.
+ * @example
+ * onDOMContentLoaded(() => {
+ *   initApp()
+ * })
+ */
+export const onDOMContentLoaded = (fn) => document.readyState === 'loading'
+    ? document.addEventListener('DOMContentLoaded', fn, { once: true })
+    : fn();
+/**
+ * Subscribe to browser history changes triggered by `history.pushState`,
+ * `history.replaceState`, or user navigation (back/forward).
+ *
+ * @param fn - Handler invoked with the `PopStateEvent`.
+ * @example
+ * onPopState((e) => {
+ *   console.debug('popstate', e.state)
+ *   router.navigate(location.pathname + location.search)
+ * })
+ */
+export const onPopState = (fn) => window.addEventListener('popstate', fn);
+/**
+ * Listen for document visibility changes (e.g., tab hidden/visible switches).
+ *
+ * Useful for pausing timers, videos, or analytics when the page is hidden.
+ *
+ * @param fn - Callback invoked on every `visibilitychange`.
+ * @example
+ * onVisibilityChange(() => {
+ *   if (document.hidden) pause()
+ *   else resume()
+ * })
+ */
+export const onVisibilityChange = (fn) => document.addEventListener('visibilitychange', fn);

package/dist/dom.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Query all elements matching a selector within a given root and return them as a plain array.
+ *
+ * - Generic `T` narrows the element type of the result (defaults to `HTMLElement`).
+ * - Thin wrapper over `root.querySelectorAll` + `Array.from`.
+ *
+ * @typeParam T - Element subtype expected from the selector.
+ * @param root - Search root (e.g., `document`, an `HTMLElement`, or a `ShadowRoot`).
+ * @param s - CSS selector string.
+ * @returns An array of matching elements typed as `T[]`.
+ *
+ * @example
+ * const items = $$<HTMLLIElement>(document, 'ul.menu > li')
+ * items.forEach((li) => li.classList.add('is-found'))
+ */
+export declare const $$: <T extends Element = HTMLElement>(root: ParentNode, s: string) => T[];
+/**
+ * Check if an element is currently in (any part of) the viewport.
+ *
+ * The element is considered "in view" if its bounding box intersects the viewport:
+ * `top < window.innerHeight` **and** `bottom > 0`.
+ *
+ * Note: For preloading just-before-visible content, prefer `IntersectionObserver`
+ * with a positive `rootMargin`.
+ *
+ * @param el - The element to test.
+ * @returns `true` if any portion of the element is visible, otherwise `false`.
+ *
+ * @example
+ * if (inViewport(hero)) {
+ *   hydrateHero()
+ * }
+ */
+export declare const inViewport: (el: Element) => boolean;

package/dist/dom.js

@@ -0,0 +1,37 @@
+/**
+ * Query all elements matching a selector within a given root and return them as a plain array.
+ *
+ * - Generic `T` narrows the element type of the result (defaults to `HTMLElement`).
+ * - Thin wrapper over `root.querySelectorAll` + `Array.from`.
+ *
+ * @typeParam T - Element subtype expected from the selector.
+ * @param root - Search root (e.g., `document`, an `HTMLElement`, or a `ShadowRoot`).
+ * @param s - CSS selector string.
+ * @returns An array of matching elements typed as `T[]`.
+ *
+ * @example
+ * const items = $$<HTMLLIElement>(document, 'ul.menu > li')
+ * items.forEach((li) => li.classList.add('is-found'))
+ */
+export const $$ = (root, s) => Array.from(root.querySelectorAll(s));
+/**
+ * Check if an element is currently in (any part of) the viewport.
+ *
+ * The element is considered "in view" if its bounding box intersects the viewport:
+ * `top < window.innerHeight` **and** `bottom > 0`.
+ *
+ * Note: For preloading just-before-visible content, prefer `IntersectionObserver`
+ * with a positive `rootMargin`.
+ *
+ * @param el - The element to test.
+ * @returns `true` if any portion of the element is visible, otherwise `false`.
+ *
+ * @example
+ * if (inViewport(hero)) {
+ *   hydrateHero()
+ * }
+ */
+export const inViewport = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.top < window.innerHeight && r.bottom > 0;
+};

package/dist/events.d.ts

@@ -0,0 +1,87 @@
+import type { Handler } from './types';
+/**
+ * Create a tiny event bus backed by `EventTarget`.
+ *
+ * Features:
+ * - `on(type, handler)` → subscribe; returns an unsubscribe function.
+ * - `once(type, handler)` → subscribe for a single invocation.
+ * - `emit(type, payload)` → publish with an optional payload.
+ *
+ * Example:
+ * ```ts
+ * const bus = createEventBus()
+ *
+ * const off = bus.on('OPEN_FLYOUT', (detail) => {
+ *   console.log('opened from', detail?.source)
+ * })
+ *
+ * bus.emit('OPEN_FLYOUT', { source: 'button' })
+ * off() // unsubscribe
+ *
+ * bus.once('READY', () => console.log('ready once'))
+ * bus.emit('READY')
+ * ```
+ *
+ * @returns {{
+ *   on(type: string, handler: Handler): () => void;
+ *   once(type: string, handler: Handler): void;
+ *   emit(type: string, payload?: any): void;
+ * }}
+ * An object with `on`, `once`, and `emit` methods.
+ */
+export declare function createEventBus(): {
+    /**
+     * Subscribe to an event type.
+     * @param {string} type - Event name.
+     * @param {Handler} handler - Called with `payload` passed to {@link emit}.
+     * @returns {() => void} Unsubscribe function to remove this handler.
+     */
+    on(type: string, handler: Handler): () => void;
+    /**
+     * Subscribe to a single occurrence of an event type.
+     * Automatically unsubscribes after the first call.
+     * @param {string} type - Event name.
+     * @param {Handler} handler - Called once with the emitted `payload`.
+     */
+    once(type: string, handler: Handler): void;
+    /**
+     * Publish an event with an optional payload.
+     * @param {string} type - Event name.
+     * @param {any} [payload] - Arbitrary data exposed to subscribers as `detail`.
+     */
+    emit(type: string, payload?: any): void;
+};
+/**
+ * A shared, app-wide event bus instance.
+ *
+ * Example:
+ * ```ts
+ * // listen somewhere
+ * const off = events.on('TOGGLE_SIDEBAR', () => {...})
+ *
+ * // emit elsewhere
+ * events.emit('TOGGLE_SIDEBAR')
+ * ```
+ */
+export declare const events: {
+    /**
+     * Subscribe to an event type.
+     * @param {string} type - Event name.
+     * @param {Handler} handler - Called with `payload` passed to {@link emit}.
+     * @returns {() => void} Unsubscribe function to remove this handler.
+     */
+    on(type: string, handler: Handler): () => void;
+    /**
+     * Subscribe to a single occurrence of an event type.
+     * Automatically unsubscribes after the first call.
+     * @param {string} type - Event name.
+     * @param {Handler} handler - Called once with the emitted `payload`.
+     */
+    once(type: string, handler: Handler): void;
+    /**
+     * Publish an event with an optional payload.
+     * @param {string} type - Event name.
+     * @param {any} [payload] - Arbitrary data exposed to subscribers as `detail`.
+     */
+    emit(type: string, payload?: any): void;
+};

package/dist/events.js

@@ -0,0 +1,77 @@
+/**
+ * Create a tiny event bus backed by `EventTarget`.
+ *
+ * Features:
+ * - `on(type, handler)` → subscribe; returns an unsubscribe function.
+ * - `once(type, handler)` → subscribe for a single invocation.
+ * - `emit(type, payload)` → publish with an optional payload.
+ *
+ * Example:
+ * ```ts
+ * const bus = createEventBus()
+ *
+ * const off = bus.on('OPEN_FLYOUT', (detail) => {
+ *   console.log('opened from', detail?.source)
+ * })
+ *
+ * bus.emit('OPEN_FLYOUT', { source: 'button' })
+ * off() // unsubscribe
+ *
+ * bus.once('READY', () => console.log('ready once'))
+ * bus.emit('READY')
+ * ```
+ *
+ * @returns {{
+ *   on(type: string, handler: Handler): () => void;
+ *   once(type: string, handler: Handler): void;
+ *   emit(type: string, payload?: any): void;
+ * }}
+ * An object with `on`, `once`, and `emit` methods.
+ */
+export function createEventBus() {
+    const target = new EventTarget();
+    return {
+        /**
+         * Subscribe to an event type.
+         * @param {string} type - Event name.
+         * @param {Handler} handler - Called with `payload` passed to {@link emit}.
+         * @returns {() => void} Unsubscribe function to remove this handler.
+         */
+        on(type, handler) {
+            const wrapped = (e) => handler(e.detail);
+            target.addEventListener(type, wrapped);
+            return () => target.removeEventListener(type, wrapped); // unsubscribe
+        },
+        /**
+         * Subscribe to a single occurrence of an event type.
+         * Automatically unsubscribes after the first call.
+         * @param {string} type - Event name.
+         * @param {Handler} handler - Called once with the emitted `payload`.
+         */
+        once(type, handler) {
+            const wrapped = (e) => handler(e.detail);
+            target.addEventListener(type, wrapped, { once: true });
+        },
+        /**
+         * Publish an event with an optional payload.
+         * @param {string} type - Event name.
+         * @param {any} [payload] - Arbitrary data exposed to subscribers as `detail`.
+         */
+        emit(type, payload) {
+            target.dispatchEvent(new CustomEvent(type, { detail: payload }));
+        },
+    };
+}
+/**
+ * A shared, app-wide event bus instance.
+ *
+ * Example:
+ * ```ts
+ * // listen somewhere
+ * const off = events.on('TOGGLE_SIDEBAR', () => {...})
+ *
+ * // emit elsewhere
+ * events.emit('TOGGLE_SIDEBAR')
+ * ```
+ */
+export const events = createEventBus();

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { FeatureProps, FeatureInstance, Feature, Loader } from './types';
+export { vettvangur } from './vettvangur';
+export { onDOMContentLoaded } from './browser-events';
+export { preloadTimeout } from './preload-timeout';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { vettvangur } from './vettvangur';
+export { onDOMContentLoaded } from './browser-events';
+export { preloadTimeout } from './preload-timeout';

package/dist/preload-timeout.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Apply staged preload classes to the document body to prevent e.g. transitions from running and font swapping to be visible.
+ *
+ * Sequence:
+ *  - After ~100 ms: adds `loaded` (useful to start lightweight effects after first paint).
+ *  - After ~400 ms: adds `preload--hidden` and removes `preload--transitions`
+ *    to fully hide any preload UI and enable normal transitions.
+ *
+ * Pair this with CSS that initially disables transitions/animations under
+ * `.preload--transitions` and displays your preload UI until `preload--hidden` is set.
+ *
+ * @example
+ * // Run once DOM is ready
+ * window.addEventListener('DOMContentLoaded', preloadTimeout)
+ */
+export declare function preloadTimeout(): void;

package/dist/preload-timeout.js

@@ -0,0 +1,23 @@
+/**
+ * Apply staged preload classes to the document body to prevent e.g. transitions from running and font swapping to be visible.
+ *
+ * Sequence:
+ *  - After ~100 ms: adds `loaded` (useful to start lightweight effects after first paint).
+ *  - After ~400 ms: adds `preload--hidden` and removes `preload--transitions`
+ *    to fully hide any preload UI and enable normal transitions.
+ *
+ * Pair this with CSS that initially disables transitions/animations under
+ * `.preload--transitions` and displays your preload UI until `preload--hidden` is set.
+ *
+ * @example
+ * // Run once DOM is ready
+ * window.addEventListener('DOMContentLoaded', preloadTimeout)
+ */
+export function preloadTimeout() {
+    const body = document.body;
+    setTimeout(() => body.classList.add('loaded'), 100);
+    setTimeout(() => {
+        body.classList.add('preload--hidden');
+        body.classList.remove('preload--transitions');
+    }, 400);
+}

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export type FeatureProps = Record<string, unknown>;
+export interface FeatureInstance {
+    mount(): void;
+    unmount(): void;
+}
+export type Feature = (root: HTMLElement, props?: FeatureProps) => FeatureInstance;
+export type Loader = () => Promise<any>;
+export type Handler = (payload?: any) => void;

package/dist/types.js

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

package/dist/vettvangur.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A function that dynamically imports a feature module.
+ * It should usually be of the form: `() => import('./feature')`.
+ */
+export type Loader = () => Promise<any>;
+/**
+ * A mapping from a comma-separated list of CSS selectors to a dynamic loader.
+ *
+ * Example:
+ * ```ts
+ * const moduleMap: ModuleMap = {
+ *   '.accordion, [data-feature="accordion"]': () => import('./features/accordion'),
+ *   '.tabs': () => import('./features/tabs'),
+ * }
+ * ```
+ */
+export type ModuleMap = Record<string, Loader>;
+/**
+ * Bootstraps feature mounting for a subtree.
+ *
+ * Responsibilities:
+ * - Eagerly mounts elements already in (or near) the viewport.
+ * - Lazily mounts elements as they enter the viewport using `IntersectionObserver`.
+ * - Observes the DOM with `MutationObserver` to mount/unmount nodes that are added/removed.
+ * - Ensures each element matching a selector in `moduleMap` is mounted at most once.
+ *
+ * Notes:
+ * - Uses a `rootMargin` of `200px` to pre-mount just before elements scroll into view.
+ * - Stores the `FeatureInstance` on each element under a private key to support unmount.
+ * - If a node (or any descendant) is removed, its feature is unmounted automatically.
+ *
+ * @param root - The search root (defaults to `document`). Typically a document or shadow root.
+ * @param moduleMap - A map of CSS selector list → dynamic import loader.
+ *
+ * @example
+ * ```ts
+ * import { vettvangur } from '@vettvangur/framework'
+ *
+ * vettvangur(document, {
+ *   '.accordion, [data-accordion]': () => import('./features/accordion'),
+ *   '.tabs': () => import('./features/tabs'),
+ * })
+ * ```
+ */
+export declare function vettvangur(root: ParentNode, moduleMap: ModuleMap): void;

package/dist/vettvangur.js

@@ -0,0 +1,187 @@
+import { $$, inViewport } from './dom';
+/** @internal Symbolic key stored on mounted HTMLElements to cache their FeatureInstance. */
+const INST = '__feature_instance__';
+/**
+ * Cache for dynamic imports so multiple elements using the same loader
+ * do not trigger duplicate network requests.
+ */
+const loaderCache = new WeakMap();
+/**
+ * Mount a single element with the provided dynamic loader.
+ *
+ * - Loads the module (cached per `Loader`).
+ * - Resolves the module's default export (or the module itself) as a {@link Feature}.
+ * - Calls `feature(root).mount()` if present.
+ * - Stores the returned {@link FeatureInstance} on the element for later unmounts.
+ *
+ * @param el - The element to enhance with a feature.
+ * @param load - The dynamic import function that resolves to a module exporting a {@link Feature} as default (or the module itself is a function).
+ */
+async function mount(el, load) {
+    // Already mounted? bail.
+    if (el[INST])
+        return;
+    try {
+        // Reuse an in-flight or completed import for this loader.
+        const promise = loaderCache.get(load) ?? (loaderCache.set(load, load()), loaderCache.get(load));
+        const mod = await promise;
+        const exp = mod.default ?? mod;
+        let instance;
+        if (typeof exp === 'function') {
+            instance = exp(el);
+            instance?.mount?.();
+        }
+        if (instance) {
+            ;
+            el[INST] = instance;
+        }
+    }
+    catch (e) {
+        console.error('Feature mount failed:', e);
+    }
+}
+/**
+ * Unmount a previously mounted element.
+ *
+ * - Invokes `FeatureInstance.unmount()` if present.
+ * - Clears the cached instance from the element.
+ *
+ * @param el - The enhanced element to unmount.
+ */
+function unmount(el) {
+    const inst = el[INST];
+    if (inst?.unmount) {
+        try {
+            inst.unmount();
+        }
+        catch {
+            // swallow unmount errors to avoid breaking DOM tear-down flows
+        }
+    }
+    ;
+    el[INST] = undefined;
+}
+/**
+ * Resolve the appropriate loader for a given element by checking all selector lists
+ * in the {@link ModuleMap}. Keys may contain multiple selectors separated by commas.
+ *
+ * @param el - The element to match against module map selectors.
+ * @param moduleMap - The selector → loader mapping.
+ * @returns The matching loader or `null` if no selector matches the element.
+ */
+function resolveLoader(el, moduleMap) {
+    for (const key of Object.keys(moduleMap)) {
+        const sels = key
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (sels.some((s) => el.matches(s))) {
+            return moduleMap[key];
+        }
+    }
+    return null;
+}
+/**
+ * Bootstraps feature mounting for a subtree.
+ *
+ * Responsibilities:
+ * - Eagerly mounts elements already in (or near) the viewport.
+ * - Lazily mounts elements as they enter the viewport using `IntersectionObserver`.
+ * - Observes the DOM with `MutationObserver` to mount/unmount nodes that are added/removed.
+ * - Ensures each element matching a selector in `moduleMap` is mounted at most once.
+ *
+ * Notes:
+ * - Uses a `rootMargin` of `200px` to pre-mount just before elements scroll into view.
+ * - Stores the `FeatureInstance` on each element under a private key to support unmount.
+ * - If a node (or any descendant) is removed, its feature is unmounted automatically.
+ *
+ * @param root - The search root (defaults to `document`). Typically a document or shadow root.
+ * @param moduleMap - A map of CSS selector list → dynamic import loader.
+ *
+ * @example
+ * ```ts
+ * import { vettvangur } from '@vettvangur/framework'
+ *
+ * vettvangur(document, {
+ *   '.accordion, [data-accordion]': () => import('./features/accordion'),
+ *   '.tabs': () => import('./features/tabs'),
+ * })
+ * ```
+ */
+export function vettvangur(root = document, moduleMap) {
+    /** Lazily mount elements as they approach the viewport. */
+    const io = new IntersectionObserver((entries) => {
+        entries.forEach((e) => {
+            if (!e.isIntersecting)
+                return;
+            const el = e.target;
+            const loader = resolveLoader(el, moduleMap);
+            if (!loader)
+                return io.unobserve(el);
+            mount(el, loader).finally(() => io.unobserve(el));
+        });
+    }, { root: null, threshold: 0, rootMargin: '200px 0px' });
+    /** Prevent double-processing when multiple selectors overlap. */
+    const seen = new WeakSet();
+    // Initial scan for all configured selectors within the root subtree.
+    for (const key of Object.keys(moduleMap)) {
+        const sels = key
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        sels.forEach((sel) => $$(root, sel).forEach((el) => {
+            if (seen.has(el))
+                return;
+            seen.add(el);
+            if (inViewport(el)) {
+                // Eager mount if already visible
+                mount(el, moduleMap[key]);
+            }
+            else {
+                // Otherwise, lazy mount as it comes into view
+                io.observe(el);
+            }
+        }));
+    }
+    /**
+     * Observe DOM mutations:
+     * - For added nodes: mount if the node itself (or descendants) match.
+     * - For removed nodes: unmount any feature instances attached to the node or its descendants.
+     */
+    const mo = new MutationObserver((muts) => {
+        for (const m of muts) {
+            // Added nodes → try to mount
+            m.addedNodes.forEach((n) => {
+                if (!(n instanceof HTMLElement))
+                    return;
+                // If the added node itself matches a selector
+                const loader = resolveLoader(n, moduleMap);
+                if (loader) {
+                    inViewport(n) ? mount(n, loader) : io.observe(n);
+                }
+                // Also search descendants for matches
+                for (const key of Object.keys(moduleMap)) {
+                    const sels = key
+                        .split(',')
+                        .map((s) => s.trim())
+                        .filter(Boolean);
+                    sels.forEach((sel) => n.querySelectorAll(sel).forEach((el) => {
+                        if (el[INST])
+                            return;
+                        inViewport(el) ? mount(el, moduleMap[key]) : io.observe(el);
+                    }));
+                }
+            });
+            // Removed nodes → unmount if needed
+            m.removedNodes.forEach((n) => {
+                if (!(n instanceof HTMLElement))
+                    return;
+                if (n[INST])
+                    unmount(n);
+                n.querySelectorAll('*').forEach((el) => el[INST] && unmount(el));
+            });
+        }
+    });
+    // Observe the whole document body for dynamic changes.
+    mo.observe(document.body, { childList: true, subtree: true });
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vettvangur/framework",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "rimraf": "^5.0.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist || rm -rf dist",
+    "bundle": "pnpm clean && tsc -p tsconfig.json",
+    "dist": "pnpm publish"
+  }
+}