element-vir 0.0.5 → 0.2.0

package/README.md

@@ -28,6 +28,8 @@ npm i element-vir
 
 Most usage of this package is done through the [`defineFunctionalElement` function](https://github.com/electrovir/element-vir/blob/main/src/functional-element/define-functional-element.ts#L25-L30). See the [`FunctionalElementInit` type](https://github.com/electrovir/element-vir/blob/main/src/functional-element/functional-element-init.ts#L7-L20) for that function's inputs. These inputs are also described below with examples.
 
+All of [`lit`](https://lit.dev)'s syntax and functionality is also available for use.
+
 ## Simple element definition
 
 Use `defineFunctionalElement` to define your element. This is apparent if you inspect the types but it must be given an object with at least `tagName` and `renderCallback` properties. This is a bare-minimum example custom element:
@@ -206,35 +208,57 @@ export const MyAppWithEventsElement = defineFunctionalElement({
 });
 ```
 
-## Lifecycle callbacks
+## Directives
+
+Some custom [`lit` directives](https://lit.dev/docs/templates/custom-directives/) are also contained within this package.
+
+### onDomCreate
+
+This directive should be used instead of trying to use `querySelector` directly on the custom element.
 
-Use `connectedCallback` and `disconnectedCallback` to access [`lit-element`'s lifecycle callbacks](https://lit.dev/docs/components/lifecycle/#connectedcallback):
+This triggers only once when the element it's contained within is created in the DOM. If it's containing element changes, the callback will be triggered again.
 
-<!-- src/readme-examples/my-simple-with-lifecycle-callbacks.element.ts -->
+<!-- src/readme-examples/my-simple-with-on-dom-created.element.ts -->
 
 ```typescript
-import {defineFunctionalElement, html} from 'element-vir';
+import {defineFunctionalElement, html, onDomCreated} from 'element-vir';
 
-export const MySimpleWithLifecycleCallbacksElement = defineFunctionalElement({
-    tagName: 'my-simple-element-with-lifecycle-callbacks',
-    props: {
-        windowWidth: window.innerWidth,
-        resizeListener: undefined as undefined | (() => void),
-    },
-    connectedCallback: ({props}) => {
-        props.resizeListener = () => {
-            props.windowWidth = window.innerWidth;
-        };
-        window.addEventListener('resize', props.resizeListener);
-    },
-    disconnectedCallback({props}) {
-        if (props.resizeListener) {
-            window.removeEventListener('resize', props.resizeListener);
-        }
-        props.resizeListener = undefined;
-    },
-    renderCallback: ({props}) => html`
-        <span>This window is ${props.windowWidth} wide!</span>
+export const MySimpleWithOnDomCreatedElement = defineFunctionalElement({
+    tagName: 'my-simple-with-on-dom-created-element',
+    renderCallback: () => html`
+        <span
+            ${onDomCreated((element) => {
+                // logs a span element
+                console.log(element);
+            })}
+        >
+            Hello there!
+        </span>
+    `,
+});
+```
+
+### onResize
+
+This directive fulfills a common use case of triggering callbacks when something resizes. Instead of just tracking the _globally_ resizing window though, this allows you to track resizes of an individual element. The callback here is given a portion of the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) (since not all properties are supported well in browsers).
+
+<!-- src/readme-examples/my-simple-with-on-resize.element.ts -->
+
+```typescript
+import {defineFunctionalElement, html, onResize} from 'element-vir';
+
+export const MySimpleWithOnResizeElement = defineFunctionalElement({
+    tagName: 'my-simple-with-on-dom-created-element',
+    renderCallback: () => html`
+        <span
+            ${onResize((entry) => {
+                // this will track resizing of this span
+                // the entry parameter contains target and contentRect properties
+                console.log(entry);
+            })}
+        >
+            Hello there!
+        </span>
     `,
 });
 ```

package/dist/functional-element/define-functional-element.d.ts

@@ -1,5 +1,4 @@
 import { EventsInitMap } from './element-events';
 import { PropertyInitMapBase } from './element-properties';
-import { FunctionalElementConstructor } from './functional-element';
-import { FunctionalElementInit } from './functional-element-init';
+import { FunctionalElementConstructor, FunctionalElementInit } from './functional-element';
 export declare function defineFunctionalElement<EventsInitGeneric extends EventsInitMap = never, PropertyInitGeneric extends PropertyInitMapBase = never>(functionalElementInit: FunctionalElementInit<PropertyInitGeneric, EventsInitGeneric>): FunctionalElementConstructor<PropertyInitGeneric, EventsInitGeneric>;

package/dist/functional-element/define-functional-element.js

@@ -24,29 +24,6 @@ export function defineFunctionalElement(functionalElementInit) {
             render() {
                 return functionalElementInit.renderCallback(this.createRenderParams());
             }
-            connectedCallback() {
-                var _a;
-                super.connectedCallback();
-                (_a = functionalElementInit.connectedCallback) === null || _a === void 0 ? void 0 : _a.call(functionalElementInit, {
-                    element: this,
-                    ...this.createRenderParams(),
-                });
-            }
-            disconnectedCallback() {
-                var _a;
-                super.disconnectedCallback();
-                (_a = functionalElementInit.disconnectedCallback) === null || _a === void 0 ? void 0 : _a.call(functionalElementInit, {
-                    element: this,
-                    ...this.createRenderParams(),
-                });
-            }
-            firstUpdated() {
-                var _a;
-                (_a = functionalElementInit.firstUpdated) === null || _a === void 0 ? void 0 : _a.call(functionalElementInit, {
-                    element: this,
-                    ...this.createRenderParams(),
-                });
-            }
         },
         _a.tagName = functionalElementInit.tagName,
         _a.styles = functionalElementInit.styles || css ``,

package/dist/functional-element/directives/assign-with-clean-up.directive.d.ts

@@ -0,0 +1,17 @@
+import { PartInfo } from 'lit/directive.js';
+import { PropertyInitMapBase, StaticElementPropertyDescriptor } from '../element-properties';
+import { FunctionalElementInstance } from '../functional-element';
+/**
+ * The directive generics (in listenDirective) are not strong enough to maintain their values. Thus,
+ * the directive call is wrapped in this function.
+ */
+export declare function assignWithCleanup<PropName extends string, PropValue>(propertyDescriptor: StaticElementPropertyDescriptor<PropName, PropValue>, value: typeof propertyDescriptor['initValue'], cleanupCallback: CleanupCallback<typeof propertyDescriptor['initValue']>): import("lit-html/directive").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        readonly element: FunctionalElementInstance<PropertyInitMapBase>;
+        lastValue: unknown;
+        render(propName: string, value: unknown, cleanupCallback: CleanupCallback<any>): symbol;
+        readonly _$isConnected: boolean;
+        update(_part: import("lit-html").Part, props: unknown[]): unknown;
+    };
+}>;
+export declare type CleanupCallback<T> = (oldValue: T) => void;

package/dist/functional-element/directives/assign-with-clean-up.directive.js

@@ -0,0 +1,28 @@
+import { noChange } from 'lit';
+import { directive, Directive } from 'lit/directive.js';
+import { extractFunctionalElement } from './directive-util';
+/**
+ * The directive generics (in listenDirective) are not strong enough to maintain their values. Thus,
+ * the directive call is wrapped in this function.
+ */
+export function assignWithCleanup(propertyDescriptor, value, cleanupCallback) {
+    return assignWithCleanupDirective(propertyDescriptor.propName, value, cleanupCallback);
+}
+const assignWithCleanupDirective = directive(class extends Directive {
+    constructor(partInfo) {
+        super(partInfo);
+        this.element = extractFunctionalElement(partInfo, 'assign');
+    }
+    render(propName, value, cleanupCallback) {
+        if (!(propName in this.element.instanceProps)) {
+            throw new Error(`${this.element.tagName} element has no property of name "${propName}"`);
+        }
+        // reference equality check!
+        if (this.lastValue !== value) {
+            cleanupCallback(this.lastValue);
+        }
+        this.element.instanceProps[propName] = value;
+        this.lastValue = value;
+        return noChange;
+    }
+});

package/dist/functional-element/directives/{property-assign.directive.d.ts → assign.directive.d.ts}

@@ -1,23 +1,15 @@
 import { PartInfo } from 'lit/directive.js';
-import { ElementEvent } from '../element-events';
 import { PropertyInitMapBase, StaticElementPropertyDescriptor } from '../element-properties';
 import { FunctionalElementInstance } from '../functional-element';
 /**
- * The directive generics (in listenDirective) are not strong enough to maintain their values. Thus,
+ * The directive generics (in assignDirective) are not strong enough to maintain their values. Thus,
  * the directive call is wrapped in this function.
  */
 export declare function assign<PropName extends string, PropValue>(propertyDescriptor: StaticElementPropertyDescriptor<PropName, PropValue>, value: typeof propertyDescriptor['initValue']): import("lit-html/directive").DirectiveResult<{
     new (partInfo: PartInfo): {
         readonly element: FunctionalElementInstance<PropertyInitMapBase>;
-        lastListenerMetaData: ListenerMetaData<any> | undefined;
         render(propName: string, value: unknown): symbol;
         readonly _$isConnected: boolean;
         update(_part: import("lit-html").Part, props: unknown[]): unknown;
     };
 }>;
-declare type ListenerMetaData<EventDetail> = {
-    eventType: string;
-    callback: (event: ElementEvent<string, EventDetail>) => void;
-    listener: (event: any) => void;
-};
-export {};

package/dist/functional-element/directives/{property-assign.directive.js → assign.directive.js}

@@ -2,7 +2,7 @@ import { noChange } from 'lit';
 import { directive, Directive } from 'lit/directive.js';
 import { extractFunctionalElement } from './directive-util';
 /**
- * The directive generics (in listenDirective) are not strong enough to maintain their values. Thus,
+ * The directive generics (in assignDirective) are not strong enough to maintain their values. Thus,
  * the directive call is wrapped in this function.
  */
 export function assign(propertyDescriptor, value) {
@@ -11,7 +11,7 @@ export function assign(propertyDescriptor, value) {
 const assignDirective = directive(class extends Directive {
     constructor(partInfo) {
         super(partInfo);
-        this.element = extractFunctionalElement(partInfo);
+        this.element = extractFunctionalElement(partInfo, 'assign');
     }
     render(propName, value) {
         if (!(propName in this.element.instanceProps)) {

package/dist/functional-element/directives/directive-util.d.ts

@@ -1,4 +1,14 @@
-import { PartInfo } from 'lit/directive.js';
+import { ElementPartInfo, PartInfo } from 'lit/directive.js';
 import { PropertyInitMapBase } from '../element-properties';
 import { FunctionalElementInstance } from '../functional-element';
-export declare function extractFunctionalElement<PropertyInitGeneric extends PropertyInitMapBase>(partInfo: PartInfo): FunctionalElementInstance<PropertyInitGeneric>;
+/** For some reason these aren't defined in lit's types already. */
+export declare type ExtraPartInfoProperties = {
+    element: Element;
+    options: {
+        host: Element;
+        renderBefore: Element;
+        isConnected: boolean;
+    };
+};
+export declare function extractFunctionalElement<PropertyInitGeneric extends PropertyInitMapBase>(partInfo: PartInfo, directiveName: string): FunctionalElementInstance<PropertyInitGeneric>;
+export declare function assertsIsElementPartInfo(partInfo: PartInfo, directiveName: string): asserts partInfo is ElementPartInfo & ExtraPartInfoProperties;

package/dist/functional-element/directives/directive-util.js

@@ -1,12 +1,18 @@
 import { PartType } from 'lit/directive.js';
 import { FunctionalElementBaseClass } from '../functional-element';
-export function extractFunctionalElement(partInfo) {
-    if (partInfo.type !== PartType.ELEMENT) {
-        throw new Error(`assign directive can only be attached directly to an element.`);
-    }
+export function extractFunctionalElement(partInfo, directiveName) {
+    assertsIsElementPartInfo(partInfo, directiveName);
     const element = partInfo.element;
     if (!(element instanceof FunctionalElementBaseClass)) {
-        throw new Error(`assign directive only works when attached to functional elements`);
+        throw new Error(`${directiveName} directive only works when attached to functional elements`);
     }
     return element;
 }
+export function assertsIsElementPartInfo(partInfo, directiveName) {
+    if (partInfo.type !== PartType.ELEMENT) {
+        throw new Error(`${directiveName} directive can only be attached directly to an element.`);
+    }
+    if (!partInfo.element) {
+        throw new Error(`${directiveName} directive found no element`);
+    }
+}

package/dist/functional-element/directives/{event-listen.directive.js → listen.directive.js}

@@ -11,7 +11,7 @@ export function listen(eventType, listener) {
 const listenDirective = directive(class extends Directive {
     constructor(partInfo) {
         super(partInfo);
-        this.element = extractFunctionalElement(partInfo);
+        this.element = extractFunctionalElement(partInfo, 'listen');
     }
     resetListener(listenerMetaData) {
         if (this.lastListenerMetaData) {

package/dist/functional-element/directives/on-dom-created.directive.d.ts

@@ -0,0 +1,11 @@
+import { PartInfo } from 'lit/directive.js';
+export declare type OnDomCreatedCallback = (element: Element) => void;
+/** Only fires once, when the element has been created. */
+export declare const onDomCreated: (callback: OnDomCreatedCallback) => import("lit-html/directive").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        element: Element | undefined;
+        update(partInfo: PartInfo, [callback]: [OnDomCreatedCallback]): undefined;
+        render(callback: OnDomCreatedCallback): undefined;
+        readonly _$isConnected: boolean;
+    };
+}>;

package/dist/functional-element/directives/on-dom-created.directive.js

@@ -0,0 +1,22 @@
+import { directive, Directive } from 'lit/directive.js';
+import { assertsIsElementPartInfo } from './directive-util';
+const directiveName = 'onDomCreated';
+/** Only fires once, when the element has been created. */
+export const onDomCreated = directive(class extends Directive {
+    constructor(partInfo) {
+        super(partInfo);
+        assertsIsElementPartInfo(partInfo, directiveName);
+    }
+    update(partInfo, [callback]) {
+        assertsIsElementPartInfo(partInfo, directiveName);
+        const newElement = partInfo.element;
+        if (newElement !== this.element) {
+            callback(newElement);
+            this.element = newElement;
+        }
+        return this.render(callback);
+    }
+    render(callback) {
+        return undefined;
+    }
+});

package/dist/functional-element/directives/on-resize.directive.d.ts

@@ -0,0 +1,15 @@
+import { PartInfo } from 'lit/directive.js';
+export declare type OnResizeCallback = (
+/** Only these two properties are supported in all major modern browsers */
+entry: Readonly<Pick<ResizeObserverEntry, 'target' | 'contentRect'>>) => void;
+export declare const onResize: (callback: OnResizeCallback) => import("lit-html/directive").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        element: Element | undefined;
+        readonly resizeObserver: ResizeObserver;
+        callback: OnResizeCallback | undefined;
+        fireCallback(entries: ResizeObserverEntry[]): void;
+        update(partInfo: PartInfo, [callback]: [OnResizeCallback]): undefined;
+        render(callback: OnResizeCallback): undefined;
+        readonly _$isConnected: boolean;
+    };
+}>;

package/dist/functional-element/directives/on-resize.directive.js

@@ -0,0 +1,36 @@
+import { directive, Directive } from 'lit/directive.js';
+import { assertsIsElementPartInfo } from './directive-util';
+const directiveName = 'onResize';
+export const onResize = directive(class extends Directive {
+    constructor(partInfo) {
+        super(partInfo);
+        this.resizeObserver = new ResizeObserver((entries) => this.fireCallback(entries));
+        assertsIsElementPartInfo(partInfo, directiveName);
+    }
+    fireCallback(entries) {
+        var _a;
+        const resizeEntry = entries[0];
+        if (!resizeEntry) {
+            console.error(entries);
+            throw new Error(`${directiveName} observation triggered but the first entry was empty.`);
+        }
+        (_a = this.callback) === null || _a === void 0 ? void 0 : _a.call(this, { target: resizeEntry.target, contentRect: resizeEntry.contentRect });
+    }
+    update(partInfo, [callback]) {
+        assertsIsElementPartInfo(partInfo, directiveName);
+        this.callback = callback;
+        const newElement = partInfo.element;
+        // if the element changes we need to observe the new one
+        if (newElement !== this.element) {
+            if (this.element) {
+                this.resizeObserver.unobserve(this.element);
+            }
+            this.resizeObserver.observe(newElement);
+            this.element = newElement;
+        }
+        return this.render(callback);
+    }
+    render(callback) {
+        return undefined;
+    }
+});

package/dist/functional-element/functional-element.d.ts

@@ -2,6 +2,20 @@ import { CSSResult, LitElement, TemplateResult } from 'lit';
 import { EventDescriptorMap, EventsInitMap } from './element-events';
 import { ElementPropertyDescriptorMap, PropertyInitMapBase } from './element-properties';
 import { RenderCallback } from './render-callback';
+export declare type FunctionalElementInit<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap> = {
+    /**
+     * HTML tag name. This should not be used directly, as interpolating it with the html tagged
+     * template from this package is preferred.
+     */
+    tagName: string;
+    /** Static styles. These should not and cannot change. */
+    styles?: CSSResult | undefined;
+    /** Initializer for element properties. (These can be thought of as "inputs".) */
+    props?: PropertyInitGeneric | undefined;
+    /** Initializer for events that the element can dispatch. (These can be thought of as "outputs".) */
+    events?: EventsInitGeneric | undefined;
+    renderCallback: RenderCallback<PropertyInitGeneric, EventsInitGeneric>;
+};
 export declare abstract class FunctionalElementBaseClass<PropertyInitGeneric extends PropertyInitMapBase> extends LitElement {
     static readonly tagName: string;
     static readonly styles: CSSResult;

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 export * from './functional-element/define-functional-element';
-export * from './functional-element/directives/event-listen.directive';
-export * from './functional-element/directives/property-assign.directive';
+export * from './functional-element/directives/assign-with-clean-up.directive';
+export * from './functional-element/directives/assign.directive';
+export * from './functional-element/directives/listen.directive';
+export * from './functional-element/directives/on-dom-created.directive';
+export * from './functional-element/directives/on-resize.directive';
 export * from './functional-element/element-events';
 export * from './functional-element/element-properties';
 export * from './functional-element/functional-element';
-export * from './functional-element/functional-element-init';
-export * from './functional-element/lifecycle-callback';
 export * from './functional-element/render-callback';
-export * from './vir-html/directive';
 export * from './vir-html/vir-html';

package/dist/index.js

@@ -1,11 +1,11 @@
 export * from './functional-element/define-functional-element';
-export * from './functional-element/directives/event-listen.directive';
-export * from './functional-element/directives/property-assign.directive';
+export * from './functional-element/directives/assign-with-clean-up.directive';
+export * from './functional-element/directives/assign.directive';
+export * from './functional-element/directives/listen.directive';
+export * from './functional-element/directives/on-dom-created.directive';
+export * from './functional-element/directives/on-resize.directive';
 export * from './functional-element/element-events';
 export * from './functional-element/element-properties';
 export * from './functional-element/functional-element';
-export * from './functional-element/functional-element-init';
-export * from './functional-element/lifecycle-callback';
 export * from './functional-element/render-callback';
-export * from './vir-html/directive';
 export * from './vir-html/vir-html';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "0.0.5",
+    "version": "0.2.0",
     "keywords": [
         "custom",
         "web",

package/dist/functional-element/functional-element-init.d.ts

@@ -1,22 +0,0 @@
-import { CSSResult } from 'lit';
-import { EventsInitMap } from './element-events';
-import { PropertyInitMapBase } from './element-properties';
-import { LifecycleCallback } from './lifecycle-callback';
-import { RenderCallback } from './render-callback';
-export declare type FunctionalElementInit<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap> = {
-    /**
-     * HTML tag name. This should not be used directly, as interpolating it with the html tagged
-     * template from this package is preferred.
-     */
-    tagName: string;
-    /** Static styles. These should not and cannot change. */
-    styles?: CSSResult | undefined;
-    /** Initializer for element properties. (These can be thought of as "inputs".) */
-    props?: PropertyInitGeneric | undefined;
-    /** Initializer for events that the element can dispatch. (These can be thought of as "outputs".) */
-    events?: EventsInitGeneric | undefined;
-    connectedCallback?: LifecycleCallback<PropertyInitGeneric, EventsInitGeneric>;
-    disconnectedCallback?: LifecycleCallback<PropertyInitGeneric, EventsInitGeneric>;
-    firstUpdated?: LifecycleCallback<PropertyInitGeneric, EventsInitGeneric>;
-    renderCallback: RenderCallback<PropertyInitGeneric, EventsInitGeneric>;
-};

package/dist/functional-element/functional-element-init.js

@@ -1 +0,0 @@
-export {};

package/dist/functional-element/lifecycle-callback.d.ts

@@ -1,8 +0,0 @@
-import { EventsInitMap } from './element-events';
-import { PropertyInitMapBase } from './element-properties';
-import { FunctionalElementInstance } from './functional-element';
-import { RenderParams } from './render-callback';
-export declare type LifecycleCallbackParams<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap> = {
-    element: FunctionalElementInstance<PropertyInitGeneric>;
-} & RenderParams<PropertyInitGeneric, EventsInitGeneric>;
-export declare type LifecycleCallback<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap> = (params: LifecycleCallbackParams<PropertyInitGeneric, EventsInitGeneric>) => void;

package/dist/functional-element/lifecycle-callback.js

@@ -1 +0,0 @@
-export {};

package/dist/vir-html/directive.d.ts

@@ -1,9 +0,0 @@
-/** For some reason these aren't defined in lit's types already. */
-export declare type ExtraPartInfoProperties = {
-    element: HTMLElement;
-    options: {
-        host: HTMLElement;
-        renderBefore: HTMLElement;
-        isConnected: boolean;
-    };
-};

package/dist/vir-html/directive.js

@@ -1 +0,0 @@
-export {};