lightview 2.2.2 → 2.3.4

package/src/lightview-x.js

@@ -622,12 +622,16 @@ const elementsFromSelector = (selector, element) => {
     }
 };
 
-const updateTargetContent = (el, elements, raw, loc, contentHash, { element, setupChildren }, targetHash = null) => {
+const updateTargetContent = (el, elements, raw, loc, contentHash, options, targetHash = null) => {
+    const { element, setupChildren, saveScrolls, restoreScrolls } = { ...options, ...globalThis.Lightview?.internals };
     const markerId = `${loc}-${contentHash.slice(0, 8)}`;
     let track = getOrSet(insertedContentMap, el.domEl, () => ({}));
     if (track[loc]) removeInsertedContent(el.domEl, `${loc}-${track[loc].slice(0, 8)}`);
     track[loc] = contentHash;
 
+    // Snapshot scroll positions document-wide before updating
+    const scrollMap = saveScrolls ? saveScrolls() : null;
+
     const performScroll = (root) => {
         if (!targetHash) return;
         requestAnimationFrame(() => {
@@ -642,18 +646,25 @@ const updateTargetContent = (el, elements, raw, loc, contentHash, { element, set
         });
     };
 
+    const runRestore = (root) => {
+        if (restoreScrolls && scrollMap) restoreScrolls(scrollMap, root);
+    };
+
     if (loc === 'shadow') {
         if (!el.domEl.shadowRoot) el.domEl.attachShadow({ mode: 'open' });
         setupChildren(elements, el.domEl.shadowRoot);
         executeScripts(el.domEl.shadowRoot);
         performScroll(el.domEl.shadowRoot);
+        runRestore(el.domEl.shadowRoot);
     } else if (loc === 'innerhtml') {
         el.children = elements;
         executeScripts(el.domEl);
         performScroll(document);
+        runRestore(el.domEl);
     } else {
         insert(elements, el.domEl, loc, markerId, { element, setupChildren });
         performScroll(document);
+        runRestore(el.domEl);
     }
 };
 
@@ -1573,6 +1584,114 @@ const customElementWrapper = (Component, config = {}) => {
     };
 };
 
+
+/**
+ * JSON Schema Lite Validator (Draft 7 Compatible)
+ * Implements a lightweight validation engine for LightviewX.
+ */
+const validateJSONSchema = (value, schema) => {
+    if (!schema) return true;
+    const errors = [];
+    const internals = globalThis.Lightview?.internals;
+
+    const check = (val, sch, path = '') => {
+        if (!sch) return true;
+
+        // Resolve named schemas
+        if (typeof sch === 'string') {
+            const registered = internals?.schemas?.get(sch);
+            if (registered) return check(val, registered, path);
+            return true; // Unknown named schema passes by default or could throw
+        }
+
+        const type = sch.type;
+        const getType = (v) => {
+            if (v === null) return 'null';
+            if (Array.isArray(v)) return 'array';
+            return typeof v;
+        };
+        const currentType = getType(val);
+
+        // 1. Type Validation
+        if (type && type !== currentType) {
+            if (type === 'integer' && Number.isInteger(val)) { /* OK */ }
+            else if (!(type === 'number' && typeof val === 'number')) {
+                errors.push({ path, message: `Expected type ${type}, got ${currentType}`, keyword: 'type' });
+                return false;
+            }
+        }
+
+        // 2. String Validation
+        if (currentType === 'string') {
+            if (sch.minLength !== undefined && val.length < sch.minLength) errors.push({ path, keyword: 'minLength' });
+            if (sch.maxLength !== undefined && val.length > sch.maxLength) errors.push({ path, keyword: 'maxLength' });
+            if (sch.pattern !== undefined && !new RegExp(sch.pattern).test(val)) errors.push({ path, keyword: 'pattern' });
+            if (sch.format === 'email' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val)) errors.push({ path, keyword: 'format' });
+        }
+
+        // 3. Number Validation
+        if (currentType === 'number') {
+            if (sch.minimum !== undefined && val < sch.minimum) errors.push({ path, keyword: 'minimum' });
+            if (sch.maximum !== undefined && val > sch.maximum) errors.push({ path, keyword: 'maximum' });
+            if (sch.multipleOf !== undefined && val % sch.multipleOf !== 0) errors.push({ path, keyword: 'multipleOf' });
+        }
+
+        // 4. Object Validation
+        if (currentType === 'object') {
+            if (sch.required && Array.isArray(sch.required)) {
+                for (const key of sch.required) {
+                    if (!(key in val)) errors.push({ path: path ? `${path}.${key}` : key, keyword: 'required' });
+                }
+            }
+            if (sch.properties) {
+                for (const key in sch.properties) {
+                    if (key in val) check(val[key], sch.properties[key], path ? `${path}.${key}` : key);
+                }
+            }
+            if (sch.additionalProperties === false) {
+                for (const key in val) {
+                    if (!sch.properties || !(key in sch.properties)) errors.push({ path: path ? `${path}.${key}` : key, keyword: 'additionalProperties' });
+                }
+            }
+        }
+
+        // 5. Array Validation
+        if (currentType === 'array') {
+            if (sch.minItems !== undefined && val.length < sch.minItems) errors.push({ path, keyword: 'minItems' });
+            if (sch.maxItems !== undefined && val.length > sch.maxItems) errors.push({ path, keyword: 'maxItems' });
+            if (sch.uniqueItems && new Set(val).size !== val.length) errors.push({ path, keyword: 'uniqueItems' });
+            if (sch.items) {
+                val.forEach((item, i) => check(item, sch.items, `${path}[${i}]`));
+            }
+        }
+
+        // 6. Const & Enum
+        if (sch.const !== undefined && val !== sch.const) errors.push({ path, keyword: 'const' });
+        if (sch.enum && !sch.enum.includes(val)) errors.push({ path, keyword: 'enum' });
+
+        return errors.length === 0;
+    };
+
+    const valid = check(value, schema);
+    return valid || errors; // Return true or the array of errors
+};
+
+// Hook into Lightview core validation
+const lvInternals = globalThis.__LIGHTVIEW_INTERNALS__ || globalThis.Lightview?.internals;
+if (lvInternals) {
+    const hooks = lvInternals.hooks || (globalThis.Lightview?.hooks);
+    if (hooks) {
+        hooks.validate = (value, schema) => {
+            const result = validateJSONSchema(value, schema);
+            if (result === true) return true;
+            // If validation fails, we throw to prevent state update
+            const msg = result.map(e => `${e.path || 'root'}: failed ${e.keyword}${e.message ? ' (' + e.message + ')' : ''}`).join(', ');
+            throw new Error(`Lightview Validation Error: ${msg}`);
+        };
+    }
+    if (globalThis.Lightview) globalThis.Lightview.validate = validateJSONSchema;
+}
+
 // Export for module usage
 const LightviewX = {
     state,
@@ -1591,6 +1710,7 @@ const LightviewX = {
     preloadComponentCSS,
     createCustomElement,
     customElementWrapper,
+    validate: validateJSONSchema,
     internals: {
         handleSrcAttribute,
         parseElements

package/src/lightview.js

@@ -1,4 +1,5 @@
-import { signal, effect, computed, getRegistry } from './reactivity/signal.js';
+import { signal, effect, computed, getRegistry, internals } from './reactivity/signal.js';
+import { state, getState } from './reactivity/state.js';
 
 const core = {
     get currentEffect() {
@@ -13,6 +14,58 @@ const nodeStateFactory = () => ({ effects: [], onmount: null, onunmount: null })
 
 const registry = getRegistry();
 
+/**
+ * Persistent scroll memory - tracks scroll positions continuously via event listeners.
+ * Much more reliable than point-in-time snapshots.
+ */
+const scrollMemory = new Map();
+
+const initScrollMemory = () => {
+    if (typeof document === 'undefined') return;
+
+    // Use event delegation on document for scroll events
+    document.addEventListener('scroll', (e) => {
+        const el = e.target;
+        if (el === document || el === document.documentElement) return;
+
+        const key = el.id || (el.getAttribute && el.getAttribute('data-preserve-scroll'));
+        if (key) {
+            scrollMemory.set(key, { top: el.scrollTop, left: el.scrollLeft });
+        }
+    }, true); // Capture phase to catch all scroll events
+};
+
+// Initialize when DOM is ready
+if (typeof document !== 'undefined') {
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', initScrollMemory);
+    } else {
+        initScrollMemory();
+    }
+}
+
+/**
+ * Returns the current scroll memory (a snapshot of all tracked positions).
+ */
+const saveScrolls = () => new Map(scrollMemory);
+
+/**
+ * Restores scroll positions from a saved map.
+ */
+const restoreScrolls = (map, root = document) => {
+    if (!map || map.size === 0) return;
+    requestAnimationFrame(() => {
+        map.forEach((pos, key) => {
+            const node = document.getElementById(key) ||
+                document.querySelector(`[data-preserve-scroll="${key}"]`);
+            if (node) {
+                node.scrollTop = pos.top;
+                node.scrollLeft = pos.left;
+            }
+        });
+    });
+};
+
 /**
  * Assocates an effect with a DOM node for automatic cleanup when the node is removed.
  */
@@ -305,6 +358,25 @@ const makeReactiveAttributes = (attributes, domNode) => {
                 domNode.setAttribute(key, value);
             }
             reactiveAttrs[key] = value;
+        } else if (typeof value === 'object' && value !== null && Lightview.hooks.processAttribute) {
+            const processed = Lightview.hooks.processAttribute(domNode, key, value);
+            if (processed !== undefined) {
+                reactiveAttrs[key] = processed;
+            } else if (key === 'style') {
+                // Style object support (merged from below)
+                Object.entries(value).forEach(([styleKey, styleValue]) => {
+                    if (typeof styleValue === 'function') {
+                        const runner = effect(() => { domNode.style[styleKey] = styleValue(); });
+                        trackEffect(domNode, runner);
+                    } else {
+                        domNode.style[styleKey] = styleValue;
+                    }
+                });
+                reactiveAttrs[key] = value;
+            } else {
+                setAttributeValue(domNode, key, value);
+                reactiveAttrs[key] = value;
+            }
         } else if (typeof value === 'function') {
             // Reactive binding
             const runner = effect(() => {
@@ -317,19 +389,6 @@ const makeReactiveAttributes = (attributes, domNode) => {
             });
             trackEffect(domNode, runner);
             reactiveAttrs[key] = value;
-        } else if (key === 'style' && typeof value === 'object') {
-            // Handle style object which may contain reactive values
-            Object.entries(value).forEach(([styleKey, styleValue]) => {
-                if (typeof styleValue === 'function') {
-                    const runner = effect(() => {
-                        domNode.style[styleKey] = styleValue();
-                    });
-                    trackEffect(domNode, runner);
-                } else {
-                    domNode.style[styleKey] = styleValue;
-                }
-            });
-            reactiveAttrs[key] = value;
         } else {
             // Static attribute - handle undefined/null/boolean properly
             setAttributeValue(domNode, key, value);
@@ -595,6 +654,9 @@ const tags = new Proxy({}, {
 });
 
 const Lightview = {
+    state,
+    getState,
+    registerSchema: (name, definition) => internals.schemas.set(name, definition),
     signal,
     get: signal.get,
     computed,
@@ -608,14 +670,24 @@ const Lightview = {
     hooks: {
         onNonStandardHref: null,
         processChild: null,
-        validateUrl: null
+        processAttribute: null,
+        validateUrl: null,
+        validate: (value, schema) => internals.hooks.validate(value, schema)
     },
     // Internals exposed for extensions
     internals: {
         core,
         domToElement,
         wrapDomElement,
-        setupChildren
+        setupChildren,
+        trackEffect,
+        saveScrolls,
+        restoreScrolls,
+        localRegistries: internals.localRegistries,
+        futureSignals: internals.futureSignals,
+        schemas: internals.schemas,
+        parents: internals.parents,
+        hooks: internals.hooks
     }
 };
 

package/src/reactivity/signal.js

@@ -6,33 +6,48 @@
 // Global Handshake: Ensures all bundles share the same reactive engine
 const _LV = (globalThis.__LIGHTVIEW_INTERNALS__ ||= {
     currentEffect: null,
-    registry: new Map(),
-    dependencyMap: new WeakMap() // Tracking signals -> subscribers
+    registry: new Map(), // Global name -> Signal/Proxy
+    localRegistries: new WeakMap(), // Object/Element -> Map(name -> Signal/Proxy)
+    futureSignals: new Map(), // name -> Set of (signal) => void
+    schemas: new Map(), // name -> Schema (Draft 7+ or Shorthand)
+    parents: new WeakMap(), // Proxy -> Parent (Proxy/Element)
+    helpers: new Map(), // name -> function (used for transforms and expressions)
+    hooks: {
+        validate: (value, schema) => true // Hook for extensions (like JPRX) to provide full validation
+    }
 });
 
+/**
+ * Resolves a named signal/state using up-tree search starting from scope.
+ */
+export const lookup = (name, scope) => {
+    let current = scope;
+    while (current && typeof current === 'object') {
+        const registry = _LV.localRegistries.get(current);
+        if (registry && registry.has(name)) return registry.get(name);
+        current = current.parentElement || _LV.parents.get(current);
+    }
+    return _LV.registry.get(name);
+};
+
 /**
  * Creates a reactive signal.
  */
 export const signal = (initialValue, optionsOrName) => {
-    let name = typeof optionsOrName === 'string' ? optionsOrName : optionsOrName?.name;
+    const name = typeof optionsOrName === 'string' ? optionsOrName : optionsOrName?.name;
     const storage = optionsOrName?.storage;
+    const scope = optionsOrName?.scope;
 
     if (name && storage) {
         try {
             const stored = storage.getItem(name);
-            if (stored !== null) {
-                initialValue = JSON.parse(stored);
-            }
-        } catch (e) { /* Ignore storage errors */ }
+            if (stored !== null) initialValue = JSON.parse(stored);
+        } catch (e) { /* Ignore */ }
     }
 
     let value = initialValue;
     const subscribers = new Set();
-
-    const f = (...args) => {
-        if (args.length === 0) return f.value;
-        f.value = args[0];
-    };
+    const f = (...args) => args.length === 0 ? f.value : (f.value = args[0]);
 
     Object.defineProperty(f, 'value', {
         get() {
@@ -46,24 +61,24 @@ export const signal = (initialValue, optionsOrName) => {
             if (value !== newValue) {
                 value = newValue;
                 if (name && storage) {
-                    try {
-                        storage.setItem(name, JSON.stringify(value));
-                    } catch (e) { /* Ignore storage errors */ }
+                    try { storage.setItem(name, JSON.stringify(value)); } catch (e) { /* Ignore */ }
                 }
-                // Copy subscribers to avoid infinite loop when effect re-subscribes during iteration
                 [...subscribers].forEach(effect => effect());
             }
         }
     });
 
     if (name) {
-        if (_LV.registry.has(name)) {
-            // Already registered - could be a name collision or re-registration
-            if (_LV.registry.get(name) !== f) {
-                throw new Error(`Lightview: A signal or state with the name "${name}" is already registered.`);
-            }
-        } else {
-            _LV.registry.set(name, f);
+        const registry = (scope && typeof scope === 'object') ? (_LV.localRegistries.get(scope) || _LV.localRegistries.set(scope, new Map()).get(scope)) : _LV.registry;
+        if (registry && registry.has(name) && registry.get(name) !== f) {
+            throw new Error(`Lightview: A signal or state with the name "${name}" is already registered.`);
+        }
+        if (registry) registry.set(name, f);
+
+        // Resolve future signal waiters
+        const futures = _LV.futureSignals.get(name);
+        if (futures) {
+            futures.forEach(resolve => resolve(f));
         }
     }
 
@@ -71,13 +86,37 @@ export const signal = (initialValue, optionsOrName) => {
 };
 
 /**
- * Gets a named signal from the registry.
+ * Gets a named signal, or a 'future' signal if not found.
  */
-export const getSignal = (name, defaultValue) => {
-    if (!_LV.registry.has(name) && defaultValue !== undefined) {
-        return signal(defaultValue, name);
-    }
-    return _LV.registry.get(name);
+export const getSignal = (name, defaultValueOrOptions) => {
+    const options = typeof defaultValueOrOptions === 'object' && defaultValueOrOptions !== null ? defaultValueOrOptions : { defaultValue: defaultValueOrOptions };
+    const { scope, defaultValue } = options;
+
+    const existing = lookup(name, scope);
+    if (existing) return existing;
+
+    if (defaultValue !== undefined) return signal(defaultValue, { name, scope });
+
+    // Return a "Future Signal" that will track the real one once registered
+    const future = signal(undefined);
+    const handler = (realSignal) => {
+        // When the real signal appears, sync the future one
+        // If it's a signal (has .value), track its value. If it's a state proxy or object, it IS the value.
+        const hasValue = realSignal && (typeof realSignal === 'object' || typeof realSignal === 'function') && 'value' in realSignal;
+        if (hasValue) {
+            future.value = realSignal.value;
+            effect(() => {
+                future.value = realSignal.value;
+            });
+        } else {
+            future.value = realSignal;
+        }
+    };
+
+    if (!_LV.futureSignals.has(name)) _LV.futureSignals.set(name, new Set());
+    _LV.futureSignals.get(name).add(handler);
+
+    return future;
 };
 
 // Map .get to signal for backwards compatibility
@@ -131,3 +170,8 @@ export const computed = (fn) => {
  * Returns the global registry.
  */
 export const getRegistry = () => _LV.registry;
+
+/**
+ * Returns the global internals (private use).
+ */
+export const internals = _LV;

package/src/reactivity/state.js

@@ -3,12 +3,53 @@
  * Provides deeply reactive state by wrapping objects/arrays in Proxies.
  */
 
-import { signal as signalFactory, effect, getRegistry } from './signal.js';
+import { signal as signalFactory, effect, getRegistry, internals, lookup } from './signal.js';
 
-// Internal helpers and caches
+// Internal caches
 const stateCache = new WeakMap();
 const stateSignals = new WeakMap();
-const parents = new WeakMap();
+const stateSchemas = new WeakMap();
+const { parents, schemas, hooks } = internals;
+
+/**
+ * Core Validation & Coercion
+ */
+const validate = (target, prop, value, schema) => {
+    const current = target[prop];
+    const type = typeof current;
+    const isNew = !(prop in target);
+
+    // 1. Resolve schema behavior
+    let behavior = schema;
+    if (typeof schema === 'object' && schema !== null) behavior = schema.type;
+
+    if (behavior === 'auto' && isNew) throw new Error(`Lightview: Cannot add new property "${prop}" to fixed 'auto' state.`);
+
+    // 2. Perform Validation/Coercion
+    if (behavior === 'polymorphic' || (typeof behavior === 'object' && behavior?.coerce)) {
+        if (type === 'number') return Number(value);
+        if (type === 'boolean') return Boolean(value);
+        if (type === 'string') return String(value);
+    } else if (behavior === 'auto' || behavior === 'dynamic') {
+        if (!isNew && typeof value !== type) {
+            throw new Error(`Lightview: Type mismatch for "${prop}". Expected ${type}, got ${typeof value}.`);
+        }
+    }
+
+    // 3. Perform Transformations (Lightview Extension)
+    if (typeof schema === 'object' && schema !== null && schema.transform) {
+        const trans = schema.transform;
+        const transformFn = typeof trans === 'function' ? trans : (internals.helpers.get(trans) || globalThis.Lightview?.helpers?.[trans]);
+        if (transformFn) value = transformFn(value);
+    }
+
+    // 4. Delegation to hooks (for full JSON Schema support in JPRX/Lightview-X)
+    if (hooks.validate(value, schema) === false) {
+        throw new Error(`Lightview: Validation failed for "${prop}".`);
+    }
+
+    return value;
+};
 
 // Build method lists dynamically from prototypes
 const protoMethods = (proto, test) => Object.getOwnPropertyNames(proto).filter(k => typeof proto[k] === 'function' && test(k));
@@ -48,12 +89,15 @@ const proxyGet = (target, prop, receiver, signals) => {
 };
 
 const proxySet = (target, prop, value, receiver, signals) => {
+    const schema = stateSchemas.get(receiver);
+    const validatedValue = schema ? validate(target, prop, value, schema) : value;
+
     if (!signals.has(prop)) {
         signals.set(prop, signalFactory(Reflect.get(target, prop, receiver)));
     }
-    const success = Reflect.set(target, prop, value, receiver);
+    const success = Reflect.set(target, prop, validatedValue, receiver);
     const signal = signals.get(prop);
-    if (success && signal) signal.value = value;
+    if (success && signal) signal.value = validatedValue;
     return success;
 };
 
@@ -154,6 +198,8 @@ export const state = (obj, optionsOrName) => {
 
     const name = typeof optionsOrName === 'string' ? optionsOrName : optionsOrName?.name;
     const storage = optionsOrName?.storage;
+    const scope = optionsOrName?.scope;
+    const schema = optionsOrName?.schema;
 
     if (name && storage) {
         try {
@@ -162,7 +208,7 @@ export const state = (obj, optionsOrName) => {
                 const loaded = JSON.parse(item);
                 Array.isArray(obj) && Array.isArray(loaded) ? (obj.length = 0, obj.push(...loaded)) : Object.assign(obj, loaded);
             }
-        } catch (e) { /* Storage access denied or corrupted JSON */ }
+        } catch (e) { /* Ignore */ }
     }
 
     let proxy = stateCache.get(obj);
@@ -183,20 +229,25 @@ export const state = (obj, optionsOrName) => {
         } else return obj;
     }
 
+    if (schema) stateSchemas.set(proxy, schema);
+
     if (name && storage) {
         effect(() => {
-            try { storage.setItem(name, JSON.stringify(proxy)); } catch (e) { /* Persistence failed */ }
+            try { storage.setItem(name, JSON.stringify(proxy)); } catch (e) { /* Ignore */ }
         });
     }
 
     if (name) {
-        const registry = getRegistry();
-        if (registry.has(name)) {
-            if (registry.get(name) !== proxy) {
-                throw new Error(`Lightview: A signal or state with the name "${name}" is already registered.`);
-            }
-        } else {
-            registry.set(name, proxy);
+        const registry = (scope && typeof scope === 'object') ? (internals.localRegistries.get(scope) || internals.localRegistries.set(scope, new Map()).get(scope)) : getRegistry();
+        if (registry && registry.has(name) && registry.get(name) !== proxy) {
+            throw new Error(`Lightview: A signal or state with the name "${name}" is already registered.`);
+        }
+        if (registry) registry.set(name, proxy);
+
+        // Resolve future signal waiters
+        const futures = internals.futureSignals.get(name);
+        if (futures) {
+            futures.forEach(resolve => resolve(proxy));
         }
     }
 
@@ -204,14 +255,26 @@ export const state = (obj, optionsOrName) => {
 };
 
 /**
- * Gets a named state from the registry.
+ * Gets a named state using up-tree search starting from scope.
  */
-export const getState = (name, defaultValue) => {
-    const registry = getRegistry();
-    if (!registry.has(name) && defaultValue !== undefined) {
-        return state(defaultValue, name);
-    }
-    return registry.get(name);
+export const getState = (name, defaultValueOrOptions) => {
+    const options = typeof defaultValueOrOptions === 'object' && defaultValueOrOptions !== null ? defaultValueOrOptions : { defaultValue: defaultValueOrOptions };
+    const { scope, defaultValue } = options;
+
+    const existing = lookup(name, scope);
+    if (existing) return existing;
+
+    if (defaultValue !== undefined) return state(defaultValue, { name, scope });
+
+    // Future State Resolution (similar to getSignal)
+    const future = signalFactory(undefined);
+    const handler = (realState) => {
+        future.value = realState;
+    };
+    if (!internals.futureSignals.has(name)) internals.futureSignals.set(name, new Set());
+    internals.futureSignals.get(name).add(handler);
+
+    return future;
 };
 
 state.get = getState;