mount-observer 0.1.14 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mount-observer",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",
@@ -48,11 +48,21 @@
     "./upShadowSearch.js": {
       "default": "./upShadowSearch.js",
       "types": "./upShadowSearch.ts"
+    },
+    "./handlers/*": {
+      "default": "./handlers/*"
     }
   },
   "files": [
     "*.js",
-    "*.ts"
+    "*.ts",
+    "handlers/**/*.js",
+    "handlers/**/*.ts",
+    "types/**/*.d.ts",
+    "refid/**/*.js",
+    "refid/**/*.ts",
+    "slotkin/**/*.js",
+    "slotkin/**/*.ts"
   ],
   "types": "./types/mount-observer/types.d.ts",
   "scripts": {

package/types/assign-gingerly/types.d.ts

@@ -0,0 +1,244 @@
+export type EnhKey = string | symbol;
+
+// type NoUnderscore<T extends string> = T extends `_${string}` ? never : T;
+
+// type YesUnderscore = `_${string}`;
+
+// export type StringWithAutocompleteOptions<TOptions> = 
+//     | (string & {})
+//     | TOptions;
+
+// export type StringNotStartWithUnderscoreAutocompleteOptions<TOptions> = 
+//     | (NoUnderscore<string> & {})
+//     | TOptions;
+
+// export type StringStartWithUnderscoreAutocompleteOptions<TOptions> = 
+//     | (YesUnderscore & {})
+//     | TOptions;
+
+//used by mount-observer, not by assign-gingerly
+type DisposeEvent = 
+    | 'disconnect' 
+    | 'dismount'
+    // cannot polyfill
+    | 'exit' // element moved outside customElementRegistry
+    //reference count outside any enhancements goes to zero
+    | 'dispose'
+
+export type Spawner<T = any, Obj = Element> = {
+  new (obj?: Obj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
+  canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
+}
+
+/**
+ * Configuration for enhancing elements with class instances
+ * Defines how to spawn and initialize enhancement classes
+ */
+export interface EnhancementConfig<T = any, Obj = Element> {
+  
+  spawn: Spawner<T, Obj>;
+  
+  //Applicable to passing in the initVals during the spawn lifecycle event
+  withAttrs?: AttrPatterns<T>;
+  
+  //Allow unprefixed attributes for custom elements and SVG when element tag name matches pattern
+  allowUnprefixed?: string | RegExp;
+  
+  //keys of type symbol are used for dependency injection
+  //and are used by assign-gingerly
+  symlinks?: { [key: symbol]: keyof T };
+  //only applicable when spawning from a DOM Element reference
+  enhKey?: EnhKey;
+  lifecycleKeys?: 
+    | true  // Use standard names: "dispose" method, "resolved" property/event
+    | {
+        dispose?: string | symbol,
+        resolved?: string | symbol
+      }
+  //used by mount-observer, not by assign-gingerly
+  //impossible to polyfill, but will always be disposed
+  //when oElement's reference count goes to zero
+  disposeOn?: DisposeEvent | DisposeEvent[]
+    
+}
+
+export type Constructor = new (...args: any[]) => any;
+
+export type pathString = `?.${string}`;
+
+export type CustomElementName = string;
+export type CustomElementConstructorStaticMethodName = string;
+
+export interface AttrConfig<T = any> {
+  /**
+   * Type of the property value (JSON-serializable string format)
+   */
+  instanceOf?: 'Object' | 'String' | 'Number' | 'Boolean' | 'Array' 
+              | typeof Object | typeof String | typeof Number | typeof Boolean | typeof Array;
+
+  
+  /**
+   * Property name on the spawned class instance to map to
+   * Use '.' to map to the root object using assignGingerly
+   * Is optional.
+   * If not specified, we assume it is the key without the underscore first
+   * character, unless the key is _base in which case it assume mapsTo = "."
+   */
+  mapsTo?: 
+    | '.' 
+    | keyof T 
+    | pathString 
+    | `${pathString} +=`
+    | `${pathString} =!`
+    | `${pathString} -=`
+  
+  /**
+   * Parser to transform attribute string value
+   * - Function: Inline parser function (not JSON serializable)
+   * - String: Named parser reference (JSON serializable) - looks up in global parser registry (e.g., 'timestamp', 'csv')
+   * - Tuple: [CustomElementName, StaticMethodName] - looks up static method on custom element constructor (e.g., ['my-widget', 'parseSpecial'])
+   */
+  parser?: 
+    | ((attrValue: string | null) => any) 
+    | string 
+    | [CustomElementName, CustomElementConstructorStaticMethodName]
+  ;
+  
+  /**
+   * Default value to use when attribute is missing
+   * If defined, bypasses parser when attribute is not present
+   * If undefined, property is not added to initVals when attribute is missing
+   */
+  valIfNull?: any;
+  
+  /**
+   * Enable caching of parsed attribute values
+   * - 'shared': Cache and reuse the same parsed object (fast, but enhancements must not mutate)
+   * - 'cloned': Cache and return a structural clone (safer, but slower)
+   * Note: Parsers should be pure functions when using caching
+   */
+  parseCache?: 'shared' | 'cloned';
+  
+  // /**
+  //  * Whether to only read the initial value (true) or continue observing changes (false)
+  //  * Defaults to true (initial read only)
+  //  */
+  // initialOnly?: boolean;
+}
+
+export type AttrPatterns<T = any> = {
+  /**
+   * Base prefix for attribute names
+   */
+  base: string;
+
+  /**
+   * Configuration for the base pattern
+   */
+  _base?: AttrConfig<T>;
+} & {
+  // Provide autocomplete for all properties of T (optional)
+  [K in keyof T]?: string | AttrConfig<T>;
+} & {
+  // Provide autocomplete for underscore-prefixed config keys
+  [K in keyof T as `_${string & K}`]?: AttrConfig<T>;
+} & {
+  // Allow any other string keys for custom patterns
+  [key: string]: string | AttrConfig<T>;
+};
+
+
+export interface SpawnContext<T = any, TMountContext = any> {
+  config: EnhancementConfig<T>;
+  mountCtx?: TMountContext;
+}
+
+/**
+ * @deprecated Use EnhancementConfig instead
+ */
+export type IEnhancementRegistryItem<T = any> = EnhancementConfig<T>;
+
+/**
+ * Interface for the options passed to assignGingerly
+ */
+export interface IAssignGingerlyOptions {
+  registry?: typeof EnhancementRegistry | EnhancementRegistry;
+  bypassChecks?: boolean;
+}
+
+/**
+ * Event dispatched when enhancement configs are registered
+ */
+export declare class EnhancementRegisteredEvent extends Event {
+  static eventName: string;
+  config: EnhancementConfig | EnhancementConfig[];
+  constructor(config: EnhancementConfig | EnhancementConfig[]);
+}
+
+/**
+ * Base registry class for managing enhancement configurations
+ * Extends EventTarget to dispatch events when configs are registered
+ */
+export declare class EnhancementRegistry extends EventTarget {
+  private items;
+  push(items: EnhancementConfig | EnhancementConfig[]): void;
+  getItems(): EnhancementConfig[];
+  findBySymbol(symbol: symbol | string): EnhancementConfig | undefined;
+  findByEnhKey(enhKey: string | symbol): EnhancementConfig | undefined;
+}
+
+/**
+ * Constructor signature for ItemScope Manager classes
+ */
+export type ItemscopeManager<T = any> = {
+  new (element: HTMLElement, initVals?: Partial<T>): T;
+}
+
+/**
+ * Configuration for ItemScope Manager registration
+ */
+export interface ItemscopeManagerConfig<T = any> {
+  /**
+   * Manager class constructor
+   */
+  manager: ItemscopeManager<T>;
+  
+  /**
+   * Optional lifecycle method keys
+   * - dispose: Method name to call when manager is disposed
+   * - resolved: Property/event name indicating manager is ready
+   */
+  lifecycleKeys?: {
+    dispose?: string | symbol;
+    resolved?: string | symbol;
+  };
+}
+
+/**
+ * Registry for ItemScope Manager configurations
+ * Extends EventTarget to support lazy registration via events
+ */
+export declare class ItemscopeRegistry extends EventTarget {
+  define(name: string, config: ItemscopeManagerConfig): void;
+  get(name: string): ItemscopeManagerConfig | undefined;
+  whenDefined(name: string): Promise<void>;
+}
+
+/**
+ * Main assignGingerly function
+ */
+export declare function assignGingerly(
+  target: any,
+  source: Record<string | symbol, any>,
+  options?: IAssignGingerlyOptions
+): any;
+
+export default assignGingerly;
+
+export declare class ElementEnhancementGateway{
+  enh: ElementEnhancement;
+}
+
+export interface ElementEnhancement{
+  dispose(regItem: EnhancementConfig): void;
+}

package/types/be-a-beacon/types.d.ts

@@ -0,0 +1,3 @@
+export interface BeABeaconProps {
+    eventName: string;
+}

package/types/global.d.ts

@@ -0,0 +1,29 @@
+// Type declarations for Map.prototype.getOrInsertComputed and WeakMap.prototype.getOrInsertComputed
+// Feature is now supported in all modern browsers (Chrome 146+, Firefox 134+, Safari 18.2+)
+// See: https://web-platform-dx.github.io/web-features-explorer/features/getorinsert/
+
+interface Map<K, V> {
+  /**
+   * Returns the value associated with the key if it exists, otherwise inserts
+   * the value returned by the insert callback and returns it.
+   * @param key The key to look up
+   * @param insert A callback that returns the value to insert if the key doesn't exist
+   * @returns The existing or newly inserted value
+   */
+  getOrInsertComputed(key: K, insert: () => V): V;
+}
+
+interface WeakMap<K extends object, V> {
+  /**
+   * Returns the value associated with the key if it exists, otherwise inserts
+   * the value returned by the insert callback and returns it.
+   * @param key The key to look up
+   * @param insert A callback that returns the value to insert if the key doesn't exist
+   * @returns The existing or newly inserted value
+   */
+  getOrInsertComputed(key: K, insert: () => V): V;
+}
+
+interface HTMLTemplateElement {
+  remoteContent?: Node;
+}

package/types/id-generation/types.d.ts

@@ -0,0 +1,26 @@
+// Type definitions for id-generation
+
+export interface GenIdsOptions {
+    //startCounter?: number;
+}
+
+export interface ParsedDataId {
+    name: string;
+    setName: boolean;
+    setItemprop: boolean;
+    setClass: boolean;
+    setPart: boolean;
+    setItemscope: boolean;
+}
+
+export interface ScopeInfo {
+    scopeElement: Element;
+    elementsToProcess: Element[];
+}
+
+export interface AttributeReplacement {
+    element: Element;
+    attributeName: string;
+    oldValue: string;
+    newValue: string;
+}

package/types/mount-observer/types.d.ts

@@ -0,0 +1,330 @@
+// Core types for MountObserver v2 - Polyfill Supported Scenario I
+
+export type Constructor = new (...args: any[]) => any;
+
+export type EventConstructor = {new(...args: any[]): Event};
+
+export interface EventConfig {
+    event: string | EventConstructor;
+    args?: any | any[];
+    eventProps?: Record<string, any>;
+    oncePerMountedElement?: boolean;
+}
+
+export type DismountReason = 
+    | 'media-query-failed'
+    | 'root-size-failed'
+    | 'intersection-failed'
+    | 'connection-failed'
+    | 'with-matching-failed';
+
+export interface ConnectionCondition {
+    effectiveTypeIn?: string[];
+    downlinkMin?: number;
+    downlinkMax?: number;
+    rttMax?: number;
+}
+
+/**
+ * Configuration object for MountObserver that defines what elements to observe and how to handle them.
+ * All `where*` properties form an AND condition - elements must satisfy ALL specified conditions to mount.
+ * 
+ * @template TKeys - String literal type for sub-observer keys when using the `with` property
+ */
+export interface MountConfig<TKeys extends string = string> {
+    /**
+     * CSS selector string to match elements.
+     * Only elements matching this selector will be considered for mounting.
+     * @example 'button.fancy' or 'div > p.highlight'
+     */
+    matching?: string;
+    
+    /**
+     * Custom element tag name(s) that must be defined before mounting occurs.
+     * Waits for customElements.whenDefined() to resolve for each specified tag.
+     * Uses the customElementRegistry of the observed root node.
+     * This check happens first, before any other where* conditions.
+     * @example 'my-button' or ['my-button', 'my-input']
+     */
+    whenDefined?: string | string[];
+    
+    /**
+     * Constructor or array of constructors to filter elements by instance type.
+     * Elements must be instances of at least one of the specified constructors (OR logic for arrays).
+     * @example HTMLButtonElement or [HTMLInputElement, HTMLTextAreaElement]
+     */
+    whereInstanceOf?: Constructor | Constructor[];
+    
+    /**
+     * Media query string or MediaQueryList for conditional mounting based on viewport/media conditions.
+     * Elements only mount when the media query matches.
+     * @example '(min-width: 768px)' or '(prefers-color-scheme: dark)'
+     */
+    withMediaMatching?: string | MediaQueryList;
+    
+    /**
+     * CSS selector defining a "donut hole" scope perimeter.
+     * Excludes elements that are descendants of elements matching this selector.
+     * Useful for preventing observation of nested scopes.
+     * @example '.no-observe' to exclude elements inside .no-observe containers
+     */
+    withScopePerimeter?: string;
+    
+    /**
+     * Container query string for conditional mounting based on observed root element size.
+     * Elements only mount when the root node matches this size condition.
+     * @example '(min-width: 500px)' to only mount when root is at least 500px wide
+     */
+    whereObservedRootSizeMatches?: string;
+    
+    /**
+     * IntersectionObserver configuration for conditional mounting based on element visibility.
+     * Elements only mount when they intersect with the viewport according to these options.
+     * @example { rootMargin: '50px', threshold: 0.5 }
+     */
+    whereElementIntersectsWith?: IntersectionObserverInit;
+    
+    /**
+     * Network connection conditions for conditional mounting.
+     * Elements only mount when network conditions match the specified criteria.
+     * Useful for adaptive loading based on connection quality.
+     */
+    whereConnectionHas?: ConnectionCondition;
+    
+    /**
+     * When true, inverts the default registry matching behavior.
+     * Default (false): Only mount elements with the SAME customElementRegistry as the root node.
+     * When true: Only mount elements with a DIFFERENT customElementRegistry than the root node.
+     * Useful for cross-registry observation scenarios.
+     * @example true to observe elements from other shadow DOM scopes
+     */
+    whereDifferentCustomElementRegistry?: boolean;
+    
+    /**
+     * Regular expression or string pattern to match against element's localName.
+     * Only elements whose localName matches this pattern will mount.
+     * String values are converted to RegExp.
+     * @example /^my-/ to match elements starting with 'my-'
+     * @example 'button|input' to match button or input elements
+     */
+    whereLocalNameMatches?: string | RegExp;
+    
+    /**
+     * Module(s) to import before mounting elements.
+     * Can be a URL string, ImportSpec object, or array of either.
+     * Modules are loaded based on loadingEagerness setting.
+     * @example './my-component.js' or [{ url: './styles.css', type: 'css' }]
+     */
+    import?: string | ImportSpec | Array<string | ImportSpec>;
+    
+    /**
+     * Handler(s) to execute when elements mount.
+     * Can be:
+     * - String: Name of a registered handler (e.g., 'builtIns.defineCustomElement')
+     * - Function: Inline callback function
+     * - Array: Multiple handlers to execute in order
+     * @example 'builtIns.defineCustomElement' or (el, ctx) => { el.classList.add('mounted') }
+     */
+    do?: string | DoCallback | (string | DoCallback)[];
+    
+    /**
+     * Custom JavaScript check that runs after all declarative where* conditions pass.
+     * This is the final gate before mounting occurs.
+     * 
+     * If shouldMount returns false, the element is not mounted (no do callback, no mount event).
+     * If shouldMount throws an error, it is treated as returning false and the error is logged.
+     * 
+     * @example (el) => currentUser.hasRole('admin')
+     * @example (el) => el.dataset.apiKey && el.dataset.apiEndpoint
+     */
+    shouldMount?: ShouldMountCallback;
+    
+    /**
+     * Controls when imports are loaded.
+     * - 'eager': Load imports immediately when MountObserver is created
+     * - 'lazy': Load imports only when first matching element is found (default)
+     */
+    loadingEagerness?: 'eager' | 'lazy';
+    
+    /**
+     * Properties to assign to elements when they mount.
+     * Uses assign-gingerly for safe property assignment.
+     * @example { disabled: false, tabIndex: 0 }
+     */
+    assignOnMount?: Record<string, any>;
+    
+    /**
+     * Properties to assign to elements when they dismount.
+     * Uses assign-gingerly for safe property assignment.
+     * @example { disabled: true }
+     */
+    assignOnDismount?: Record<string, any>;
+    
+    /**
+     * Properties to tentatively assign on mount with automatic reversal on dismount.
+     * Original values are saved and restored when element dismounts.
+     * @example { hidden: false } - will restore original hidden value on dismount
+     */
+    stageOnMount?: Record<string, any>;
+    
+    /**
+     * When true, enables detailed event dispatching for debugging and monitoring.
+     * Provides granular lifecycle events for observation.
+     */
+    getPlayByPlay?: boolean;
+    
+    /**
+     * Event(s) to emit from mounted elements.
+     * Can be a single EventConfig or array of EventConfigs.
+     * Allows elements to dispatch custom events when mounted.
+     * @example { event: 'ready', args: { detail: 'mounted' } }
+     */
+    mountedElemEmits?: EventConfig | EventConfig[];
+    
+    /**
+     * External module(s) to import MountConfig from.
+     * Allows separating JSON-serializable config from non-serializable handlers.
+     * Loaded configs are merged left-to-right, with inline config taking final precedence.
+     * @example './config.js' or ['./base-config.js', './override-config.js']
+     */
+    configFrom?: string | string[];
+    
+    /**
+     * Custom data to pass to handler classes or functions.
+     * Allows handlers to receive additional context-specific information.
+     * Not used by MountObserver itself, but available in MountContext.
+     */
+    customData?: unknown;
+    
+    /**
+     * Sub-observer configurations for hierarchical composition.
+     * Each key-value pair defines a sub-observer that will observe the same root node as the parent.
+     * Sub-observers are created when the parent's observe() method is called and automatically
+     * disconnected when the parent disconnects.
+     * 
+     * Sub-observers operate independently with their own configurations and do not inherit
+     * properties from the parent observer. Each sub-observer can have its own `with` property
+     * for unlimited nesting depth.
+     * 
+     * @example
+     * ```typescript
+     * const observer = new MountObserver({
+     *   matching: '.parent',
+     *   with: {
+     *     registry: { matching: 'my-element', do: 'builtIns.defineCustomElement' },
+     *     styles: { import: './styles.css' }
+     *   }
+     * });
+     * ```
+     */
+    with?: {[K in TKeys]: MountConfig};
+}
+
+
+
+export interface ImportSpec {
+    url: string;
+    type?: 'js' | 'css' | 'json' | 'html';
+}
+
+/**
+ * Context object passed to mount handlers containing information about the mounted element and observer state.
+ * 
+ * @template TKeys - String literal type for sub-observer keys when using the `with` property
+ */
+export interface MountContext<TKeys extends string = string> {
+    modules: any[];
+    observer: IMountObserver;
+    rootNode: Node;
+    
+    /**
+     * The configuration object for this observer.
+     * Contains all the settings that define what elements to observe and how to handle them.
+     */
+    mountConfig: MountConfig<TKeys>;
+    
+    /**
+     * Map of sub-observers created from the `with` property in mountConfig.
+     * Only present when the parent observer has sub-observers defined.
+     * Keys match the keys from the `with` property, providing type-safe access to sub-observers.
+     * 
+     * @example
+     * ```typescript
+     * do: (el, ctx) => {
+     *   // Access sub-observers with type safety
+     *   const registryObserver = ctx.withObservers?.registry;
+     *   if (registryObserver) {
+     *     console.log('Registry observer:', registryObserver);
+     *   }
+     * }
+     * ```
+     */
+    withObservers?: {[K in TKeys]: IMountObserver};
+}
+
+
+
+export type DoCallback<TKeys extends string = string> = (mountedElement: Element, context: MountContext<TKeys>) => void;
+
+/**
+ * Callback function that performs a final check before mounting an element.
+ * Called after all declarative where* conditions have passed.
+ * 
+ * @param mountedElement - The element being considered for mounting
+ * @param context - The mount context containing modules, observer, config, etc.
+ * @returns true to allow mounting, false to prevent it
+ */
+export type ShouldMountCallback<TKeys extends string = string> = (mountedElement: Element, context: MountContext<TKeys>) => boolean;
+
+// export interface DoCallbacks {
+//     mount?: (mountedElement: Element, context: MountContext) => void;
+//     dismount?: (mountedElement: Element, context: MountContext) => void;
+//     disconnect?: (mountedElement: Element, context: MountContext) => void;
+//     reconnect?: (mountedElement: Element, context: MountContext) => void;
+// }
+
+export type MountScope = 
+    | 'registry'     // Observe all scopes with matching registry (new default)
+    | 'registryRoot' // getRegistryRoot - finds highest node with matching customElementRegistry
+    | 'self'         // this element
+    | 'root'         // getRootNode()
+    | 'shadow'       // shadowRoot (throws if none)
+    | Element;       // custom element to observe
+
+export interface MountObserverOptions {
+    disconnectedSignal?: AbortSignal;
+    scope?: MountScope;
+}
+
+export interface WeakDual<T extends Object>{
+    weakSet: WeakSet<T>,
+    setWeak: Set<WeakRef<T>>
+}
+
+export interface WeakMapDual<T extends Object, R extends Object>{
+    weakMap: WeakMap<T, R>,
+    setWeak: Set<WeakRef<T>> 
+}
+
+export interface IMountObserver extends EventTarget {
+    observe(observedNode: Node): Promise<void>;
+    disconnect(): void;
+    disconnectedSignal: AbortSignal;
+    assignGingerly(config: Record<string, any> | undefined): Promise<void>;
+    getNotifier(element: Element): EventTarget;
+}
+
+export interface IMountEvent extends Event {
+    mountedElement: Element;
+    modules: any[];
+    mountConfig: MountConfig;
+    mountContext: MountContext;
+}
+
+export interface IDismountEvent extends Event {
+    mountedElement: Element;
+    reason: DismountReason;
+    mountConfig: MountConfig;
+}
+
+