sygnal 5.2.0 → 5.2.1

package/README.md

@@ -404,7 +404,7 @@ import vikeSygnal from 'sygnal/config'
 export default { extends: [vikeSygnal] }
 ```
 
-Pages are standard Sygnal components in `pages/*/+Page.jsx`. Supports layouts, data fetching, and SPA mode.
+Pages are standard Sygnal components in `pages/*/+Page.jsx`. Supports layouts, data fetching, SPA mode, and `ClientOnly` for browser-only components.
 
 ### TypeScript
 

package/dist/astro/client.cjs.js

@@ -5532,7 +5532,7 @@ function component(opts) {
     return returnFunction;
 }
 class Component {
-    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', onError, debug = false }) {
+    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', isolatedState = false, onError, debug = false }) {
         if (!sources || !isObj(sources))
             throw new Error(`[${name}] Missing or invalid sources`);
         this._componentNumber = COMPONENT_COUNT++;
@@ -5554,6 +5554,7 @@ class Component {
         this.requestSourceName = requestSourceName;
         this.sourceNames = Object.keys(sources);
         this.onError = onError;
+        this.isolatedState = isolatedState;
         this._debug = debug;
         // Warn if calculated fields shadow base state keys
         if (this.calculated && this.initialState
@@ -5953,7 +5954,7 @@ class Component {
         const hmrState = ENVIRONMENT?.__SYGNAL_HMR_STATE;
         const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState;
         const initial = { type: INITIALIZE_ACTION, data: effectiveInitialState };
-        if (this.isSubComponent && this.initialState) {
+        if (this.isSubComponent && this.initialState && !this.isolatedState) {
             console.warn(`[${this.name}] Initial state provided to sub-component. This will overwrite any state provided by the parent component.`);
         }
         const hasInitialState = (typeof effectiveInitialState !== 'undefined');
@@ -6134,6 +6135,7 @@ class Component {
             .map((vdom) => processLazy(vdom, this))
             .map(processPortals)
             .map(processTransitions)
+            .map(processClientOnly)
             .compose(this.instantiateSubComponents.bind(this))
             .filter((val) => val !== undefined)
             .compose(this.renderVdom.bind(this));
@@ -7111,6 +7113,31 @@ function processTransitions(vnode) {
     }
     return vnode;
 }
+function processClientOnly(vnode) {
+    if (!vnode || !vnode.sel)
+        return vnode;
+    if (vnode.sel === 'clientonly') {
+        // On the client, unwrap to children (render them normally)
+        const children = vnode.children || [];
+        if (children.length === 0)
+            return { sel: 'div', data: {}, children: [] };
+        if (children.length === 1)
+            return processClientOnly(children[0]);
+        // Multiple children: wrap in a div
+        return {
+            sel: 'div',
+            data: {},
+            children: children.map(processClientOnly),
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
+    if (vnode.children && vnode.children.length > 0) {
+        vnode.children = vnode.children.map(processClientOnly);
+    }
+    return vnode;
+}
 function applyTransitionHooks(vnode, name, duration) {
     const existingInsert = vnode.data?.hook?.insert;
     const existingRemove = vnode.data?.hook?.remove;

package/dist/astro/client.mjs

@@ -5530,7 +5530,7 @@ function component(opts) {
     return returnFunction;
 }
 class Component {
-    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', onError, debug = false }) {
+    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', isolatedState = false, onError, debug = false }) {
         if (!sources || !isObj(sources))
             throw new Error(`[${name}] Missing or invalid sources`);
         this._componentNumber = COMPONENT_COUNT++;
@@ -5552,6 +5552,7 @@ class Component {
         this.requestSourceName = requestSourceName;
         this.sourceNames = Object.keys(sources);
         this.onError = onError;
+        this.isolatedState = isolatedState;
         this._debug = debug;
         // Warn if calculated fields shadow base state keys
         if (this.calculated && this.initialState
@@ -5951,7 +5952,7 @@ class Component {
         const hmrState = ENVIRONMENT?.__SYGNAL_HMR_STATE;
         const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState;
         const initial = { type: INITIALIZE_ACTION, data: effectiveInitialState };
-        if (this.isSubComponent && this.initialState) {
+        if (this.isSubComponent && this.initialState && !this.isolatedState) {
             console.warn(`[${this.name}] Initial state provided to sub-component. This will overwrite any state provided by the parent component.`);
         }
         const hasInitialState = (typeof effectiveInitialState !== 'undefined');
@@ -6132,6 +6133,7 @@ class Component {
             .map((vdom) => processLazy(vdom, this))
             .map(processPortals)
             .map(processTransitions)
+            .map(processClientOnly)
             .compose(this.instantiateSubComponents.bind(this))
             .filter((val) => val !== undefined)
             .compose(this.renderVdom.bind(this));
@@ -7109,6 +7111,31 @@ function processTransitions(vnode) {
     }
     return vnode;
 }
+function processClientOnly(vnode) {
+    if (!vnode || !vnode.sel)
+        return vnode;
+    if (vnode.sel === 'clientonly') {
+        // On the client, unwrap to children (render them normally)
+        const children = vnode.children || [];
+        if (children.length === 0)
+            return { sel: 'div', data: {}, children: [] };
+        if (children.length === 1)
+            return processClientOnly(children[0]);
+        // Multiple children: wrap in a div
+        return {
+            sel: 'div',
+            data: {},
+            children: children.map(processClientOnly),
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
+    if (vnode.children && vnode.children.length > 0) {
+        vnode.children = vnode.children.map(processClientOnly);
+    }
+    return vnode;
+}
 function applyTransitionHooks(vnode, name, duration) {
     const existingInsert = vnode.data?.hook?.insert;
     const existingRemove = vnode.data?.hook?.remove;

package/dist/astro/server.cjs.js

@@ -172,6 +172,24 @@ function processSSRTree(vnode, context, parentState) {
             key: undefined,
         };
     }
+    // ClientOnly: render fallback during SSR, skip children (they need a browser)
+    if (sel === 'clientonly') {
+        const props = vnode.data?.props || {};
+        const fallback = props.fallback;
+        if (fallback) {
+            // fallback can be a VNode or a string
+            return processSSRTree(fallback, context, parentState);
+        }
+        // No fallback — render an empty placeholder div
+        return {
+            sel: 'div',
+            data: { attrs: { 'data-sygnal-clientonly': '' } },
+            children: [],
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
     // Slot: unwrap to children
     if (sel === 'slot') {
         const children = vnode.children || [];

package/dist/astro/server.mjs

@@ -168,6 +168,24 @@ function processSSRTree(vnode, context, parentState) {
             key: undefined,
         };
     }
+    // ClientOnly: render fallback during SSR, skip children (they need a browser)
+    if (sel === 'clientonly') {
+        const props = vnode.data?.props || {};
+        const fallback = props.fallback;
+        if (fallback) {
+            // fallback can be a VNode or a string
+            return processSSRTree(fallback, context, parentState);
+        }
+        // No fallback — render an empty placeholder div
+        return {
+            sel: 'div',
+            data: { attrs: { 'data-sygnal-clientonly': '' } },
+            children: [],
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
     // Slot: unwrap to children
     if (sel === 'slot') {
         const children = vnode.children || [];

package/dist/index.cjs.js

@@ -2270,7 +2270,7 @@ function component(opts) {
     return returnFunction;
 }
 class Component {
-    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', onError, debug = false }) {
+    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', isolatedState = false, onError, debug = false }) {
         if (!sources || !isObj(sources))
             throw new Error(`[${name}] Missing or invalid sources`);
         this._componentNumber = COMPONENT_COUNT++;
@@ -2292,6 +2292,7 @@ class Component {
         this.requestSourceName = requestSourceName;
         this.sourceNames = Object.keys(sources);
         this.onError = onError;
+        this.isolatedState = isolatedState;
         this._debug = debug;
         // Warn if calculated fields shadow base state keys
         if (this.calculated && this.initialState
@@ -2691,7 +2692,7 @@ class Component {
         const hmrState = ENVIRONMENT?.__SYGNAL_HMR_STATE;
         const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState;
         const initial = { type: INITIALIZE_ACTION, data: effectiveInitialState };
-        if (this.isSubComponent && this.initialState) {
+        if (this.isSubComponent && this.initialState && !this.isolatedState) {
             console.warn(`[${this.name}] Initial state provided to sub-component. This will overwrite any state provided by the parent component.`);
         }
         const hasInitialState = (typeof effectiveInitialState !== 'undefined');
@@ -2872,6 +2873,7 @@ class Component {
             .map((vdom) => processLazy(vdom, this))
             .map(processPortals)
             .map(processTransitions)
+            .map(processClientOnly)
             .compose(this.instantiateSubComponents.bind(this))
             .filter((val) => val !== undefined)
             .compose(this.renderVdom.bind(this));
@@ -3849,6 +3851,31 @@ function processTransitions(vnode) {
     }
     return vnode;
 }
+function processClientOnly(vnode) {
+    if (!vnode || !vnode.sel)
+        return vnode;
+    if (vnode.sel === 'clientonly') {
+        // On the client, unwrap to children (render them normally)
+        const children = vnode.children || [];
+        if (children.length === 0)
+            return { sel: 'div', data: {}, children: [] };
+        if (children.length === 1)
+            return processClientOnly(children[0]);
+        // Multiple children: wrap in a div
+        return {
+            sel: 'div',
+            data: {},
+            children: children.map(processClientOnly),
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
+    if (vnode.children && vnode.children.length > 0) {
+        vnode.children = vnode.children.map(processClientOnly);
+    }
+    return vnode;
+}
 function applyTransitionHooks(vnode, name, duration) {
     const existingInsert = vnode.data?.hook?.insert;
     const existingRemove = vnode.data?.hook?.remove;
@@ -5842,6 +5869,63 @@ function renderComponent(componentDef, options = {}) {
     };
 }
 
+/**
+ * Reducer helpers for common state update patterns.
+ *
+ * These reduce boilerplate in model definitions by providing
+ * shorthand factories for the most frequent reducer shapes.
+ */
+// ── set() ──────────────────────────────────────────────────────────
+/**
+ * Create a reducer that merges a partial update into state.
+ *
+ * Static form — merge a fixed object:
+ *   set({ isEditing: true })
+ *
+ * Dynamic form — function receives (state, data, next, props) and
+ * returns the partial update to merge:
+ *   set((state, title) => ({ title }))
+ */
+function set(partial) {
+    if (typeof partial === 'function') {
+        return (state, data, next, props) => ({
+            ...state,
+            ...partial(state, data, next, props),
+        });
+    }
+    return (state) => ({ ...state, ...partial });
+}
+// ── toggle() ───────────────────────────────────────────────────────
+/**
+ * Create a reducer that toggles a boolean field on state.
+ *
+ *   toggle('showModal')
+ *   // equivalent to: (state) => ({ ...state, showModal: !state.showModal })
+ */
+function toggle(field) {
+    return (state) => ({ ...state, [field]: !state[field] });
+}
+// ── emit() ─────────────────────────────────────────────────────────
+/**
+ * Create a model entry that emits an EVENTS bus event.
+ *
+ * With static data:
+ *   emit('DELETE_LANE', { laneId: 42 })
+ *
+ * With dynamic data derived from state:
+ *   emit('DELETE_LANE', (state) => ({ laneId: state.id }))
+ *
+ * Fire-and-forget (no data):
+ *   emit('REFRESH')
+ */
+function emit(type, data) {
+    return {
+        EVENTS: typeof data === 'function'
+            ? (state, actionData, next, props) => ({ type, data: data(state, actionData, next, props) })
+            : () => ({ type, data }),
+    };
+}
+
 /**
  * Server-Side Rendering utilities for Sygnal components.
  *
@@ -6012,6 +6096,24 @@ function processSSRTree(vnode, context, parentState) {
             key: undefined,
         };
     }
+    // ClientOnly: render fallback during SSR, skip children (they need a browser)
+    if (sel === 'clientonly') {
+        const props = vnode.data?.props || {};
+        const fallback = props.fallback;
+        if (fallback) {
+            // fallback can be a VNode or a string
+            return processSSRTree(fallback, context, parentState);
+        }
+        // No fallback — render an empty placeholder div
+        return {
+            sel: 'div',
+            data: { attrs: { 'data-sygnal-clientonly': '' } },
+            children: [],
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
     // Slot: unwrap to children
     if (sel === 'slot') {
         const children = vnode.children || [];
@@ -6517,6 +6619,7 @@ exports.createElement = createElement;
 exports.createRef = createRef;
 exports.createRef$ = createRef$;
 exports.driverFromAsync = driverFromAsync;
+exports.emit = emit;
 exports.enableHMR = enableHMR;
 exports.exactState = exactState;
 exports.getDevTools = getDevTools;
@@ -6530,6 +6633,8 @@ exports.processForm = processForm;
 exports.renderComponent = renderComponent;
 exports.renderToString = renderToString;
 exports.run = run;
+exports.set = set;
 exports.switchable = switchable;
 exports.thunk = thunk;
+exports.toggle = toggle;
 exports.xs = xs;

package/dist/index.d.ts

@@ -378,6 +378,40 @@ export function enableHMR<STATE = any, DRIVERS = {}>(
 export function classes(...classes: ClassesType): string
 export function exactState<STATE>(): <ACTUAL extends STATE>(state: ExactShape<STATE, ACTUAL>) => STATE
 
+// ── Reducer helpers ────────────────────────────────────────────────
+
+/**
+ * Create a reducer that merges a partial update into state.
+ *
+ * Static form — merge a fixed object:
+ *   `set({ isEditing: true })`
+ *
+ * Dynamic form — function receives (state, data, next, props) and
+ * returns the partial update to merge:
+ *   `set((state, title) => ({ title }))`
+ */
+export function set<S = any>(
+  partial: Partial<S> | ((state: S, data: any, next: Function, props: any) => Partial<S>)
+): (state: S, data: any, next: Function, props: any) => S
+
+/**
+ * Create a reducer that toggles a boolean field on state.
+ *
+ *   `toggle('showModal')`
+ */
+export function toggle<S = any>(field: keyof S & string): (state: S) => S
+
+/**
+ * Create a model entry that emits an EVENTS bus event.
+ *
+ *   `emit('DELETE_LANE', (state) => ({ laneId: state.id }))`
+ *   `emit('REFRESH')`
+ */
+export function emit(
+  type: string,
+  data?: any | ((state: any, actionData: any, next: Function, props: any) => any)
+): { EVENTS: (state: any, actionData: any, next: Function, props: any) => { type: string; data: any } }
+
 /**
  * Any object with an events() method (e.g., DOM.select('form')).
  * Uses permissive signature to be compatible with MainDOMSource's overloaded events().

package/dist/index.esm.js

@@ -2253,7 +2253,7 @@ function component(opts) {
     return returnFunction;
 }
 class Component {
-    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', onError, debug = false }) {
+    constructor({ name = 'NO NAME', sources, intent, model, hmrActions, context, response, view, peers = {}, components = {}, initialState, calculated, storeCalculatedInState = true, DOMSourceName = 'DOM', stateSourceName = 'STATE', requestSourceName = 'HTTP', isolatedState = false, onError, debug = false }) {
         if (!sources || !isObj(sources))
             throw new Error(`[${name}] Missing or invalid sources`);
         this._componentNumber = COMPONENT_COUNT++;
@@ -2275,6 +2275,7 @@ class Component {
         this.requestSourceName = requestSourceName;
         this.sourceNames = Object.keys(sources);
         this.onError = onError;
+        this.isolatedState = isolatedState;
         this._debug = debug;
         // Warn if calculated fields shadow base state keys
         if (this.calculated && this.initialState
@@ -2674,7 +2675,7 @@ class Component {
         const hmrState = ENVIRONMENT?.__SYGNAL_HMR_STATE;
         const effectiveInitialState = (typeof hmrState !== 'undefined') ? hmrState : this.initialState;
         const initial = { type: INITIALIZE_ACTION, data: effectiveInitialState };
-        if (this.isSubComponent && this.initialState) {
+        if (this.isSubComponent && this.initialState && !this.isolatedState) {
             console.warn(`[${this.name}] Initial state provided to sub-component. This will overwrite any state provided by the parent component.`);
         }
         const hasInitialState = (typeof effectiveInitialState !== 'undefined');
@@ -2855,6 +2856,7 @@ class Component {
             .map((vdom) => processLazy(vdom, this))
             .map(processPortals)
             .map(processTransitions)
+            .map(processClientOnly)
             .compose(this.instantiateSubComponents.bind(this))
             .filter((val) => val !== undefined)
             .compose(this.renderVdom.bind(this));
@@ -3832,6 +3834,31 @@ function processTransitions(vnode) {
     }
     return vnode;
 }
+function processClientOnly(vnode) {
+    if (!vnode || !vnode.sel)
+        return vnode;
+    if (vnode.sel === 'clientonly') {
+        // On the client, unwrap to children (render them normally)
+        const children = vnode.children || [];
+        if (children.length === 0)
+            return { sel: 'div', data: {}, children: [] };
+        if (children.length === 1)
+            return processClientOnly(children[0]);
+        // Multiple children: wrap in a div
+        return {
+            sel: 'div',
+            data: {},
+            children: children.map(processClientOnly),
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
+    if (vnode.children && vnode.children.length > 0) {
+        vnode.children = vnode.children.map(processClientOnly);
+    }
+    return vnode;
+}
 function applyTransitionHooks(vnode, name, duration) {
     const existingInsert = vnode.data?.hook?.insert;
     const existingRemove = vnode.data?.hook?.remove;
@@ -5825,6 +5852,63 @@ function renderComponent(componentDef, options = {}) {
     };
 }
 
+/**
+ * Reducer helpers for common state update patterns.
+ *
+ * These reduce boilerplate in model definitions by providing
+ * shorthand factories for the most frequent reducer shapes.
+ */
+// ── set() ──────────────────────────────────────────────────────────
+/**
+ * Create a reducer that merges a partial update into state.
+ *
+ * Static form — merge a fixed object:
+ *   set({ isEditing: true })
+ *
+ * Dynamic form — function receives (state, data, next, props) and
+ * returns the partial update to merge:
+ *   set((state, title) => ({ title }))
+ */
+function set(partial) {
+    if (typeof partial === 'function') {
+        return (state, data, next, props) => ({
+            ...state,
+            ...partial(state, data, next, props),
+        });
+    }
+    return (state) => ({ ...state, ...partial });
+}
+// ── toggle() ───────────────────────────────────────────────────────
+/**
+ * Create a reducer that toggles a boolean field on state.
+ *
+ *   toggle('showModal')
+ *   // equivalent to: (state) => ({ ...state, showModal: !state.showModal })
+ */
+function toggle(field) {
+    return (state) => ({ ...state, [field]: !state[field] });
+}
+// ── emit() ─────────────────────────────────────────────────────────
+/**
+ * Create a model entry that emits an EVENTS bus event.
+ *
+ * With static data:
+ *   emit('DELETE_LANE', { laneId: 42 })
+ *
+ * With dynamic data derived from state:
+ *   emit('DELETE_LANE', (state) => ({ laneId: state.id }))
+ *
+ * Fire-and-forget (no data):
+ *   emit('REFRESH')
+ */
+function emit(type, data) {
+    return {
+        EVENTS: typeof data === 'function'
+            ? (state, actionData, next, props) => ({ type, data: data(state, actionData, next, props) })
+            : () => ({ type, data }),
+    };
+}
+
 /**
  * Server-Side Rendering utilities for Sygnal components.
  *
@@ -5995,6 +6079,24 @@ function processSSRTree(vnode, context, parentState) {
             key: undefined,
         };
     }
+    // ClientOnly: render fallback during SSR, skip children (they need a browser)
+    if (sel === 'clientonly') {
+        const props = vnode.data?.props || {};
+        const fallback = props.fallback;
+        if (fallback) {
+            // fallback can be a VNode or a string
+            return processSSRTree(fallback, context, parentState);
+        }
+        // No fallback — render an empty placeholder div
+        return {
+            sel: 'div',
+            data: { attrs: { 'data-sygnal-clientonly': '' } },
+            children: [],
+            text: undefined,
+            elm: undefined,
+            key: undefined,
+        };
+    }
     // Slot: unwrap to children
     if (sel === 'slot') {
         const children = vnode.children || [];
@@ -6474,4 +6576,4 @@ function buildAttributes(data, selectorId, selectorClasses) {
     return result;
 }
 
-export { ABORT, Collection, MainDOMSource, MockedDOMSource, Portal, Slot, Suspense, Switchable, Transition, classes, collection, component, createCommand, createElement, createRef, createRef$, driverFromAsync, enableHMR, exactState, getDevTools, lazy, makeDOMDriver, makeDragDriver, mockDOMSource, Portal as portal, processDrag, processForm, renderComponent, renderToString, run, switchable, thunk, xs };
+export { ABORT, Collection, MainDOMSource, MockedDOMSource, Portal, Slot, Suspense, Switchable, Transition, classes, collection, component, createCommand, createElement, createRef, createRef$, driverFromAsync, emit, enableHMR, exactState, getDevTools, lazy, makeDOMDriver, makeDragDriver, mockDOMSource, Portal as portal, processDrag, processForm, renderComponent, renderToString, run, set, switchable, thunk, toggle, xs };