universal-readonly-rest 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# universal-readonly
+
+Universal readonly / interaction-control layer for web applications.
+
+This package lets you lock a page or a section of the DOM into a read-only state while still allowing safe viewing actions (scrolling, reading, selection, copying, etc.) and optionally permitting some interactions such as links or keyboard input.
+
+It is framework-agnostic and works in plain browser code, React, Vue, or any app that can run JavaScript in the DOM.
+
+Installation
+
+```bash
+npm install universal-readonly-rest
+```
+
+Basic usage
+
+```ts
+import { readonlyMode } from 'universal-readonly-rest';
+
+// Enable globally for the entire page
+readonlyMode.enable();
+
+// Enable only for one form or section
+readonlyMode.enable({ selector: '#order-form' });
+
+// Enable with custom permissions
+readonlyMode.enable({
+  selector: '#order-form',
+  allow: {
+    scroll: true,
+    selection: true,
+    copy: true,
+    links: false,
+    download: false,
+    focus: true,
+    contextMenu: false,
+    keyboard: false
+  }
+});
+
+// Disable all readonly behavior
+readonlyMode.disable();
+
+// Toggle between on/off
+readonlyMode.toggle();
+
+// Check if the readonly mode is active
+console.log(readonlyMode.isEnabled());
+```
+
+Options
+
+`readonlyMode.enable(options?)` and `readonlyMode.toggle(options?)` accept:
+
+```ts
+interface ReadonlyOptions {
+  selector?: string | string[];
+  allow?: {
+    scroll?: boolean;
+    selection?: boolean;
+    copy?: boolean;
+    links?: boolean;
+    download?: boolean;
+    focus?: boolean;
+    contextMenu?: boolean;
+    keyboard?: boolean;
+  };
+}
+```
+
+- `selector`: CSS selector or list of selectors to scope readonly mode. If omitted, the package applies to the whole document.
+- `allow`: fine-grained control over what behavior is still permitted while readonly is active.
+
+Default allow configuration
+
+```ts
+{
+  scroll: true,
+  selection: true,
+  copy: true,
+  links: true,
+  download: true,
+  focus: true,
+  contextMenu: true,
+  keyboard: false
+}
+```
+
+What gets blocked
+
+When readonly mode is active, the library listens to DOM events in the capture phase and prevents state-changing actions such as:
+
+- form submit
+- button click
+- input/change events
+- paste/cut/drop
+- context menu
+- keyboard editing while `keyboard: false`
+
+The default behavior is to keep viewing and reading actions available while blocking edits and interactive mutations.
+
+React example
+
+```tsx
+import React, { useEffect } from 'react';
+import { readonlyMode } from 'universal-readonly-rest';
+
+export function OrderFormDemo() {
+  useEffect(() => {
+    readonlyMode.enable({
+      selector: '#order-form',
+      allow: {
+        scroll: true,
+        selection: true,
+        copy: true,
+        links: false,
+        download: false,
+        focus: true,
+        contextMenu: false,
+        keyboard: false
+      }
+    });
+
+    return () => readonlyMode.disable();
+  }, []);
+
+  return (
+    <form id="order-form">
+      <input name="name" placeholder="Name" />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+In this example, only the form with id `order-form` is locked. Other parts of the app remain interactive unless they match the selector.
+
+Notes
+
+- The package is intentionally small and browser-oriented.
+- It hooks into DOM events on the capture phase to stop interaction before it reaches the target element.
+- Because it works with selectors, you can apply readonly mode to a single form, a section, or the entire page.
+- If you want all interactions disabled, set all `allow` values to `false` for a strict lock.
+
+Example: strict read-only mode
+
+```ts
+readonlyMode.enable({
+  allow: {
+    scroll: false,
+    selection: false,
+    copy: false,
+    links: false,
+    download: false,
+    focus: false,
+    contextMenu: false,
+    keyboard: false
+  }
+});
+```
+
+This effectively prevents most user-driven state changes while leaving the page visually readable (depending on browser behavior and the element set you target).

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { ReadonlyOptions } from './types';
+declare class ReadonlyMode {
+    private enabled;
+    private roots;
+    private options;
+    private listeners;
+    enable(options?: ReadonlyOptions): void;
+    disable(): void;
+    toggle(options?: ReadonlyOptions): void;
+    isEnabled(): boolean;
+    private normalizeSelectors;
+    private isEventInRoots;
+    private isEditable;
+}
+export declare const readonlyMode: ReadonlyMode;
+export default readonlyMode;

package/dist/index.js

@@ -0,0 +1,154 @@
+const DEFAULT_ALLOW = {
+    scroll: true,
+    selection: true,
+    copy: true,
+    links: true,
+    download: true,
+    focus: true,
+    contextMenu: true,
+    keyboard: false
+};
+class ReadonlyMode {
+    constructor() {
+        this.enabled = false;
+        this.roots = [];
+        this.options = {};
+        this.listeners = new Map();
+    }
+    enable(options) {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        this.options = options || {};
+        const allow = { ...DEFAULT_ALLOW, ...(this.options.allow || {}) };
+        // Resolve roots
+        const selectors = this.normalizeSelectors(this.options.selector);
+        if (selectors.length === 0) {
+            this.roots = [document.documentElement];
+        }
+        else {
+            const set = new Set();
+            for (const sel of selectors) {
+                try {
+                    document.querySelectorAll(sel).forEach(el => set.add(el));
+                }
+                catch (err) {
+                    // ignore invalid selectors
+                }
+            }
+            this.roots = Array.from(set);
+        }
+        // Attach capturing listeners to intercept state-changing interactions
+        const capture = (e) => {
+            if (!this.isEventInRoots(e))
+                return;
+            if (e.type === 'submit') {
+                // Block form submissions
+                e.preventDefault();
+                e.stopImmediatePropagation();
+                return;
+            }
+            if (e.type === 'click') {
+                // Allow links optionally
+                const t = e.target;
+                if (!t)
+                    return;
+                const anchor = t.closest('a[href]');
+                if (anchor) {
+                    if (allow.links)
+                        return; // allow
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    return;
+                }
+                const btn = t.closest('button, input[type="button"], input[type="submit"], input[type="checkbox"], input[type="radio"]');
+                if (btn) {
+                    // block clicking that could change state
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    return;
+                }
+            }
+            if (e.type === 'keydown' || e.type === 'keypress' || e.type === 'beforeinput') {
+                if (allow.keyboard)
+                    return;
+                const t = e.target;
+                if (!t)
+                    return;
+                if (this.isEditable(t)) {
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    return;
+                }
+            }
+            if (e.type === 'input' || e.type === 'change' || e.type === 'paste' || e.type === 'cut' || e.type === 'drop') {
+                // Block state-changing input events
+                e.preventDefault();
+                e.stopImmediatePropagation();
+                return;
+            }
+            if (e.type === 'contextmenu') {
+                if (allow.contextMenu)
+                    return;
+                e.preventDefault();
+                e.stopImmediatePropagation();
+                return;
+            }
+        };
+        const events = ['submit', 'click', 'keydown', 'keypress', 'beforeinput', 'input', 'change', 'paste', 'cut', 'drop', 'contextmenu'];
+        for (const ev of events) {
+            const listener = capture.bind(this);
+            document.addEventListener(ev, listener, { capture: true, passive: false });
+            this.listeners.set(ev, listener);
+        }
+    }
+    disable() {
+        if (!this.enabled)
+            return;
+        this.enabled = false;
+        for (const [ev, listener] of this.listeners.entries()) {
+            document.removeEventListener(ev, listener, { capture: true });
+        }
+        this.listeners.clear();
+        this.roots = [];
+        this.options = {};
+    }
+    toggle(options) {
+        if (this.enabled)
+            this.disable();
+        else
+            this.enable(options);
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    normalizeSelectors(selector) {
+        if (!selector)
+            return [];
+        if (typeof selector === 'string') {
+            // support comma-separated lists
+            return selector.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        return selector.map(s => s.trim()).filter(Boolean);
+    }
+    isEventInRoots(e) {
+        const target = e.target;
+        if (!target)
+            return false;
+        for (const root of this.roots) {
+            if (root.contains(target))
+                return true;
+        }
+        return false;
+    }
+    isEditable(el) {
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'input' || tag === 'textarea' || el.isContentEditable)
+            return true;
+        if (el.closest && el.closest('input, textarea, [contenteditable="true"]'))
+            return true;
+        return false;
+    }
+}
+export const readonlyMode = new ReadonlyMode();
+export default readonlyMode;

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+import { ReadonlyOptions } from './types';
+declare class ReadonlyMode {
+    private enabled;
+    private roots;
+    private options;
+    private listeners;
+    enable(options?: ReadonlyOptions): void;
+    disable(): void;
+    toggle(options?: ReadonlyOptions): void;
+    isEnabled(): boolean;
+    private normalizeSelectors;
+    private isEventInRoots;
+    private isEditable;
+}
+export declare const readonlyMode: ReadonlyMode;
+export default readonlyMode;

package/dist/src/index.js

@@ -0,0 +1,154 @@
+const DEFAULT_ALLOW = {
+    scroll: true,
+    selection: true,
+    copy: true,
+    links: true,
+    download: true,
+    focus: true,
+    contextMenu: true,
+    keyboard: false
+};
+class ReadonlyMode {
+    constructor() {
+        this.enabled = false;
+        this.roots = [];
+        this.options = {};
+        this.listeners = new Map();
+    }
+    enable(options) {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        this.options = options || {};
+        const allow = { ...DEFAULT_ALLOW, ...(this.options.allow || {}) };
+        // Resolve roots
+        const selectors = this.normalizeSelectors(this.options.selector);
+        if (selectors.length === 0) {
+            this.roots = [document.documentElement];
+        }
+        else {
+            const set = new Set();
+            for (const sel of selectors) {
+                try {
+                    document.querySelectorAll(sel).forEach(el => set.add(el));
+                }
+                catch (err) {
+                    // ignore invalid selectors
+                }
+            }
+            this.roots = Array.from(set);
+        }
+        // Attach capturing listeners to intercept state-changing interactions
+        const capture = (e) => {
+            if (!this.isEventInRoots(e))
+                return;
+            if (e.type === 'submit') {
+                // Block form submissions
+                e.preventDefault();
+                e.stopImmediatePropagation();
+                return;
+            }
+            if (e.type === 'click') {
+                // Allow links optionally
+                const t = e.target;
+                if (!t)
+                    return;
+                const anchor = t.closest('a[href]');
+                if (anchor) {
+                    if (allow.links)
+                        return; // allow
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    return;
+                }
+                const btn = t.closest('button, input[type="button"], input[type="submit"], input[type="checkbox"], input[type="radio"]');
+                if (btn) {
+                    // block clicking that could change state
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    return;
+                }
+            }
+            if (e.type === 'keydown' || e.type === 'keypress' || e.type === 'beforeinput') {
+                if (allow.keyboard)
+                    return;
+                const t = e.target;
+                if (!t)
+                    return;
+                if (this.isEditable(t)) {
+                    e.preventDefault();
+                    e.stopImmediatePropagation();
+                    return;
+                }
+            }
+            if (e.type === 'input' || e.type === 'change' || e.type === 'paste' || e.type === 'cut' || e.type === 'drop') {
+                // Block state-changing input events
+                e.preventDefault();
+                e.stopImmediatePropagation();
+                return;
+            }
+            if (e.type === 'contextmenu') {
+                if (allow.contextMenu)
+                    return;
+                e.preventDefault();
+                e.stopImmediatePropagation();
+                return;
+            }
+        };
+        const events = ['submit', 'click', 'keydown', 'keypress', 'beforeinput', 'input', 'change', 'paste', 'cut', 'drop', 'contextmenu'];
+        for (const ev of events) {
+            const listener = capture.bind(this);
+            document.addEventListener(ev, listener, { capture: true, passive: false });
+            this.listeners.set(ev, listener);
+        }
+    }
+    disable() {
+        if (!this.enabled)
+            return;
+        this.enabled = false;
+        for (const [ev, listener] of this.listeners.entries()) {
+            document.removeEventListener(ev, listener, { capture: true });
+        }
+        this.listeners.clear();
+        this.roots = [];
+        this.options = {};
+    }
+    toggle(options) {
+        if (this.enabled)
+            this.disable();
+        else
+            this.enable(options);
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    normalizeSelectors(selector) {
+        if (!selector)
+            return [];
+        if (typeof selector === 'string') {
+            // support comma-separated lists
+            return selector.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        return selector.map(s => s.trim()).filter(Boolean);
+    }
+    isEventInRoots(e) {
+        const target = e.target;
+        if (!target)
+            return false;
+        for (const root of this.roots) {
+            if (root.contains(target))
+                return true;
+        }
+        return false;
+    }
+    isEditable(el) {
+        const tag = el.tagName.toLowerCase();
+        if (tag === 'input' || tag === 'textarea' || el.isContentEditable)
+            return true;
+        if (el.closest && el.closest('input, textarea, [contenteditable="true"]'))
+            return true;
+        return false;
+    }
+}
+export const readonlyMode = new ReadonlyMode();
+export default readonlyMode;

package/dist/src/types.d.ts

@@ -0,0 +1,14 @@
+export interface ReadonlyAllowOptions {
+    scroll?: boolean;
+    selection?: boolean;
+    copy?: boolean;
+    links?: boolean;
+    download?: boolean;
+    focus?: boolean;
+    contextMenu?: boolean;
+    keyboard?: boolean;
+}
+export interface ReadonlyOptions {
+    selector?: string | string[];
+    allow?: ReadonlyAllowOptions;
+}

package/dist/src/types.js

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

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export interface ReadonlyAllowOptions {
+    scroll?: boolean;
+    selection?: boolean;
+    copy?: boolean;
+    links?: boolean;
+    download?: boolean;
+    focus?: boolean;
+    contextMenu?: boolean;
+    keyboard?: boolean;
+}
+export interface ReadonlyOptions {
+    selector?: string | string[];
+    allow?: ReadonlyAllowOptions;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "universal-readonly-rest",
+  "version": "0.1.0",
+  "description": "Universal readonly / interaction-control layer for web applications (framework-agnostic).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "vitest run --environment jsdom",
+    "test:watch": "vitest --environment jsdom"
+  },
+  "keywords": [
+    "readonly",
+    "readonly-mode",
+    "ui",
+    "accessibility",
+    "interaction-control"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "^26.4.1",
+    "jsdom": "^30.0.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  }
+}