@cocreate/state 1.29.0 → 2.0.0

package/src/index.js

@@ -6,10 +6,29 @@ import storage from "@cocreate/local-storage";
 
 const { localStorage, sessionStorage } = storage;
 
+async function syncActiveState() {
+    if (!("serviceWorker" in navigator)) return;
+
+    const message = {
+        action: "setActiveState",
+        state: sessionStorage.getItem("state") || "{}",
+        theme: window.matchMedia("(prefers-color-scheme: dark)").matches
+            ? "dark"
+            : "light"
+    };
+    const worker = navigator.serviceWorker.controller ||
+        (await navigator.serviceWorker.ready).active;
+    worker?.postMessage(message);
+}
+
+function syncVisibleState() {
+    if (document.visibilityState === "visible") void syncActiveState();
+}
+
 function init() {
     let elements = document.querySelectorAll("[state-id]");
     initElements(elements);
-    
+
     window.addEventListener("storage", function (e) {
         if (e.key == "state") {
             // Re-initialize only elements that are explicitly listening to storage changes
@@ -19,20 +38,38 @@ function init() {
             initElements(elements);
         }
     });
-    
+
     document.addEventListener("click", function (e) {
-        const target = e.target.closest("[state-to]");
+        const target = e.target.closest("[state-to], [state]");
         if (target) {
             if (target.closest('[actions*="state"]')) return;
             stateAttributes(target);
         }
     });
+
+    window.matchMedia("(prefers-color-scheme: dark)")
+        .addEventListener("change", syncActiveState);
+    navigator.serviceWorker?.addEventListener("controllerchange", syncActiveState);
+    window.addEventListener("focus", syncVisibleState);
+    window.addEventListener("pageshow", syncVisibleState);
+    document.addEventListener("visibilitychange", syncVisibleState);
+    syncVisibleState();
 }
 
+/**
+ *
+ * @public
+ * @environment client
+ */
 function initElements(elements) {
     for (let element of elements) initElement(element);
 }
 
+/**
+ *
+ * @public
+ * @environment client
+ */
 function initElement(element) {
     let state_id = element.getAttribute("state-id");
     if (!state_id) return;
@@ -44,7 +81,7 @@ function initElement(element) {
     let statedAttributes = storageObj.getItem("state");
 
     if (!statedAttributes || statedAttributes.length == 0) return;
-    
+
     try {
         statedAttributes = JSON.parse(statedAttributes);
     } catch(e) {
@@ -63,24 +100,18 @@ function initElement(element) {
 }
 
 function _setAttributeValues(el, attrValues) {
-    let isOverwrite = el.getAttribute("state-overwrite");
-    if (isOverwrite === null || isOverwrite === undefined)
-        isOverwrite = attrValues["overwrite"];
-
-    if ((isOverwrite && isOverwrite != "false") || isOverwrite === "")
-        isOverwrite = true;
-    else if (!isOverwrite || isOverwrite === "false") isOverwrite = false;
-
-    // delete attrValues["overwrite"];
+    const isOverwrite = el.getAttribute("state-overwrite") !== "false";
 
     for (const key of Object.keys(attrValues)) {
         _setAttributeValue(el, key, attrValues[key], isOverwrite);
     }
 }
 
-async function _setAttributeValue(element, attribute, value, isOverwrite) {
+async function _setAttributeValue(element, attribute, value, isOverwrite) {
     if (!element.getAttribute(attribute) || isOverwrite) {
-        if (attribute == "value") {
+        if (attribute === "hidden") {
+            element.hidden = value !== false && value !== "false" && value !== null;
+        } else if (attribute == "value") {
             if (element.value == "" || (element.value && isOverwrite))
                 element.value = value;
             else if (
@@ -104,24 +135,182 @@ async function _setAttributeValue(element, attribute, value, isOverwrite) {
                 }
             }
         }
-    }
-}
-
-async function stateAttributes(element) {
-    let sessionState = {};
-    let localState = {};
-    
-    try { sessionState = JSON.parse(sessionStorage.getItem("state") || "{}"); } catch(e) {}
-    try { localState = JSON.parse(localStorage.getItem("state") || "{}"); } catch(e) {}
-    
+    }
+}
+
+function getStoredState(storageObj) {
+    try {
+        const state = JSON.parse(storageObj.getItem("state") || "{}");
+        return state && typeof state === "object" && !Array.isArray(state)
+            ? state
+            : {};
+    } catch (error) {
+        return {};
+    }
+}
+
+function normalizeUnset(value) {
+    if (Array.isArray(value))
+        return value.map(String).map(key => key.trim()).filter(Boolean);
+    if (typeof value === "string")
+        return value.split(",").map(key => key.trim()).filter(Boolean);
+    return [];
+}
+
+function unsetKeys(state, keys) {
+    if (!state || typeof state !== "object") return false;
+    let changed = false;
+    for (const key of keys) {
+        if (!Object.prototype.hasOwnProperty.call(state, key)) continue;
+        delete state[key];
+        changed = true;
+    }
+    return changed;
+}
+
+function unsetElementValues(element, keys) {
+    for (const key of keys) {
+        if (key.startsWith("$")) {
+            const property = key.slice(1);
+            if (
+                Object.prototype.hasOwnProperty.call(element, property) &&
+                typeof element[property] !== "function"
+            ) {
+                try {
+                    delete element[property];
+                } catch (error) {
+                    element[property] = undefined;
+                }
+            }
+            continue;
+        }
+
+        if (key === "value") {
+            element.setValue("");
+            element.removeAttribute("value");
+        } else {
+            element.removeAttribute(key);
+        }
+    }
+}
+
+function _unsetStateId(keys, stateId) {
+    if (!keys.length) return;
+    const elements = document.querySelectorAll("[state-id]");
+    for (const element of elements) {
+        const ids = (element.getAttribute("state-id") || "")
+            .split(",")
+            .map(id => id.trim())
+            .filter(Boolean);
+        if (ids.includes(stateId)) unsetElementValues(element, keys);
+    }
+}
+
+function mergeState(targetState, state, updates) {
+    if (!state || typeof state !== "object" || Array.isArray(state))
+        return false;
+
+    let changed = false;
+    for (const [stateId, values] of Object.entries(state)) {
+        if (!values || typeof values !== "object" || Array.isArray(values))
+            continue;
+
+        const unset = normalizeUnset(values.$unset);
+        const nextValues = { ...values };
+        delete nextValues.$unset;
+        targetState[stateId] = {
+            ...targetState[stateId],
+            ...nextValues
+        };
+        if (unset.length) {
+            unsetKeys(targetState[stateId], unset);
+            if (updates) updates.push(() => _unsetStateId(unset, stateId));
+            else _unsetStateId(unset, stateId);
+        }
+        const valuesToApply = { ...targetState[stateId] };
+        if (updates) updates.push(() => _getStateId(valuesToApply, stateId));
+        else _getStateId(valuesToApply, stateId);
+        changed = Object.keys(nextValues).length > 0 || unset.length > 0 || changed;
+    }
+
+    return changed;
+}
+
+function persistState({
+    sessionState,
+    localState,
+    sessionChanged,
+    localChanged,
+    title = document.title,
+    updateHistory = true
+}) {
+    if (sessionChanged)
+        sessionStorage.setItem("state", JSON.stringify(sessionState));
+    if (localChanged)
+        localStorage.setItem("state", JSON.stringify(localState));
+    if (sessionChanged) void syncActiveState();
+
+    if (title) document.title = title;
+    if (updateHistory) {
+        history.pushState(
+            {
+                sessionState: JSON.stringify(sessionState),
+                localState: JSON.stringify(localState),
+                title,
+                url: location.href
+            },
+            title,
+            location.href
+        );
+    }
+}
+
+/**
+ *
+ * @public
+ * @environment client
+ */
+function setState(state, options = {}) {
+    const sessionState = getStoredState(sessionStorage);
+    const localState = getStoredState(localStorage);
+    const isLocal =
+        options.storage === "local" || options.localStorage === true;
+    const changed = mergeState(isLocal ? localState : sessionState, state);
+
+    if (!changed) return false;
+
+    persistState({
+        sessionState,
+        localState,
+        sessionChanged: !isLocal,
+        localChanged: isLocal,
+        title: options.title || document.title || ""
+    });
+    return true;
+}
+
+/**
+ *
+ * @public
+ * @environment client
+ */
+async function stateAttributes(element) {
+    let sessionState = getStoredState(sessionStorage);
+    let localState = getStoredState(localStorage);
+
+    const updates = [];
     let elements = [];
 
-    if (element.hasAttribute("state-to")) elements.push(element);
-    let nestedElements = element.querySelectorAll("[state-to]");
+    if (element.hasAttribute("state-to") || element.hasAttribute("state"))
+        elements.push(element);
+    let nestedElements = element.querySelectorAll("[state-to], [state]");
     elements.push(...nestedElements);
     let current = element;
     while (current) {
-        if (current.hasAttribute("state-to") && !elements.includes(current)) {
+        if (
+            (current.hasAttribute("state-to") || current.hasAttribute("state")) &&
+            !elements.includes(current)
+        ) {
             elements.push(current);
         }
         current = current.parentElement;
@@ -133,6 +322,27 @@ async function stateAttributes(element) {
     let triggerIsLocal = element.hasAttribute("state-localstorage") || element.hasAttribute("state-onstoragechange");
 
     for (let i = 0; i < elements.length; i++) {
+        let isLocal =
+            triggerIsLocal ||
+            elements[i].hasAttribute("state-localstorage") ||
+            elements[i].hasAttribute("state-onstoragechange");
+        const targetState = isLocal ? localState : sessionState;
+        const stateValue = elements[i].getAttribute("state");
+
+        if (stateValue) {
+            try {
+                const parsedState = typeof stateValue === "string"
+                    ? JSON.parse(stateValue)
+                    : stateValue;
+                if (mergeState(targetState, parsedState, updates)) {
+                    if (isLocal) localChanged = true;
+                    else sessionChanged = true;
+                }
+            } catch (error) {
+                console.warn("Invalid state JSON:", stateValue, error);
+            }
+        }
+
         let attrValues = await _getAttributeValues(elements[i]);
         if (attrValues.src === "$back" || attrValues.href === "$back") {
             changeState = true;
@@ -149,46 +359,51 @@ async function stateAttributes(element) {
 
         let state_to = elements[i].getAttribute("state-to");
         if (!state_to) continue;
-        
-        let isLocal = triggerIsLocal || elements[i].hasAttribute("state-localstorage") || elements[i].hasAttribute("state-onstoragechange");
-        
-        // Parse state-to string into an array of trimmed individual target keys
-        let stateToKeys = state_to.split(',').map(s => s.trim()).filter(Boolean);
 
-        for (let toKey of stateToKeys) {
-            if (isLocal) {
-                Object.assign(localState, { [`${toKey}`]: attrValues });
-                localChanged = true;
-            } else {
-                Object.assign(sessionState, { [`${toKey}`]: attrValues });
-                sessionChanged = true;
-            }
-            
-            _getStateId(attrValues, toKey);
-        }
-    }
-    
-    let href = element.closest("href");
-    if (!changeState && !href) {
-        // --- IMPROVEMENT: Explicitly support [state-title] only, with document.title fallback (No native 'title' fallback) ---
-        let title = element.getAttribute("state-title") || document.title || "";
-        
-        // --- IMPROVEMENT: Update document.title immediately on click/action ---
-        if (title) {
-            document.title = title;
-        }
-        
-        history.pushState(
-            { sessionState: JSON.stringify(sessionState), localState: JSON.stringify(localState), title, url: location.href },
-            title,
-            location.href
-        );
-    }
-
-    if (!changeState) {
-        if (sessionChanged) sessionStorage.setItem("state", JSON.stringify(sessionState));
-        if (localChanged) localStorage.setItem("state", JSON.stringify(localState));
-    }
+        // Parse state-to string into an array of trimmed individual target keys
+        let stateToKeys = state_to.split(',').map(s => s.trim()).filter(Boolean);
+
+        for (let toKey of stateToKeys) {
+            // A state-to writer defines the complete state for its target.
+            // Replace the prior value so stale attributes and actions do not
+            // survive subsequent writes.
+            const unset = normalizeUnset(attrValues.$unset);
+            const nextValues = { ...attrValues };
+            delete nextValues.$unset;
+
+            if (Object.keys(nextValues).length) {
+                updates.push(() => _getStateId(nextValues, toKey));
+                targetState[toKey] = nextValues;
+            } else if (!targetState[toKey]) {
+                targetState[toKey] = {};
+            }
+
+            if (unset.length) {
+                unsetKeys(targetState[toKey], unset);
+                updates.push(() => _unsetStateId(unset, toKey));
+            }
+
+            if (Object.keys(nextValues).length || unset.length) {
+                if (isLocal) localChanged = true;
+                else sessionChanged = true;
+            }
+        }
+    }
+
+    let href = element.closest("href");
+    if (!changeState) {
+        const title = element.getAttribute("state-title") || document.title || "";
+        persistState({
+            sessionState,
+            localState,
+            sessionChanged,
+            localChanged,
+            title,
+            updateHistory: !href
+        });
+        // Source observers must see the complete selection in X-State.
+        for (const update of updates) update();
+    }
 
     element.dispatchEvent(
         new CustomEvent("stateEnd", {
@@ -252,7 +467,7 @@ window.addEventListener("popstate", function (event) {
         if (event.state.sessionState || event.state.localState) {
             if (event.state.sessionState) sessionStorage.setItem("state", event.state.sessionState);
             if (event.state.localState) localStorage.setItem("state", event.state.localState);
-            
+
             let elements = document.querySelectorAll("[state-id]");
             initElements(elements);
         }
@@ -287,4 +502,91 @@ Action.init({
 
 init();
 
-export default { initElements, initElement, stateAttributes };
+export { setState };
+export default { initElements, initElement, stateAttributes, setState };
+
+/**
+ *
+ * @name state
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name state-id
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name state-localstorage
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name state-onstoragechange
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name state-overwrite
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name state-title
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name state-to
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ *
+ * @name value
+ * @kind member
+ * @attribute
+ * @environment client
+ */
+
+/**
+ * Data attributes which can be used for components in CoCreate framework combined as a group of attributes that dynamically change attributes & fetch custom data.
+ *
+ * @module state
+ * @environment client
+ */
+
+/**
+ * Declarative selectors recognized by this module.
+ *
+ * @name declarative-selectors
+ * @kind member
+ * @selectors
+ * @environment client
+ * @example
+ * ```json
+ * [
+ *   "[state-id]"
+ * ]
+ * ```
+ */

package/test/hidden-state.test.cjs

@@ -0,0 +1,21 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const source = fs.readFileSync(path.join(__dirname, '../src/index.js'), 'utf8');
+const start = source.indexOf('async function _setAttributeValue(');
+const end = source.indexOf('\nfunction getStoredState', start);
+const context = vm.createContext({});
+vm.runInContext(source.slice(start, end), context);
+
+test('state can show and hide a folder section repeatedly', async () => {
+    const element = {
+        hidden: true,
+        getAttribute(name) { return name === 'hidden' && this.hidden ? '' : null; }
+    };
+    for (const [value, expected] of [[false, false], [true, true], ['false', false], ['', true]]) {
+        await context._setAttributeValue(element, 'hidden', value, true);
+        assert.equal(element.hidden, expected);
+    }
+});

package/test/source-state-order.test.cjs

@@ -0,0 +1,84 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const source = fs.readFileSync(path.join(__dirname, '../src/index.js'), 'utf8');
+
+function setup() {
+    let stored = JSON.stringify({ 'offcanvas-app-form': { array: 'apps', object: 'previous' } });
+    const requests = [];
+    const warnings = [];
+    const updates = [];
+    const storage = { getItem: () => stored, setItem: (_, value) => { stored = value; } };
+    const context = vm.createContext({
+        console: { ...console, warn: (...args) => warnings.push(args) }, sessionStorage: storage,
+        localStorage: { getItem: () => '{}', setItem() {} },
+        document: { title: 'Apps' }, location: { href: 'http://localhost/apps' },
+        history: { pushState() {} }, CustomEvent: class {},
+        syncActiveState() {},
+        getStoredState: store => JSON.parse(store.getItem('state')),
+        normalizeUnset: () => [], unsetKeys() {}, _unsetStateId() {},
+        _getAttributeValues: async element => element.values,
+        _getStateId(values, target) {
+            updates.push({ target, values: JSON.parse(JSON.stringify(values)) });
+            if (target === 'offcanvas-app-view') requests.push(JSON.parse(stored)['offcanvas-app-form'].object);
+        }
+    });
+    vm.runInContext(source.slice(source.indexOf('function mergeState('), source.indexOf('function setState(')) +
+        source.slice(source.indexOf('async function stateAttributes('), source.indexOf('async function _getAttributeValues(')), context);
+    return { apply: context.stateAttributes, requests, warnings, updates, getState: () => JSON.parse(stored) };
+}
+
+function element(attributes, values = {}, children = []) {
+    return { values, parentElement: null,
+        getAttribute: name => attributes[name] ?? null,
+        hasAttribute: name => Object.hasOwn(attributes, name),
+        querySelectorAll: () => children, closest: () => null, dispatchEvent() {} };
+}
+
+for (const format of ['nested attributes', 'JSON', 'evaluated object']) {
+    test(`source requests see the newly selected app (${format})`, async () => {
+        const { apply, requests } = setup();
+        for (const id of ['first-app', 'second-app']) {
+            const view = { src: '/apps/apps/aside.html' };
+            const record = { array: 'apps', object: id };
+            const state = { 'offcanvas-app-view': view, 'offcanvas-app-form': record };
+            const trigger = format !== 'nested attributes'
+                ? element({ state: format === 'JSON' ? JSON.stringify(state) : state })
+                : element({ 'state-to': 'offcanvas-app-view' }, view,
+                    [element({ 'state-to': 'offcanvas-app-form' }, record)]);
+            await apply(trigger);
+        }
+        assert.deepEqual(requests, ['first-app', 'second-app']);
+    });
+}
+
+for (const evaluated of [false, true]) {
+    test(`new conversation reset accepts ${evaluated ? 'an AST-evaluated object' : 'JSON text'}`, async () => {
+        const { apply, warnings, updates, getState } = setup();
+        const state = {
+            'ai-conversation-messages': { 'filter-query-value': '', array: '', $renderValue: { object: [] } },
+            'ai-queue-conversation-filter': { 'filter-query-value': '' },
+            aiChat: { 'conversation-id': '' },
+            'ai-chat-conversation-id': { value: '' },
+            'ai-chat-model': { value: 'openai:gpt-5.4-nano', array: 'ai-conversations', object: '', realtime: 'false' }
+        };
+        await apply(element({ state: evaluated ? state : JSON.stringify(state) }));
+        assert.deepEqual(warnings, []);
+        for (const [id, values] of Object.entries(state)) {
+            assert.deepEqual(getState()[id], values);
+            assert.deepEqual(updates.find(update => update.target === id)?.values, values);
+        }
+    });
+}
+
+test('malformed state JSON still warns without changing stored state', async () => {
+    const { apply, warnings, updates, getState } = setup();
+    const before = getState();
+    await apply(element({ state: '{broken' }));
+    assert.equal(warnings.length, 1);
+    assert.equal(warnings[0][0], 'Invalid state JSON:');
+    assert.deepEqual(updates, []);
+    assert.deepEqual(getState(), before);
+});