mount-observer 0.0.32 → 0.0.33

package/compose.ts

@@ -0,0 +1,118 @@
+import { ILoadEvent, loadEventName } from './ts-refs/mount-observer/types';
+import { MountObserver, inclTemplQry } from './MountObserver.js';
+
+export const childRefsKey = Symbol.for('Wr0WPVh84k+O93miuENdMA');
+export const cloneKey = Symbol.for('LD97VKZYc02CQv23DT/6fQ');
+
+export async function compose(
+    self: MountObserver, 
+    el: HTMLTemplateElement, 
+    level: number
+){
+        
+    const src = el.getAttribute('src');
+    el.removeAttribute('src');
+    const templID = src!.substring(1);
+    const fragment = self.objNde?.deref() as DocumentFragment;
+    if(fragment === undefined) return;
+    const templ = self.findByID(templID, fragment);
+    if(!(templ instanceof HTMLTemplateElement)) throw 404;
+    const clone = templ.content.cloneNode(true) as DocumentFragment;
+    const slots = el.content.querySelectorAll(`[slot]`);
+
+    for(const slot of slots){
+        const name = slot.getAttribute('slot')!;
+        const slotQry = `slot[name="${name}"]`;
+        const targets = Array.from(clone.querySelectorAll(slotQry));
+        const innerTempls = clone.querySelectorAll(inclTemplQry) as NodeListOf<HTMLTemplateElement>;
+        for(const innerTempl of innerTempls){
+            const innerSlots = innerTempl.content.querySelectorAll(slotQry);
+            for(const innerSlot of innerSlots){
+                targets.push(innerSlot);
+            }
+        }
+        for(const target of targets){
+            const slotClone = slot.cloneNode(true) as Element;
+            target.after(slotClone);
+            target.remove();
+        }
+    }
+    await self.composeFragment(clone, level + 1);
+    const shadowRootModeOnLoad = el.getAttribute('shadowRootModeOnLoad') as null | ShadowRootMode;
+    if(shadowRootModeOnLoad === null && level === 0){
+        
+        const slotMap = el.getAttribute('slotmap');
+        let map = slotMap === null ? undefined : JSON.parse(slotMap);
+        const slots = clone.querySelectorAll('[slot]');
+        for(const slot of slots){
+            if(map !== undefined){
+                const slotName = slot.slot;
+                for(const key in map){
+                    if(slot.matches(key)){
+                        const targetAttSymbols = map[key] as string;
+                        for(const sym of targetAttSymbols){
+                            switch(sym){
+                                case '|':
+                                    slot.setAttribute('itemprop', slotName);
+                                    break;
+                                case '$':
+                                    slot.setAttribute('itemscope', '');
+                                    slot.setAttribute('itemprop', slotName);
+                                    break;
+                                case '@':
+                                    slot.setAttribute('name', slotName);
+                                    break;
+                                case '.':
+                                    slot.classList.add(slotName);
+                                    break;
+                                case '%':
+                                    slot.part.add(slotName);
+                                    break;
+                            }
+                        }
+                    }
+                }
+            }
+            slot.removeAttribute('slot');
+        }
+        el.dispatchEvent(new LoadEvent(clone));
+    }
+    if(level === 0){
+        const refs: Array<WeakRef<Element>> = [];
+        for(const child of clone.children){
+            refs.push(new WeakRef(child));
+        }
+        (<any>el)[childRefsKey] = refs;
+    }
+    //if template has itemscope attribute, assume want to do some data binding before instantiating into
+    //DOM fragment.
+    let cloneStashed = false;
+    if(el.hasAttribute('itemscope')){
+        (<any>el)[cloneKey] = clone;
+        cloneStashed = true;
+    }else{
+        if(shadowRootModeOnLoad !== null){
+            const parent = el.parentElement;
+            if(parent === null) throw 404;
+            if(parent.shadowRoot === null) parent.attachShadow({mode: shadowRootModeOnLoad});
+            parent.shadowRoot?.append(clone);
+        }else{
+            el.after(clone);
+        }
+    }
+    if(!cloneStashed){
+        if(level !== 0 || (slots.length === 0 && el.attributes.length === 0)) el.remove();
+    }
+
+}
+
+export class LoadEvent extends Event implements ILoadEvent{
+    static eventName: loadEventName = 'load';
+    constructor(public clone: DocumentFragment){
+        super(LoadEvent.eventName);
+    }
+}
+
+interface HTMLElementEventMap{
+    'load': LoadEvent,
+}

package/getWhereAttrSelector.ts

@@ -0,0 +1,92 @@
+import {AttrParts, RootCnfg, WhereAttr} from './ts-refs/mount-observer/types';
+export async function getWhereAttrSelector(whereAttr: WhereAttr, withoutAttrs: string){
+    const {hasBase, hasBranchIn, hasRootIn} = whereAttr;
+
+    const fullListOfAttrs: Array<string> = [];
+    const partitionedAttrs: Array<AttrParts> = [];
+    if(hasBase !== undefined){
+        const hasRootInGuaranteed: Array<RootCnfg> = hasRootIn || [{
+            start: '',
+            context: 'Both'
+        } as RootCnfg]
+        
+        let prefixLessMatches: Array<{
+            rootToBaseDelimiter: string,
+            base: string,
+            branch?: string,
+            leaf?: string //todo,
+            baseToBranchDelimiter?: string,
+        }> = [];
+        const hasBaseIsString = typeof hasBase === 'string';
+        const baseSelector = hasBaseIsString ? hasBase : hasBase[1];
+        const rootToBaseDelimiter = hasBaseIsString ? '-' : hasBase[0];
+        if(hasBranchIn !== undefined){
+            let baseToBranchDelimiter = '-';
+            let branches: Array<string> | undefined;
+            if(hasBranchIn.length === 2 && Array.isArray(hasBranchIn[1])){
+                baseToBranchDelimiter = hasBranchIn[0];
+                branches = hasBranchIn[1];
+            }else{
+                branches = hasBranchIn as Array<string>;
+            }
+            prefixLessMatches = branches.map(x => ({
+                rootToBaseDelimiter,
+                base: baseSelector,
+                baseToBranchDelimiter: x ? baseToBranchDelimiter : '',
+                branch: x
+            }));
+        }else{
+            prefixLessMatches.push({
+                rootToBaseDelimiter,
+                base: baseSelector,
+            })
+        }
+        for(const rootCnfg of hasRootInGuaranteed){
+            const {start} = rootCnfg;
+            for(const match of prefixLessMatches){
+                const {base, baseToBranchDelimiter, branch, rootToBaseDelimiter} = match;
+                let branchIdx = 0;
+                for(const prefixLessMatch of prefixLessMatches){
+                    const {base, baseToBranchDelimiter, branch} = prefixLessMatch;
+                    const startAndRootToBaseDelimiter = start ? `${start}${rootToBaseDelimiter}` : '';
+                    //TODO:  could probably reduce the size of the code below
+                    if(branch){
+                        //will always have branch?
+                        const name = `${startAndRootToBaseDelimiter}${base}${baseToBranchDelimiter}${branch}`
+                        fullListOfAttrs.push(name);
+                        partitionedAttrs.push({
+                            root: start,
+                            name,
+                            base,
+                            branch,
+                            branchIdx,
+                            rootCnfg
+                        });
+                    }else{
+                        const name = `${startAndRootToBaseDelimiter}${base}`;
+                        fullListOfAttrs.push(name);
+                        partitionedAttrs.push({
+                            root: start,
+                            name,
+                            base,
+                            rootCnfg,
+                            branchIdx
+                        });
+                    }
+                    branchIdx++;
+                }
+                
+            } 
+        }
+    }
+
+
+    const listOfSelectors = fullListOfAttrs.map(s => `${withoutAttrs}[${s}]`);
+    const calculatedSelector = listOfSelectors.join(',');
+    return {
+        fullListOfAttrs,
+        calculatedSelector,
+        partitionedAttrs,
+    };
+        
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mount-observer",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "Observe and act on css matches.",
   "main": "MountObserver.js",
   "module": "MountObserver.js",
@@ -28,7 +28,8 @@
   },
   "files": [
     "*.js",
-    "types.d.ts"
+    "*.ts",
+    "./ts-refs/*"
   ],
   "types": "./ts-refs/mount-observer/types.d.ts",
   "scripts": {

package/playwright.config.ts

@@ -0,0 +1,29 @@
+// playwright.config.ts
+import { PlaywrightTestConfig, devices } from '@playwright/test';
+const config: PlaywrightTestConfig = {
+  webServer: {
+    command: 'npm run serve',
+    url: 'http://localhost:3030/',
+    timeout: 120 * 1000,
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://localhost:3030/',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    //firefox lacks support for import assertions
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+  ],
+};
+export default config;

package/ts-refs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bruce B. Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ts-refs/README.md

@@ -0,0 +1,18 @@
+# ts-refs
+
+The recent typescript [blog post](https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag) found it amusing, it seems, to imply that developers were all quite aware that the buildless typescript Microsoft supports had support for importing modules from type definition files:
+
+> To avoid this, developers typically had to use import(...) types in JSDoc comments.
+
+Where were developers supposed to learn that such an option even existed?  
+
+[No](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html) [idea](https://www.google.com/search?q=jsdoc+import+types+from+type+definition+files&sca_esv=f583aec8b3671997&sxsrf=ADLYWILWHAvQOa24i969M3KTSHnvI4CCtQ%3A1722464335667&source=hp&ei=T7iqZu_wJuTzkPIP3NfOsAw&iflsig=AL9hbdgAAAAAZqrGX5766U3yi_U8VDQynbrnqQTG0duO&ved=0ahUKEwiv1PTWp9KHAxXkOUQIHdyrE8YQ4dUDCBg&uact=5&oq=jsdoc+import+types+from+type+definition+files&gs_lp=Egdnd3Mtd2l6Ii1qc2RvYyBpbXBvcnQgdHlwZXMgZnJvbSB0eXBlIGRlZmluaXRpb24gZmlsZXMyBRAhGKABMgUQIRigATIFECEYoAEyBRAhGKABMgUQIRirAjIFECEYqwJIpwpQAFgAcAB4AJABAJgBeqABeqoBAzAuMbgBA8gBAPgBAvgBAZgCAaAChgGYAwCSBwMwLjGgB5wH&sclient=gws-wiz)
+
+Anyway, my experiments with it are promising, and I'm excited to use this feature, in order to avoid adding to the global warming that requiring compiling my ts files has to be adding to.
+
+But I've found that a sticking point to this solution has to do with [lack of full support for bare import specifiers / import maps](https://github.com/microsoft/TypeScript/issues/43326).  This causes problems when importing types from one package, which imports chains of types from another dependent package.
+
+Having gone this far, I feel compelled to find workarounds until that critical issue is sorted out.
+
+So the solution is this interim library, shared by projects that use this feature, via git's [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+

package/ts-refs/be-enhanced/types.d.ts

@@ -0,0 +1,31 @@
+import { Actions, Compacts, Handlers, Infractions, Positractions, Hitches } from '../trans-render/froop/types';
+export {IEnhancement, BEAllProps} from '../trans-render/be/types';
+
+export type Enhancement = string; //camelCase;
+export type EnhKey = string; //lisp case;
+export type FQN = string;
+
+export interface PropInfo{
+    dry?: boolean;
+    ro?: boolean;
+    def?: any;
+    propName?: string,
+}
+
+export type PropLookup = {[key: string]: PropInfo}
+
+export interface BEConfig<TProps = any, TActions = TProps, ETProps = TProps>{
+    propDefaults?: Partial<{[key in keyof TProps]: TProps[key]}>;
+    propInfo?: Partial<{[key in keyof TProps]: PropInfo}>;
+    actions?: Actions<TProps, TActions>;
+    /**
+     * inferred actions
+     */
+    infractions?: Infractions<TProps>,
+    compacts?: Compacts<TProps, TProps & TActions>;
+    hitch?: Hitches<TProps, TActions>
+    handlers?: Handlers<ETProps, TActions>;
+    positractions?: Positractions<TProps, TActions>;
+    watchedBranches?: Set<number>;
+}
+

package/ts-refs/be-value-added/types.d.ts

@@ -0,0 +1,34 @@
+import { ActionOnEventConfigs } from "trans-render/froop/types";
+import {JSONValue} from 'trans-render/lib/types';
+import {IEnhancement, BEAllProps} from 'trans-render/be/types';
+
+//export type TMicroElement = HTMLLinkElement | HTMLMetaElement | HTMLDataElement | HTMLTimeElement;
+
+export interface BVAEndUserProps extends IEnhancement{
+    beVigilant?: boolean;
+    value?: string | boolean | number | Date | JSONValue;
+}
+
+export interface BVAAllProps extends BVAEndUserProps{
+    attached?: boolean;
+    mutOptions?: MutationObserverInit;
+    valueFromTextContent?: boolean;
+}
+
+// export interface Output{
+//     attr: string,
+//     val: string,
+// }
+
+export type BVAP = Partial<BVAAllProps>
+
+export interface BVAActions{
+    hydrate(self: BVAAllProps): BVAP;
+    parseAttr(self: BVAAllProps): BVAP;
+    onValChange(self: this): void;
+    obs(self: this): void;
+    obsTC(self: this): BVAP;
+    obsAttr(self: this): BVAP;
+}
+
+export type PropTypes = 'href' | 'content' | 'value' | 'dateTime' | 'textContent'

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

@@ -0,0 +1,201 @@
+//import { MountObserver } from "./MountObserver";
+
+export interface JSONSerializableMountInit{
+    readonly on?: CSSMatch,
+    readonly observedAttrsWhenMounted?: (string | ObservedSourceOfTruthAttribute)[],
+    readonly whereAttr?: WhereAttr,  
+    readonly whereElementIntersectsWith?: IntersectionObserverInit,
+    readonly whereMediaMatches?: MediaQuery,
+    readonly import?: ImportString | [ImportString, ImportAssertions] | PipelineProcessor,
+
+}
+
+export interface ObservedSourceOfTruthAttribute<TProps = any>  {
+    name: string,
+    mapsTo?: keyof TProps & string,
+    valIfNull?: any,
+    valIfFalsy?: any,
+    instanceOf?: any,
+    customParser?: (newValue: string | null, oldValue: string | null, instance: Element) => any
+}
+
+export interface MountInit extends JSONSerializableMountInit{
+    
+    readonly withTargetShadowRoot?: ShadowRoot, 
+    readonly whereInstanceOf?: Array<{new(): Element}>,
+    readonly whereSatisfies?: PipelineProcessor<boolean>,
+    readonly do?: MountObserverCallbacks
+    // /**
+    //  * Purpose -- there are scenarios where we may only want to affect changes that occur after the initial 
+    //  * server rendering, so we only want to mount elements that appear 
+    //  */
+    // readonly ignoreInitialMatches?: boolean,
+}
+
+export interface MountObserverCallbacks{
+    readonly mount?: PipelineProcessor,
+    readonly dismount?: PipelineProcessor,
+    readonly disconnect?: PipelineProcessor,
+    readonly reconfirm?: PipelineProcessor,
+    readonly exit?: PipelineProcessor,
+}
+
+export interface RootCnfg{
+    start: string,
+    context: 'BuiltIn' | 'CustomElement' | 'Both'
+}
+
+//export type RootAttrOptions = Array<string | RootCnfg>;
+export type delimiter = string;
+export interface WhereAttr{
+    
+    hasBase?: string | [delimiter, string],
+    hasBranchIn?: Array<string> | [delimiter, Array<string>],
+    hasRootIn?: Array<RootCnfg>,
+    /**
+     * Used by consumers to track the universal meaning of this combination
+     * regardless of how the actual name values may be changed.
+     */
+    metadata?: any,
+}
+type CSSMatch = string;
+type ImportString = string;
+type MediaQuery = string;
+
+export interface AttribMatch{
+    names: string[],
+    //for boolean, support true/false/mixed
+    // type?: 'number' | 'string' | 'date' | 'json-object' | 'boolean',
+    // valConverter?: (s: string) => any,
+    // validator?: (v: any) => boolean;
+}
+
+export interface IMountObserver {
+    // readonly mountInit: MountInit,
+    // readonly mountedRefs:  WeakRef<Element>[],
+    // readonly dismountedRefs: WeakRef<Element>[],
+    observe(within: Node): void;
+    disconnect(within: Node): void;
+    module?: any;
+    mountedElements: WeakSet<Element>;
+    readAttrs(match: Element, branchIndexes?: Set<number>) : AttrChangeInfo[]
+} 
+
+export interface MountContext{
+    stage?: PipelineStage,
+    initializing?: boolean,
+}
+
+type PipelineStage = 'Inspecting' | 'PreImport' | 'PostImport' | 'Import' 
+export type PipelineProcessor<ReturnType = void> = (matchingElement: Element, observer: IMountObserver, ctx: MountContext) => Promise<ReturnType> | ReturnType;
+
+//#region mutation event
+export type mutationEventName = 'mutation-event';
+export interface MutationEvent{
+    mutationRecords: Array<MutationRecord>
+}
+export type mutationEventHandler = (e: MutationEvent) => void;
+
+export interface AddMutationEventListener {
+    addEventListener(eventName: mutationEventName, handler: mutationEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+interface AttrParts{
+    name: string,
+    root?: string,
+    base?: string,
+    branch?: string,
+    branchIdx: number,
+    leaf?: string, //TODO
+    leafIdx?: number, //TODO
+    rootCnfg?: RootCnfg,
+    metadata?: any,
+}
+
+interface AttrChangeInfo{
+    oldValue: string | null,
+    newValue: string | null,
+    isSOfTAttr: boolean,
+    idx?: number,
+    name: string,
+    parts?: AttrParts,
+    mapsTo?: string,
+}
+
+//#region mount event
+export type mountEventName = 'mount';
+export interface IMountEvent{
+    mountedElement: Element,
+}
+export type mountEventHandler = (e: IMountEvent) => void;
+
+export interface AddMountEventListener {
+    addEventListener(eventName: mountEventName, handler: mountEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+//#region dismount event
+export type dismountEventName = 'dismount';
+export interface IDismountEvent {
+    dismountedElement: Element
+}
+
+export type dismountEventHandler = (e: IDismountEvent) => void;
+
+export interface AddDismountEventListener {
+    addEventListener(eventName: dismountEventName, handler: dismountEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+//#region disconnected event
+export type disconnectedEventName = 'disconnect';
+export interface IDisconnectEvent {
+    disconnectedElement: Element
+}
+
+export type disconnectedEventHandler = (e: IDisconnectEvent) => void;
+
+export interface AddDisconnectEventListener {
+    addEventListener(eventName: disconnectedEventName, handler: disconnectedEventHandler, options?: AddEventListenerOptions): void;
+}
+//endregion
+
+//#region attribute change event
+export type attrChangeEventName = 'attrChange';
+export interface IAttrChangeEvent extends IMountEvent {
+    attrChangeInfos: Array<AttrChangeInfo>,
+}
+export type attrChangeEventHandler = (e: IAttrChangeEvent) => void;
+export interface AddAttrChangeEventListener{
+    addEventListener(eventName: attrChangeEventName, handler: attrChangeEventHandler, options?: AddEventListenerOptions): void;
+}
+//#endregion
+
+//#region load event
+export type loadEventName = 'load';
+export interface ILoadEvent {
+    clone: DocumentFragment
+}
+export type loadEventHandler = (e: ILoadEvent) => void;
+export interface AddLoadEventListener{
+    addEventListener(eventName: loadEventName, handler: loadEventHandler, options?: AddEventListenerOptions): void
+}
+//#endregion
+
+//#region MountObserver Script Element
+export interface MOSEAddedProps<TSynConfig=any>{
+    init: JSONSerializableMountInit;
+    observer: IMountObserver;
+    do: MountObserverCallbacks;
+    synConfig: TSynConfig;
+}
+export interface MOSE<TSynConfig=any> 
+    extends HTMLScriptElement, MOSEAddedProps<TSynConfig>{
+
+}
+
+//#endregion
+
+
+