ctrl-fx 0.0.1 → 0.1.0

package/dist/dom/views.d.ts

@@ -0,0 +1,60 @@
+import { type Node } from '.';
+import type { Dimensions } from '..';
+import type { Effect } from '../effects';
+import type { InternalLocation } from '../net/location';
+import type { ContainerListener, EventListenerResult, EventOptions, KeyData } from './events';
+import { type NodeId } from './nodeid';
+/**
+ * The return type of a view function: a list of virtual DOM nodes plus optional
+ * container-level event listeners. Create one with `nodeGroup(...)` or the `_` shorthand.
+ */
+export type NodeGroup<State, Event> = {
+    _type: 'NodeGroup';
+    nodes: Node<State, Event>[];
+    containerListeners: ContainerListener<State, Event>[];
+    /** Runs `effect` whenever the component's container is resized, receiving the new dimensions. */
+    onResize(effect: (dimensions: Dimensions) => Effect<State, Event, void>): NodeGroup<State, Event>;
+    /** Runs `effect` when the browser back/forward buttons are used. */
+    onPopState(effect: (location: InternalLocation) => Effect<State, Event, void>): NodeGroup<State, Event>;
+    /** Runs `effect` on any location change, including `pushState` and `replaceState` as well as `popstate`. */
+    onLocationChange(effect: (location: InternalLocation) => Effect<State, Event, void>): NodeGroup<State, Event>;
+    /** Runs `effect` on document-level keyup events. */
+    onKeyUp(effect: (key: KeyData) => Effect<State, Event, EventListenerResult>, options?: EventOptions): NodeGroup<State, Event>;
+    /** Runs `effect` on document-level keydown events. */
+    onKeyDown(effect: (key: KeyData) => Effect<State, Event, EventListenerResult>, options?: EventOptions): NodeGroup<State, Event>;
+    /** Runs `effect` when the page becomes visible or hidden (e.g. user switches tabs). */
+    onVisibilityChange(effect: (state: 'visible' | 'hidden') => Effect<State, Event, void>): NodeGroup<State, Event>;
+    /** Runs `effect` when the browser comes online. */
+    onOnline(effect: Effect<State, Event, void>): NodeGroup<State, Event>;
+    /** Runs `effect` when the browser goes offline. */
+    onOffline(effect: Effect<State, Event, void>): NodeGroup<State, Event>;
+    renderEffects: Effect<State, Event, void>[];
+    /** Runs `effects` once immediately after the component mounts. Use this for initial data loading or setup that requires the DOM to exist. */
+    onRender(...effects: Effect<State, Event, void>[]): NodeGroup<State, Event>;
+};
+/** Creates a `NodeGroup` from zero or more nodes. This is what view functions return. */
+export declare function nodeGroup<State, Event>(...nodes: Node<State, Event>[]): NodeGroup<State, Event>;
+/** Shorthand alias for `nodeGroup`. Useful for grouping nodes without extra verbosity: `_(div_('a'), div_('b'))`. */
+export declare function _<State, Event>(...nodes: Node<State, Event>[]): NodeGroup<State, Event>;
+/** A memoized subtree node produced by `view` or `fixedView`. */
+export type View<State, Params, Event> = {
+    _type: 'View';
+    nodeId: NodeId;
+    params: Params;
+    nodes: (params: Params) => NodeGroup<State, Event>;
+};
+/**
+ * Creates a memoized subtree. The `nodes` function is only re-called when `params` changes
+ * (by reference). Use this to avoid re-rendering expensive subtrees that don't depend on
+ * frequently-changing state.
+ * @param id A stable identifier used to track this view across re-renders. Must be unique among siblings.
+ */
+export declare function view<State, Params, Event>(id: NodeId | string, nodes: (params: Params) => NodeGroup<State, Event> | Node<State, Event>): (params: Params) => View<State, Params, Event>;
+/**
+ * Creates a memoized subtree that never re-renders after mount. The `nodes` function is
+ * called once; subsequent renders reuse the result.
+ * @param id A stable identifier used to track this view across re-renders.
+ */
+export declare function fixedView<State, Event>(id: NodeId | string): (nodes: NodeGroup<State, Event> | Node<State, Event>) => View<State, void, Event>;
+export declare function isNodeGroup<State, Event>(value: unknown): value is NodeGroup<State, Event>;
+//# sourceMappingURL=views.d.ts.map

package/dist/dom/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/dom/views.ts"],"names":[],"mappings":"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"}

package/dist/dom/views.js

@@ -0,0 +1,154 @@
+import {} from '.';
+import { nodeId } from './nodeid';
+/** Creates a `NodeGroup` from zero or more nodes. This is what view functions return. */
+export function nodeGroup(...nodes) {
+    return {
+        _type: 'NodeGroup',
+        nodes,
+        containerListeners: [],
+        onResize(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    {
+                        _type: 'resize',
+                        onChange: effect,
+                        options: {},
+                    },
+                ],
+            };
+        },
+        onPopState(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    {
+                        _type: 'popstate',
+                        onChange: effect,
+                        options: {},
+                    },
+                ],
+            };
+        },
+        onLocationChange(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    {
+                        _type: 'locationchange',
+                        onChange: effect,
+                        options: {},
+                    },
+                ],
+            };
+        },
+        onKeyDown(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    {
+                        _type: 'keydown',
+                        effect,
+                        options: {},
+                    },
+                ],
+            };
+        },
+        onKeyUp(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    { _type: 'keyup', effect, options: {} },
+                ],
+            };
+        },
+        onVisibilityChange(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    { _type: 'visibilitychange', onChange: effect, options: {} },
+                ],
+            };
+        },
+        onOnline(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    { _type: 'online', effect, options: {} },
+                ],
+            };
+        },
+        onOffline(effect) {
+            return {
+                ...this,
+                containerListeners: [
+                    ...this.containerListeners,
+                    { _type: 'offline', effect, options: {} },
+                ],
+            };
+        },
+        renderEffects: [],
+        onRender(...effects) {
+            return {
+                ...this,
+                renderEffects: effects,
+            };
+        },
+    };
+}
+/** Shorthand alias for `nodeGroup`. Useful for grouping nodes without extra verbosity: `_(div_('a'), div_('b'))`. */
+export function _(...nodes) {
+    return nodeGroup(...nodes);
+}
+/**
+ * Creates a memoized subtree. The `nodes` function is only re-called when `params` changes
+ * (by reference). Use this to avoid re-rendering expensive subtrees that don't depend on
+ * frequently-changing state.
+ * @param id A stable identifier used to track this view across re-renders. Must be unique among siblings.
+ */
+export function view(id, nodes) {
+    return (params) => ({
+        _type: 'View',
+        nodeId: typeof id === 'string' ? nodeId(id) : id,
+        params,
+        nodes: (params) => {
+            const nodeOrNodeGroup = nodes(params);
+            return isNodeGroup(nodeOrNodeGroup)
+                ? nodeOrNodeGroup
+                : _(nodeOrNodeGroup);
+        },
+    });
+}
+/**
+ * Creates a memoized subtree that never re-renders after mount. The `nodes` function is
+ * called once; subsequent renders reuse the result.
+ * @param id A stable identifier used to track this view across re-renders.
+ */
+export function fixedView(id) {
+    return nodes => ({
+        _type: 'View',
+        nodeId: typeof id === 'string' ? nodeId(id) : id,
+        params: undefined,
+        nodes: () => (isNodeGroup(nodes) ? nodes : _(nodes)),
+    });
+}
+export function isNodeGroup(value) {
+    if (value === null || value === undefined) {
+        return false;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    return (Object.prototype.hasOwnProperty.call(value, '_type') &&
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        value['_type'] === 'NodeGroup' &&
+        Object.prototype.hasOwnProperty.call(value, 'nodes') &&
+        Object.prototype.hasOwnProperty.call(value, 'containerListeners'));
+}