assign-gingerly 0.0.53 → 0.0.55

package/inferencer/types/roundabout/types.d.ts

@@ -0,0 +1,268 @@
+export type Key<T = any> = keyof T & string;
+
+export type Keysh<T = any> = Key<T> | Array<Key<T>>;
+
+type PropsToProps<Props> = (x: Props) => (Promise<Partial<Props>> | Partial<Props>)
+
+export interface LogicOp<Props = any, TActions = Props>{
+    /**
+     * Supported by trans-render
+     */
+    ifAllOf?: Keysh<Props>,
+
+    ifKeyIn?: Keysh<Props>,  
+
+    ifNoneOf?: Keysh<Props>,
+
+    ifEquals?: Array<Key<Props>>,
+
+    ifAtLeastOneOf?: Keysh<Props>,
+
+    ifNotAllOf?: Keysh<Props>,
+
+    debug?: boolean,
+
+    delay?: number,
+
+}
+
+/**
+ * Extends LogicOp with a `do` property for specifying which function to call.
+ * Used by positractions where the function is generic and view-model-neutral.
+ */
+export interface LogicOpWithDo<Props = any, TActions = Props> extends LogicOp<Props, TActions>{
+    do?:
+        | Function
+        | (keyof TActions & string)
+        | PropsToProps<Props>
+}
+
+export type Actions<TProps = any, TActions = TProps> = 
+    Partial<{[key in keyof TActions & string]: LogicOp<TProps>}>
+    //& Partial<{[key in `do_${keyof TActions & string}_on`]: Key<TActions> | Array<Key<TActions>> }> 
+;
+
+export type Compacts<TProps = any, TActions = TProps, TEvents extends string = string> = 
+    Partial<{[key in `negate_${keyof TProps & string}_to_${keyof TProps & string}`]: number}>
+    | Partial<{[key in `pass_length_of_${keyof TProps & string}_to_${keyof TProps & string}`]: number}>
+    | Partial<{[key in `echo_${keyof TProps & string}_to_${keyof TProps & string}`]: number}>
+    | Partial<{[key in `echo_${keyof TProps & string}_to_${keyof TProps & string}_after`]: keyof TProps}>
+    | Partial<{[key in `when_${keyof TProps & string}_changes_call_${keyof TActions & string}`]: number}>
+    | Partial<{[key in `when_${keyof TProps & string}_changes_toggle_${keyof TProps & string}`]: number}>
+    | Partial<{[key in `when_${keyof TProps & string}_changes_inc_${keyof TProps & string}_by`]: number}>
+    | Partial<{[key in `when_${keyof TProps & string}_changes_dispatch`]: string}>
+    | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_inc_${keyof TProps & string}_by`]: number}>
+    | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_set_${keyof TProps & string}_to`]: any}>
+;
+
+export type Hitches<TProps = any, TActions = TProps> = 
+    | Partial<{[key in `when_${keyof TProps & string}_emits_${keyof TProps & string}_inc_${keyof TProps & string}_by`]: number}>   
+;
+
+export type Handlers<ETProps = any, TActions = ETProps> = 
+    | Partial<{[key in `${keyof ETProps & string}_to_${keyof TActions & string}_on` & string]: string }>;
+
+    export type Positractions<TProps = any, TActions = TProps> = 
+    | Array<Positraction<TProps, TActions>>;
+
+export interface Positraction<TProps = any, TActions = TProps> extends LogicOpWithDo<TProps, TActions> {
+    do: 
+        | Function 
+        | (keyof TActions & string)
+        | PropsToProps<TProps>
+    ifKeyIn?: Array<keyof TProps & string>,
+    ifAllOf?: Array<keyof TProps & string>,
+    //ifNoneOf: Array<keyof TProps & string>,
+    
+    pass?: Array<(keyof TProps & string) | number | boolean | '$0' | '$0+' | `\`${string}\``>,
+    assignTo?: Array<null | (keyof TProps & string)>
+}
+
+/**
+ * A merge is a fully JSON-serializable reactive rule.
+ * When its conditions are met, it calls assignFrom(vm, assignFrom, { from: vm })
+ * to resolve RHS path strings against the vm and assign the results into the vm.
+ * No method or code is required.
+ */
+export interface Merge<TProps = any> extends LogicOp<TProps> {
+    /**
+     * Pattern object whose keys are LHS assignGingerly paths and whose
+     * values are RHS `?.`-prefixed path strings resolved against the vm.
+     */
+    assign: Record<string, any>;
+}
+
+export type Merges<TProps = any> = Array<Merge<TProps>>;
+
+/**
+ * A yield derives a value from a collection using an index or key.
+ * Scenario I: Single selection by index — when the source array or index changes,
+ * the target property is set to source[index].
+ */
+export interface YieldConfig<TProps = any> {
+    /** The source array/collection property name */
+    from: keyof TProps & string;
+    /** The index property name (for array index lookup) */
+    atIndex?: keyof TProps & string;
+    /**
+     * Behavior when the index is out of bounds.
+     * - 'undefined' (default): set target to undefined
+     * - 'clamp': reset the index to 0 (selects first item)
+     */
+    outOfBounds?: 'undefined' | 'clamp';
+    // Future: atKey, atIndices, keyProp, etc.
+}
+
+export type Yields<TProps = any> = {
+    [K in keyof TProps & string]?: YieldConfig<TProps>;
+};
+
+export interface RAConfig<
+        TProps = unknown, TActions = TProps, ETProps = TProps, 
+        TCustomData = unknown, TEvents extends string = string > {
+    actions?: Actions<TProps,TActions>,
+    compacts?: Compacts<TProps, TActions, TEvents>,
+    //onsets?: Onsets<TProps, TActions>,
+    handlers?: Handlers<ETProps, TActions>,
+    hitches?: Hitches<TProps, TActions>,
+    positractions?: Positractions<TProps>,
+    merges?: Merges<TProps>,
+    yields?: Yields<TProps>,
+    /**
+     * Properties to explicitly monitor and propagate changes for.
+     * Use this to ensure getter/setters are installed for properties
+     * that aren't referenced by actions, compacts, merges, etc.
+     * but still need to fire propagator events (e.g., attribute-parsed
+     * properties that other features subscribe to).
+     */
+    propagate?: keyof TProps & string | Array<keyof TProps & string>,
+    /**
+     * Configure automatic WeakRef wrapping for properties
+     * 
+     * Properties listed here will automatically wrap values in WeakRef when set,
+     * and automatically deref when accessed. This prevents memory leaks for
+     * DOM elements and other objects that should be garbage collected.
+     * 
+     * Options:
+     * - Array of property names: ['trigger', 'enhancedElement']
+     * - Object with configuration: { properties: ['trigger'], logIfCollected: 'warn' }
+     * 
+     * When a WeakRef'd value is garbage collected, the getter returns undefined.
+     * Use logIfCollected to get notified when this happens.
+     */
+    weakRef?: WeakRefConfig<TProps>,
+
+    defaultPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
+
+    customData?: TCustomData,
+
+    initialPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
+}
+
+export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps> extends RAConfig<TProps, TActions, ETProps> {
+    vm?: TProps & TActions & RoundaboutReady,
+    //for enhanced elements, pass in the container, referenced via $0.
+    container?: EventTarget,
+    
+    //mountObservers?: Set<IMountObserver>
+    
+    /**
+     * Enable internal routing optimization for actions (default: false)
+     * 
+     * When true: Action results are batched and cascaded before firing events.
+     * - Eliminates redundant action calls in diamond dependency patterns
+     * - More predictable: actions run once per logical change
+     * - Best for: Complex cascades, multiple properties returned from actions
+     * 
+     * When false: Uses traditional approach with immediate event firing.
+     * - Simpler execution model, easier to debug
+     * - Slightly faster for simple linear cascades
+     * - Best for: Simple cascades, performance-critical paths
+     * 
+     * Enable if you have:
+     * - Actions that return multiple properties
+     * - Multiple actions monitoring the same properties
+     * - Diamond dependencies (A→B, A→C, B→D, C→D)
+     */
+    internalRouting?: boolean,
+
+    /**
+     * Options passed to every internal assignGingerly call.
+     * See IAssignGingerlyOptions in assign-gingerly for details.
+     */
+    assignGingerlyOptions?: import('../assign-gingerly/types.js').IAssignGingerlyOptions,
+
+    /**
+     * Protocol handlers for resolving protocol-prefixed values in initialPropVals.
+     * When present, roundabout uses assignFrom (with protocol resolution and "..." spread)
+     * instead of plain assignGingerly for applying initial property values.
+     * 
+     * @example
+     * protocols: {
+     *     globalThis: (key) => globalThis[key],
+     *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
+     * }
+     */
+    protocols?: Record<string, (key: string) => any | Promise<any>>,
+    
+
+}
+
+/**
+ * Configuration for automatic WeakRef wrapping
+ */
+export interface WeakRefConfig<TProps = any> {
+    /**
+     * Properties to automatically wrap in WeakRef
+     */
+    properties: Array<keyof TProps & string>;
+    
+    /**
+     * Logging behavior when deref returns null/undefined
+     * - 'error': console.error (default)
+     * - 'warn': console.warn
+     * - 'silent': no logging
+     * - function: custom logging function
+     */
+    logIfCollected?: 'error' | 'warn' | 'silent' | ((propName: string) => void);
+}
+
+export interface RoundaboutReady{
+    /**
+     * Allow for assigning to read only props via the "backdoor"
+     * Bypasses getters / setters, sets directly to (private) memory slots
+     * Doesn't do any notification
+     * Allows for nested property setting
+    */
+    covertAssignment(obj: any): Promise<void>;
+
+    /**
+     * fires event with name matching the name of the property when the value changes (but not via covertAssignment)
+     * when property is set via public interface, not (immediately) via an action method's return object
+     */
+    readonly propagator : EventTarget | undefined;
+
+    /**
+     * 
+     * https://github.com/whatwg/dom/issues/1296
+     */
+    //readonly disconnectedSignal: AbortSignal
+
+    RAController: AbortController;
+
+    /**
+     * During this time, queues/buses continue to perform "bookkeeping"
+     * but doesn't process the queue until sleep property becomes falsy.
+     * If truthy, can call await awake() before processing should resume
+     * [TODO]
+     */  
+    readonly sleep?: number | undefined;
+
+    awake(): Promise<void>;
+
+    //make the value sleep 1 step closer to be falsy
+    nudge(): void;
+
+    //make the value of sleep 1 step further away from being falsy
+    rock(): void;
+}

package/inferencer/types/soak-up/types.d.ts

@@ -0,0 +1,40 @@
+import { ElementEnhancementGateway, SpawnContext } from "../assign-gingerly/types";
+import { StatementsResult } from "../nested-regex-groups/types";
+
+export interface SoakUpParameters {
+    propMap: string;
+    sourceSpecifierString: string;
+}
+
+export interface PropMap {
+    srcProp: string;
+    destProp?: string;
+}
+
+export interface SoakUpRule {
+    propMap: string;
+    sourceSpecifierString: string;
+    parsedPropMap?: PropMap[];
+}
+
+export interface EndUserProps {
+    soakUpRules: StatementsResult<SoakUpParameters>;
+}
+
+export interface AllProps extends EndUserProps {
+    enhancedElement: Element;
+    parsedRules: SoakUpRule[];
+    resolved: boolean;
+}
+
+export type AP = AllProps;
+
+export type PAP = Partial<AP>;
+
+export type ProPAP = Promise<PAP>;
+
+export interface Actions {
+    init(self: AP, enhancedElement: Element & ElementEnhancementGateway, ctx: SpawnContext, initVals: PAP): Promise<void>;
+    fullyParse(self: AP): PAP;
+    hydrate(self: AP): ProPAP;
+}

package/inferencer/types/templ-maker/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Context passed to the TemplateMaker feature constructor
+ */
+export interface FeatureSpawnContext {
+    key: string;
+    optIn: any;
+    injection: any;
+    featuresRegistry: any;
+    shared?: any;
+}
+
+/**
+ * Tracks whether the seed DOM fragment came from a shadow root or light DOM children.
+ */
+export type TemplateSource = 'shadow' | 'light';
+
+/**
+ * Properties that the TemplateMaker feature exposes.
+ */
+export interface TemplateMakerProps {
+    /**
+     * The cloned DocumentFragment from the stored template.
+     */
+    clone: DocumentFragment | null;
+}
+
+/**
+ * Internal state
+ */
+export interface AllProps extends TemplateMakerProps {
+    /**
+     * WeakRef to the host custom element
+     */
+    hostRef: WeakRef<Element> | null;
+
+    /**
+     * Whether the template source was shadow DOM or light DOM.
+     */
+    templateSource: TemplateSource | null;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AP>;

package/inferencer/types/time-ticker/types.d.ts

@@ -0,0 +1,62 @@
+import { SpawnContext } from "../assign-gingerly/types";
+import {FaceUpProps} from "../face-up/types";
+
+/**
+ * Configuration/properties that the TimeTicker feature exposes
+ */
+export interface FeatureProps {
+    /**
+     * Duration in milliseconds between ticks
+     */
+    duration: number;
+
+    /**
+     * Whether the ticker is disabled (stops ticking when true)
+     */
+    disabled: boolean;
+}
+
+/**
+ * Internal state (not exposed to consumers)
+ */
+export interface AllFeatureProps extends FeatureProps {
+    host: WeakRef<Element>;
+}
+
+export type AFP = AllFeatureProps;
+export type PAFP = Partial<AFP>;
+
+/**
+ * Context passed to the feature constructor
+ */
+export interface FeatureSpawnContext extends SpawnContext {
+    key: string;
+    optIn: any;
+    injection: any;
+    featuresRegistry: any;
+    shared?: any;
+}
+
+export interface TimeTickerElementEndUserProps<T = any> extends FaceUpProps {
+    /**
+     * Duration in milliseconds between ticks
+     */
+    duration: number;
+
+    items: T[];
+
+    name: string;
+
+}
+
+export interface TimeTickerElementAllProps<T = any> extends TimeTickerElementEndUserProps{
+    item: T;
+
+    idx: number;
+
+    timeTicker: EventTarget;
+
+    
+}
+
+export type T = TimeTickerElementAllProps;

package/inferencer/types/truth-sourcer/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Context passed to the TruthSourcer feature constructor
+ */
+export interface FeatureSpawnContext {
+    key: string;
+    optIn: any;
+    injection: any;
+    featuresRegistry: any;
+    shared?: any;
+}
+
+/**
+ * Properties that the TruthSourcer feature manages
+ */
+export interface TruthSourcerProps {
+    /**
+     * The EventTarget that the host element uses to propagate property change events.
+     * TruthSourcer listens for events matching attribute names to sync property -> attribute.
+     */
+    hostPropagator: EventTarget | null;
+}
+
+/**
+ * Internal state
+ */
+export interface AllProps extends TruthSourcerProps {
+    /**
+     * WeakRef to the host custom element
+     */
+    hostRef: WeakRef<HTMLElement> | null;
+
+    /**
+     * The list of observed attribute names (from static observedAttributes)
+     */
+    observedAttributes: string[];
+
+    /**
+     * AbortController for cleaning up event listeners
+     */
+    abortController: AbortController | null;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AP>;

package/inferencer/upSearch.js

@@ -0,0 +1,27 @@
+export async function upSearch(element, id) {
+    if (id) {
+        const target = element.getRootNode().getElementById(id);
+        if (!target)
+            throw 404;
+        return await waitForIt(target);
+    }
+    const itemscope = element.closest('[itemscope]');
+    if (!itemscope) {
+        const host = element.getRootNode().host;
+        if (!host)
+            throw 404;
+        return await waitForIt(host);
+    }
+    if (element.getAttribute('itemscope')) {
+        //has actual value, need to work with itemscope manager
+        throw 'NI';
+    }
+    return waitForIt(itemscope);
+}
+async function waitForIt(element) {
+    const { localName } = element;
+    if (localName.includes('-')) {
+        await (element.customElementRegistry || customElements).whenDefined(localName);
+    }
+    return element;
+}

package/inferencer/upSearch.ts

@@ -0,0 +1,26 @@
+export async function upSearch(element: Element, id?: string){
+    if(id){
+        const target = (element.getRootNode() as DocumentFragment).getElementById(id);
+        if(!target) throw 404;
+        return await waitForIt(target);
+    }
+    const itemscope = element.closest('[itemscope]');
+    if(!itemscope) {
+        const host = (element.getRootNode() as ShadowRoot).host;
+        if(!host) throw 404;
+        return await waitForIt(host);
+    }
+    if(element.getAttribute('itemscope')){
+        //has actual value, need to work with itemscope manager
+        throw 'NI';
+    }
+    return waitForIt(itemscope);
+}
+
+async function waitForIt(element: Element){
+    const {localName} = element;
+    if(localName.includes('-')){
+        await (element.customElementRegistry || customElements).whenDefined(localName);
+    }
+    return element;
+}

package/inferencer/withScopePerimeter.js

@@ -0,0 +1,27 @@
+/**
+ * Check if an element is outside (not inside) any ancestor matching a selector.
+ * This implements "donut hole" scoping — useful for ensuring itemprop queries
+ * don't reach into nested itemscopes.
+ *
+ * @param rootNode - The root node to stop traversal at (not checked against selector)
+ * @param matchCandidate - The element to check
+ * @param outside - CSS selector for excluding ancestors (e.g., '[itemscope]')
+ * @returns true if element is outside all matching ancestors, false otherwise
+ *
+ * @example
+ * // Find itemprop elements that aren't inside a nested itemscope:
+ * const candidates = container.querySelectorAll('[itemprop="name"]');
+ * const scoped = Array.from(candidates).filter(el =>
+ *     withScopePerimeter(container, el, '[itemscope]')
+ * );
+ */
+export function withScopePerimeter(rootNode, matchCandidate, outside) {
+    let current = matchCandidate.parentElement;
+    while (current && current !== rootNode) {
+        if (current.matches(outside)) {
+            return false; // Found an excluding ancestor
+        }
+        current = current.parentElement;
+    }
+    return true; // No excluding ancestors found
+}

package/inferencer/withScopePerimeter.ts

@@ -0,0 +1,33 @@
+/**
+ * Check if an element is outside (not inside) any ancestor matching a selector.
+ * This implements "donut hole" scoping — useful for ensuring itemprop queries
+ * don't reach into nested itemscopes.
+ * 
+ * @param rootNode - The root node to stop traversal at (not checked against selector)
+ * @param matchCandidate - The element to check
+ * @param outside - CSS selector for excluding ancestors (e.g., '[itemscope]')
+ * @returns true if element is outside all matching ancestors, false otherwise
+ * 
+ * @example
+ * // Find itemprop elements that aren't inside a nested itemscope:
+ * const candidates = container.querySelectorAll('[itemprop="name"]');
+ * const scoped = Array.from(candidates).filter(el => 
+ *     withScopePerimeter(container, el, '[itemscope]')
+ * );
+ */
+export function withScopePerimeter(
+    rootNode: Node,
+    matchCandidate: Element,
+    outside: string
+): boolean {
+    let current = matchCandidate.parentElement;
+    
+    while (current && current !== rootNode) {
+        if (current.matches(outside)) {
+            return false;  // Found an excluding ancestor
+        }
+        current = current.parentElement;
+    }
+    
+    return true;  // No excluding ancestors found
+}

package/inferredAssignments.js

@@ -0,0 +1,38 @@
+/**
+ * inferredAssignments.ts — Handles inferred property assignment based on DOM structure.
+ *
+ * Dynamically imported by assignFrom when `inferredAssignments` option is present.
+ * Uses the inferencer submodule to determine the correct property for each element.
+ */
+import { Infer } from './inferencer/inferencer.js';
+/**
+ * Process inferred assignments for a target element.
+ *
+ * @param target - The DOM element to search within
+ * @param from - The source object containing values to distribute
+ * @param config - The inferredAssignments configuration
+ */
+export async function processInferredAssignments(target, from, config) {
+    if (!(target instanceof Element))
+        return;
+    if (!from || typeof from !== 'object')
+        return;
+    const { byItemprop } = config;
+    if (byItemprop) {
+        const keys = byItemprop === true
+            ? Object.keys(from)
+            : byItemprop;
+        const infer = new Infer(target);
+        for (const key of keys) {
+            if (!(key in from))
+                continue;
+            const value = from[key];
+            // Use inferencer's ['|'] method — scoped by itemscope boundary
+            const matches = infer['|'](key);
+            for (const match of matches) {
+                // Infer sets the right property (textContent, value, checked, dateTime, ish)
+                match.value = value;
+            }
+        }
+    }
+}

package/inferredAssignments.ts

@@ -0,0 +1,65 @@
+/**
+ * inferredAssignments.ts — Handles inferred property assignment based on DOM structure.
+ * 
+ * Dynamically imported by assignFrom when `inferredAssignments` option is present.
+ * Uses the inferencer submodule to determine the correct property for each element.
+ */
+
+import { Infer } from './inferencer/inferencer.js';
+
+/**
+ * Configuration for inferred assignments.
+ */
+export interface InferredAssignmentsConfig {
+    /**
+     * Array of property keys to distribute by itemprop attribute.
+     * For each key, finds [itemprop="${key}"] elements within scope (respecting
+     * itemscope boundaries) and sets the value using the inferred property.
+     * 
+     * Pass `true` to infer all keys from the `from` source object.
+     */
+    byItemprop?: string[] | true;
+
+    // Phase II:
+    // byName?: string[] | true;
+}
+
+/**
+ * Process inferred assignments for a target element.
+ * 
+ * @param target - The DOM element to search within
+ * @param from - The source object containing values to distribute
+ * @param config - The inferredAssignments configuration
+ */
+export async function processInferredAssignments(
+    target: any,
+    from: any,
+    config: InferredAssignmentsConfig
+): Promise<void> {
+    if (!(target instanceof Element)) return;
+    if (!from || typeof from !== 'object') return;
+
+    const { byItemprop } = config;
+
+    if (byItemprop) {
+        const keys = byItemprop === true
+            ? Object.keys(from)
+            : byItemprop;
+
+        const infer = new Infer(target);
+
+        for (const key of keys) {
+            if (!(key in from)) continue;
+
+            const value = from[key];
+
+            // Use inferencer's ['|'] method — scoped by itemscope boundary
+            const matches: Infer[] = infer['|'](key);
+
+            for (const match of matches) {
+                // Infer sets the right property (textContent, value, checked, dateTime, ish)
+                match.value = value;
+            }
+        }
+    }
+}