@srfnstack/fntags 1.3.0 → 1.4.0

package/README.md

@@ -13,7 +13,7 @@ fntags allows you to build complex, interactive web apps using standard JavaScri
 ## Why fntags?
 
 - **No Build Step**: Import the framework directly from a CDN or your file system. No Webpack, no Babel, no headaches.
-- **Granular State**: Bind only what needs to change—text, attributes, or styles—for high-performance updates.
+- **Granular State**: Bind only what needs to change (text, attributes, or styles) for high-performance updates.
 - **Standards Based**: Just standard ES6 JavaScript and HTML5. Zero magic syntax to learn.
 - **Effortless Debugging**: In fntags, there is no black box. Errors produce clean stack traces that point exactly to your source code.
 - **TypeScript Support**: Includes TypeScript definitions out of the box. No need to install separate `@types` packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@srfnstack/fntags",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "author": "Robert Kempton <r@snow87.com>",
   "private": false,
   "homepage": "https://github.com/srfnstack/fntags",

package/src/fntags.d.mts

@@ -13,10 +13,17 @@ export function setDevMode(on: boolean): void;
  *
  * Any attribute starting with 'on' that is a function is added as an event listener with the 'on' removed.
  * i.e. { onclick: fn } gets added to the element as element.addEventListener('click', fn)
+ * An event attribute can also be an array [fn, arg], which calls fn.call(element, arg, event).
+ * For event types passed to delegateEvents, the handler is stored on the element and run by a single
+ * listener on document instead (see delegateEvents for how ordering differs).
  *
  * The style attribute can be an object and the properties of the object will be added as style properties to the element.
  * i.e. { style: { color: blue } } becomes element.style.color = blue
  *
+ * An attribute value of null, undefined or '' means no attribute: it is removed if present and never written,
+ * so { class: '' } produces an element without a class attribute. The value attribute and boolean attributes
+ * (disabled, checked, ...) are exempt and keep their property semantics.
+ *
  * The rest of the arguments will be considered children of this element and appended to it in the same order as passed.
  *
  * @template {HTMLElement|SVGElement} T
@@ -31,10 +38,16 @@ export function h<T extends HTMLElement | SVGElement>(tag: string, ...children:
  * @typedef FnStateObj A container for a state value that can be bound to.
  * @property {(element?: (newValue: T, oldValue: T)=>(Node|any))=>Node} bindAs Bind this state to the given element function. This causes the element to be replaced when the state changes.
  * If called with no parameters, the state's value will be rendered as an element.
- * Do not wrap form inputs (input, textarea, select) in bindAs — it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
+ * Do not wrap form inputs (input, textarea, select) in bindAs: it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
  * @property {(parent: (()=>(Node|any))|any|Node, element: (childState: FnState)=>(Node|any))=>Node} bindChildren Bind the values of this state to the given element.
  * Values are items/elements of an array.
  * If the current value is not an array, this will behave the same as bindAs.
+ * @property {(parent: (()=>(Node|any))|Node, template: (context: any)=>Node, options?: BindRowsOptions)=>Node} bindRows Bind the values of this state
+ * to rows stamped from an fntemplate whose template has a single root element. `values(item, selected)` maps an item to the template's slots and
+ * runs at mount, then only when the item's reference changes or the row gains or loses selection; only changed slots are written. Slots named in
+ * `handlers` are event slots, called as handler(event, item) with the row's current item through one shared function per name.
+ * Rows keep no per-row state or subscriptions, so use this for rows that are a pure function of item and selection, and bindChildren for rows
+ * with their own state or nested reactivity. Items are compared by reference: update them immutably.
  * @property {(prop: string)=>Node} bindProp Bind to a property of an object stored in this state instead of the state itself.
  * Shortcut for `mystate.bindAs((current)=> current[prop])`
  * @property {(attribute?: (newValue: T, oldValue: T)=>(string|any))=>any} bindAttr Bind attribute values to state changes.
@@ -55,6 +68,13 @@ export function h<T extends HTMLElement | SVGElement>(tag: string, ...children:
  * @property {(subscriber: (newState: T, oldState: T)=>void) => void} subscribe Register a callback that will be executed whenever the state is changed
  * @property {boolean} isFnState A flag to indicate that this is a fnstate object
  */
+/**
+ * @typedef BindRowsOptions Options for bindRows.
+ * @property {(item: any, selected: any)=>Object<string, any>} [values] Map an item and the currently selected key to the template's slot values.
+ * Defaults to the item itself. Return a fresh object: it is kept and compared slot by slot against the next result.
+ * A slot value may also be a bind getter (bindAs, bindAttr, bindStyle) or a node; bindings created here are cleaned up when values re-runs or the row is removed.
+ * @property {Object<string, (event: Event, item: any)=>any>} [handlers] Event handlers by slot name. The named slots must be on* attributes.
+ */
 /**
  * @template T The type of data stored in the state container
  * @typedef {FnStateObj<T> & ((newState?: T)=>T)} FnState A container for a state value that can be bound to.
@@ -78,6 +98,34 @@ export function fnstate<T>(initialValue: T, mapKey?: (T: any) => any): FnState<T
  * @returns {Node} The rendered node
  */
 export function renderNode(node: any): Node;
+/**
+ * Opt in to event delegation for the given event types. After this call, an `on<type>` handler on an element
+ * created by h(), or by an fntemplate compiled after this call, is stored on the element as a property
+ * (`element.__fnon_<type>`) instead of being added with addEventListener, and one listener per type is added to
+ * `document`. This saves a listener, and usually a closure, per element, which adds up in long lists.
+ *
+ * Semantics and caveats:
+ * - Only elements created after the call are delegated. Elements that already exist keep their listeners, and
+ *   templates compiled before the call keep using addEventListener for every instance.
+ * - Delegated handlers run when the event bubbles up to `document`, after every native listener on the target
+ *   and its ancestors has run. Calling stopPropagation() in a native listener therefore prevents delegated
+ *   handlers from running, and a delegated handler cannot stop a native listener on an ancestor.
+ * - Among delegated handlers the order is innermost first, like native bubbling: the walk follows the event's
+ *   composed path from the target up to `document`. stopPropagation() (or stopImmediatePropagation()) in a
+ *   delegated handler stops the walk. Removing an element during dispatch does not shorten the walk, because
+ *   the path is fixed when the event is dispatched, as it is for native listeners.
+ * - Inside a delegated handler `this` and `e.currentTarget` are the element the handler belongs to.
+ * - Elements must be connected to the document (directly or through open shadow roots) for handlers to run.
+ * - Events that do not bubble (focus, blur, mouseenter, mouseleave, load, scroll, ...) are never delegated:
+ *   they are skipped with a dev-mode warning and keep using addEventListener.
+ * - Delegation cannot be turned off again for a type.
+ *
+ * Any `on<type>` attribute, delegated or not, also accepts `[fn, arg]`, which calls `fn.call(element, arg, event)`,
+ * so every row of a list can share one handler function instead of allocating a closure per row.
+ *
+ * @param {string|string[]} types the event types to delegate, e.g. ['click', 'input']
+ */
+export function delegateEvents(types: string | string[]): void;
 /**
  * Check if the given value is an object that can be used as attributes
  * @param {any} val The value to check
@@ -137,9 +185,19 @@ export function hmrRoot(container: HTMLElement, appFn: (() => Node) | Node): HTM
  * Create a compiled template function. The returned function takes a single object that contains the properties
  * defined in the template.
  *
- * This allows fast rendering by pre-creating a dom element with the entire template structure then cloning and populating
- * the clone with data from the provided context. This avoids the work of having to re-execute the tag functions
- * one by one and can speed up situations where a similar element is created many times.
+ * The template function receives a context function. Calling `ctx('prop')` returns a placeholder that can be used
+ * as a child, as an attribute value, or as a style value. The template is rendered once to a dom tree; each
+ * instantiation clones that tree and fills the placeholders from the context object, which avoids re-executing
+ * the tag functions and can speed up situations where a similar element is created many times.
+ *
+ * Child placeholders are empty text nodes in the template. A primitive context value is written into the text node
+ * in place. A bindAs/bindSelect getter whose current node is a text node adopts the placeholder as its live node,
+ * so state changes keep updating the clone. A function value is evaluated like renderNode does. Nodes, arrays and
+ * promises replace the placeholder with their rendered node. As with h(), an attribute value of '', null or undefined
+ * (including the initial value of a bound attribute) means no attribute.
+ *
+ * The locations of all placeholders are compiled once into a single firstChild/nextSibling walk over the clone,
+ * which stops at the last bound node, so instantiation does not depend on the size of the unbound parts of the tree.
  *
  * You cannot bind state to the initial template. If you attempt to, the state will be read, but the elements will
  * not be updated when the state changes because they will not be bound to the cloned element.
@@ -157,7 +215,7 @@ export type FnStateObj<T> = {
     /**
      * Bind this state to the given element function. This causes the element to be replaced when the state changes.
      * If called with no parameters, the state's value will be rendered as an element.
-     * Do not wrap form inputs (input, textarea, select) in bindAs — it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
+     * Do not wrap form inputs (input, textarea, select) in bindAs: it replaces the element on every update and the focused input will lose focus mid-keystroke. Bind the `value` attribute with bindAttr instead.
      */
     bindAs: (element?: (newValue: T, oldValue: T) => (Node | any)) => Node;
     /**
@@ -166,6 +224,15 @@ export type FnStateObj<T> = {
      * If the current value is not an array, this will behave the same as bindAs.
      */
     bindChildren: (parent: (() => (Node | any)) | any | Node, element: (childState: any) => (Node | any)) => Node;
+    /**
+     * Bind the values of this state
+     * to rows stamped from an fntemplate whose template has a single root element. `values(item, selected)` maps an item to the template's slots and
+     * runs at mount, then only when the item's reference changes or the row gains or loses selection; only changed slots are written. Slots named in
+     * `handlers` are event slots, called as handler(event, item) with the row's current item through one shared function per name.
+     * Rows keep no per-row state or subscriptions, so use this for rows that are a pure function of item and selection, and bindChildren for rows
+     * with their own state or nested reactivity. Items are compared by reference: update them immutably.
+     */
+    bindRows: (parent: (() => (Node | any)) | Node, template: (context: any) => Node, options?: BindRowsOptions) => Node;
     /**
      * Bind to a property of an object stored in this state instead of the state itself.
      * Shortcut for `mystate.bindAs((current)=> current[prop])`
@@ -222,6 +289,25 @@ export type FnStateObj<T> = {
      */
     isFnState: boolean;
 };
+/**
+ * Options for bindRows.
+ */
+export type BindRowsOptions = {
+    /**
+     * Map an item and the currently selected key to the template's slot values.
+     * Defaults to the item itself. Return a fresh object: it is kept and compared slot by slot against the next result.
+     * A slot value may also be a bind getter (bindAs, bindAttr, bindStyle) or a node; bindings created here are cleaned up when values re-runs or the row is removed.
+     */
+    values?: (item: any, selected: any) => {
+        [x: string]: any;
+    };
+    /**
+     * Event handlers by slot name. The named slots must be on* attributes.
+     */
+    handlers?: {
+        [x: string]: (event: Event, item: any) => any;
+    };
+};
 /**
  * A container for a state value that can be bound to.
  */

package/src/fntags.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fntags.d.mts","sourceRoot":"","sources":["fntags.mjs"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,+BAFW,OAAO,QAIjB;AAQD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,2DALW,MAAM,eACH,CAAC,IAAI,MAAO,CAAC,OAsC1B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,iEAPgB,GAAG,cAqIlB;AAwlBD;;;;;GAKG;AACH,iCAHW,GAAG,GACD,IAAI,CAgChB;AAqFD;;;;GAIG;AACH,6BAHW,GAAG,GACD,OAAO,CAInB;AAED;;;;GAIG;AACH,mCAHW,GAAG,GACF,MAAM,CAIjB;AAED;;;;;;;;;;GAUG;AACH,kEALW,MAAM,GAAC,MAAM,OACb,MAAM,YACN,MAAM,EAAE,GAAC,IAAI,EAAE,KAezB;AAOD;;;;;;;;GAQG;AACH,wCAJW,MAAM,0BAiBhB;AAED;;;;;;;;;GASG;AACH,oCALW,MAAM,gBACN,GAAG,eACE,GAAG,KAAK,MAAM,OAc7B;AAED;;;;;;;;GAQG;AACH,mCAJW,WAAW,SACX,CAAC,MAAI,IAAI,CAAC,GAAC,IAAI,GACb,WAAW,CAWvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qDAJkB,IAAI,iBACH,IAAI,CA+DtB;;;;;;;;;;kCAzjCmC,CAAC,YAAY,CAAC,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;;2BAG/C,CAAC,MAAI,CAAC,IAAI,GAAC,GAAG,CAAC,CAAC,GAAC,GAAG,GAAC,IAAI,gCAAkC,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;qBAG9E,MAAM,KAAG,IAAI;;;;;sCAEI,CAAC,YAAY,CAAC,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;mCAEvC,CAAC,YAAY,CAAC,KAAG,MAAM,KAAK,MAAM;;;;yCAC7B,GAAG,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;+CACrB,GAAG,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;;;kBAC7C,GAAG,KAAG,IAAI;;;;cAGhB,MAAK,GAAG;;;;;qBACC,CAAC,KAAG,IAAI;;;;;;oBAEV,MAAM,KAAG,GAAG;;;;oBAGZ,MAAM,SAAS,GAAG,mBAAmB,OAAO,KAAG,IAAI;;;;uCAClC,CAAC,YAAY,CAAC,KAAG,IAAI,KAAK,IAAI;;;;eACtD,OAAO;;;;;sDAKqB,CAAC,KAAG,CAAC"}
+{"version":3,"file":"fntags.d.mts","sourceRoot":"","sources":["../../../../../../../../Users/r/fntags/.claude/worktrees/agent-a4e6d365c3389d8c1/src/fntags.mjs"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,+BAFW,OAAO,QAIjB;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,2DALW,MAAM,eACH,CAAC,IAAI,MAAO,CAAC,OAM1B;AAuGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,iEAPgB,GAAG,cA0ClB;AA84CD;;;;;GAKG;AACH,iCAHW,GAAG,GACD,IAAI,CAwChB;AA+DD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCAFW,MAAM,GAAC,MAAM,EAAE,QAiBzB;AAoHD;;;;GAIG;AACH,6BAHW,GAAG,GACD,OAAO,CAInB;AAED;;;;GAIG;AACH,mCAHW,GAAG,GACF,MAAM,CAIjB;AAED;;;;;;;;;;GAUG;AACH,kEALW,MAAM,GAAC,MAAM,OACb,MAAM,YACN,MAAM,EAAE,GAAC,IAAI,EAAE,KAezB;AAOD;;;;;;;;GAQG;AACH,wCAJW,MAAM,0BAiBhB;AAED;;;;;;;;;GASG;AACH,oCALW,MAAM,gBACN,GAAG,eACE,GAAG,KAAK,MAAM,OAc7B;AAED;;;;;;;;GAQG;AACH,mCAJW,WAAW,SACX,CAAC,MAAI,IAAI,CAAC,GAAC,IAAI,GACb,WAAW,CAWvB;AAsHD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qDAJkB,IAAI,iBACH,IAAI,CA6HtB;;;;;;;;;;kCA9mEmC,CAAC,YAAY,CAAC,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;;2BAG/C,CAAC,MAAI,CAAC,IAAI,GAAC,GAAG,CAAC,CAAC,GAAC,GAAG,GAAC,IAAI,gCAAkC,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;;;;;;uBAG5E,CAAC,MAAI,CAAC,IAAI,GAAC,GAAG,CAAC,CAAC,GAAC,IAAI,sBAAsB,GAAG,KAAG,IAAI,YAAY,eAAe,KAAG,IAAI;;;;;qBAMzF,MAAM,KAAG,IAAI;;;;;sCAEI,CAAC,YAAY,CAAC,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;mCAEvC,CAAC,YAAY,CAAC,KAAG,MAAM,KAAK,MAAM;;;;yCAC7B,GAAG,KAAG,CAAC,IAAI,GAAC,GAAG,CAAC,KAAG,IAAI;;;;+CACrB,GAAG,KAAG,CAAC,MAAM,GAAC,GAAG,CAAC,KAAG,GAAG;;;;;;kBAC7C,GAAG,KAAG,IAAI;;;;cAGhB,MAAK,GAAG;;;;;qBACC,CAAC,KAAG,IAAI;;;;;;oBAEV,MAAM,KAAG,GAAG;;;;oBAGZ,MAAM,SAAS,GAAG,mBAAmB,OAAO,KAAG,IAAI;;;;uCAClC,CAAC,YAAY,CAAC,KAAG,IAAI,KAAK,IAAI;;;;eACtD,OAAO;;;;;;;;;;;oBAKA,GAAG,YAAY,GAAG;YAAU,MAAM,GAAE,GAAG;;;;;;6BAGvB,KAAK,QAAQ,GAAG,KAAG,GAAG;;;;;;sDAKjB,CAAC,KAAG,CAAC"}