element-vir 3.1.0 → 4.0.0

package/README.md

@@ -1,18 +1,19 @@
 # element-vir
 
-Heroic, reactive, functional, type safe, custom web components.
+Heroic. Reactive. Functional. Type safe. Web components without compromise.
 
 No need for an extra build step,<br>
-no need for weird file extensions,<br>
+no need for side effect imports, <br>
+no need for unique file extensions,<br>
 no need for extra static analysis tools,<br>
-no need for a dedicated funky syntax.<br>
+no need for a dedicated, unique syntax.<br>
 _**It's just TypeScript.**_
 
-Built using the power of _native_ JavaScript custom web elements, _native_ JavaScript template literals, _native_ JavaScript functions<sup>\*</sup>, _native_ HTML, and [lit-element](http://lit.dev).
+Uses the power of _native_ JavaScript custom web elements, _native_ JavaScript template literals, _native_ JavaScript functions<sup>\*</sup>, _native_ HTML, and [lit-element](http://lit.dev).
 
-This is basically a [lit-element](http://lit.dev) wrapper that adds type-safe I/O and functional-programming style component definition.
+In reality this is basically a [lit-element](http://lit.dev) wrapper that adds type-safe element tag usage and I/O with functional-programming style component definition.
 
-[Works in every major browser except Internet Explorer.](https://caniuse.com/mdn-api_window_customelements) <sub>(Heaven help you if you still need to support IE.)</sub>
+[Works in every major web browser except Internet Explorer.](https://caniuse.com/mdn-api_window_customelements)
 
 <sub>\*okay I hope it's obvious that functions are native</sub>
 
@@ -24,15 +25,17 @@ This is basically a [lit-element](http://lit.dev) wrapper that adds type-safe I/
 npm i element-vir
 ```
 
+Make sure to install this as a normal dependency (not just a dev dependency) because it needs to exist at run time.
+
 # Usage
 
 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.
+All of [`lit`](https://lit.dev)'s syntax and functionality is also available for use if you wish.
 
 ## 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:
+Use `defineFunctionalElement` to define your element. Tt must be given an object with at least `tagName` and `renderCallback` properties (the types enforce this). Here is a bare-minimum example custom element:
 
 <!-- example-link: src/readme-examples/my-simple.element.ts -->
 
@@ -47,7 +50,7 @@ export const MySimpleElement = defineFunctionalElement({
 });
 ```
 
-Make sure to export your element definition as that will be used to instantiate it in your HTML templates.
+Make sure to export your element definition if you need to use it in other files.
 
 ## Using in other elements
 
@@ -70,17 +73,16 @@ export const MyAppElement = defineFunctionalElement({
 
 This requirement ensures that the element is properly imported and registered with the browser. (Compare to pure [lit](http://lit.dev) where you must remember to import each element file as a side effect, or without actually referencing any of its exports in your code.)
 
-If you wish to bypass this interpolation requirement, instead [import `html` directly from `lit`](https://lit.dev/docs/components/overview/).
+If you wish to bypass this interpolation, make sure to [import the `html` tagged template directly from `lit`](https://lit.dev/docs/components/overview/), `import {html} from 'lit';`, instead of version contained in `element-vir`.
 
 ## Adding styles
 
-Styles are added through `styles` when defining a functional element (similar to [how they are defined in `lit`](https://lit.dev/docs/components/styles/)):
+Styles are added through the `styles` property when defining a functional element (similar to [how they are defined in `lit`](https://lit.dev/docs/components/styles/)):
 
 <!-- example-link: src/readme-examples/my-simple-app-with-styles.element.ts -->
 
 ```TypeScript
-import {css} from 'lit';
-import {defineFunctionalElement, html} from 'element-vir';
+import {css, defineFunctionalElement, html} from 'element-vir';
 
 export const MySimpleWithStylesElement = defineFunctionalElement({
     tagName: 'my-simple-with-styles-element',
@@ -102,9 +104,32 @@ export const MySimpleWithStylesElement = defineFunctionalElement({
 });
 ```
 
+### Element definition as style selector
+
+Functional element definitions can be used in the `css` tagged template just like in the `html` tagged template. This will be replaced by the element's tag name:
+
+<!-- example-link: src/readme-examples/my-simple-app-with-styles-and-interpolated-selector.element.ts -->
+
+```TypeScript
+import {css, defineFunctionalElement, html} from 'element-vir';
+import {MySimpleElement} from './my-simple.element';
+
+export const MySimpleWithStylesAndInterpolatedSelectorElement = defineFunctionalElement({
+    tagName: 'my-simple-with-styles-and-interpolated-selector-element',
+    styles: css`
+        ${MySimpleElement} {
+            background-color: blue;
+        }
+    `,
+    renderCallback: () => html`
+        <${MySimpleElement}></${MySimpleElement}>
+    `,
+});
+```
+
 ## Defining and using properties (inputs)
 
-Define properties with `props` when defining a functional element. Each property must be given a default value. If you wish to leave the property's default value as `undefined`, give it a type as well (shown below with `as string | undefined`) so you can assign a defined value of that type to it later.
+Define element properties with `props` when making a functional element. Each property must be given a default value. If you wish to leave the property's default value as `undefined`, give it a type as well (shown below with `as string | undefined`) so you can assign a defined value of that type to it later.
 
 To use a custom element's properties, grab `props` from `renderCallback`'s parameters and interpolate it into your HTML template:
 
@@ -148,43 +173,37 @@ export const MyAppWithPropsElement = defineFunctionalElement({
 });
 ```
 
-## Defining and dispatching custom events (outputs)
+## Element events (outputs)
 
-Define events with `events` when defining a functional element. Each event must be initialized with `eventInit` and a type parameter. `eventInit` accepts no inputs as it doesn't make sense for events to have a default value.
+Define events with `events` when making a functional element. Each event must be initialized with `defineElementEvent` and a type parameter. `defineElementEvent` accepts no inputs as it doesn't make sense for events to have default values.
 
-To dispatch an event, grab `dispatchElementEvent` from `renderCallback`'s parameters.
+To dispatch an event, grab `dispatch` from `renderCallback`'s parameters.
 
 <!-- example-link: src/readme-examples/my-simple-with-events.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, ElementEvent, eventInit, html} from 'element-vir';
+import {defineElementEvent, defineFunctionalElement, html, listen} from 'element-vir';
 
 export const MySimpleWithEventsElement = defineFunctionalElement({
     tagName: 'my-simple-element-with-events',
     events: {
-        logoutClick: eventInit<void>(),
-        randomNumber: eventInit<number>(),
+        logoutClick: defineElementEvent<void>(),
+        randomNumber: defineElementEvent<number>(),
     },
-    renderCallback: ({dispatchElementEvent, events}) => html`
-        <!-- normal DOM events must be listened to with the "@" keyword from lit. -->
-        <button
-            @click=${() => dispatchElementEvent(new ElementEvent(events.logoutClick, undefined))}
-        >
+    renderCallback: ({dispatch, events}) => html`
+        <button ${listen('click', () => dispatch(new events.logoutClick(undefined)))}>
             log out
         </button>
-        <button
-            @click=${() =>
-                dispatchElementEvent(new ElementEvent(events.randomNumber, Math.random()))}
-        >
+        <button ${listen('click', () => dispatch(new events.randomNumber(Math.random())))}>
             generate random number
         </button>
     `,
 });
 ```
 
-## Listening to custom events (outputs)
+## Listening to typed events (outputs)
 
-Use the `listen` directive to listen to custom events emitted by your custom functional elements:
+Use the `listen` directive to listen to typed events emitted by your custom functional elements:
 
 <!-- example-link: src/readme-examples/my-app-with-events.element.ts -->
 
@@ -213,21 +232,25 @@ export const MyAppWithEventsElement = defineFunctionalElement({
 });
 ```
 
-## Custom events without an element
+`listen` can also be used to listen to native DOM events (like `click`) and the proper event type will be provided for the listener callback.
+
+## Typed events without an element
 
-Create a custom event type with `defineCustomEvent`. Make sure to include the type generics (like this: `defineCustomEvent<'customEventName', string>`) to ensure type safety when using your event.
+Create a custom event type with `defineTypedEvent`. Make sure to include the type generic (like this: `defineTypedEvent<number>`) and call it twice, the second time with the event type string, (like this: `defineTypedEvent<number>()('my-event-type-name')`) to ensure type safety when using your event. Note that event type names should probably be unique, or they may clash with each other.
 
-Creating a custom event:
+### Creating a typed event
 
 <!-- example-link: src/readme-examples/custom-event-no-element.ts -->
 
 ```TypeScript
-import {defineCustomEvent} from 'element-vir';
+import {defineTypedEvent} from 'element-vir';
 
-export const MyCustomEvent = defineCustomEvent<'myCustomEventName', number>('myCustomEventName');
+export const MyCustomEvent = defineTypedEvent<number>()('myCustomEventName');
 ```
 
-Using a custom event (both dispatching and listening):
+### Using a typed event
+
+Both dispatching a custom event and listening to a custom event:
 
 <!-- example-link: src/readme-examples/custom-event-usage.element.ts -->
 
@@ -237,16 +260,16 @@ import {MyCustomEvent} from './custom-event-no-element';
 
 export const MyElementWithCustomEvents = defineFunctionalElement({
     tagName: 'my-app-with-custom-events',
-    renderCallback: ({dispatchEvent: defaultDispatchEvent}) => html`
+    renderCallback: ({genericDispatch}) => html`
         <div
             ${listen(MyCustomEvent, (event) => {
                 console.log(`Got a number! ${event.detail}`);
             })}
         >
             <div
-                @click=${() => {
-                    defaultDispatchEvent(new MyCustomEvent(Math.random()));
-                }}
+                ${listen('click', () => {
+                    genericDispatch(new MyCustomEvent(Math.random()));
+                })}
             ></div>
         </div>
     `,
@@ -255,13 +278,13 @@ export const MyElementWithCustomEvents = defineFunctionalElement({
 
 ## Directives
 
-Some custom [`lit` directives](https://lit.dev/docs/templates/custom-directives/) are also contained within this package.
+The following custom [`lit` directives](https://lit.dev/docs/templates/custom-directives/) are contained within this package.
 
 ### onDomCreated
 
 This directive should be used instead of trying to use `querySelector` directly on the custom element.
 
-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.
+This triggers only once when the element it's attached has actually been created in the DOM. If it's attached element changes, the callback will be triggered again.
 
 <!-- example-link: src/readme-examples/my-simple-with-on-dom-created.element.ts -->
 
@@ -285,7 +308,7 @@ export const MySimpleWithOnDomCreatedElement = defineFunctionalElement({
 
 ### 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).
+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 passed an object with a portion of the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) properties (since not all properties are supported well in browsers).
 
 <!-- example-link: src/readme-examples/my-simple-with-on-resize.element.ts -->
 
@@ -316,33 +339,14 @@ Assign a value to one of a custom element's properties. This is explained in the
 
 Listen to a specific event emitted from a custom element. This is explained in the **Listening to custom events (outputs)** section earlier in this README.
 
-### namedListen
-
-Listen to an event by name directly. This can be used to listen to native events as well as custom events. However, `listen` (explained above) is better for custom events as it'll give you better type information. When using `namedListen` for native DOM events (like `'click'`) the callback will be typed correctly. When listening to custom events, however, it can't guess the callback type from anywhere so the event parameter type will be unknown.
-
-<!-- example-link: src/readme-examples/my-simple-with-named-listen.element.ts -->
-
-```TypeScript
-import {defineFunctionalElement, html, namedListen} from 'element-vir';
-
-export const MySimpleWithNamedListenElement = defineFunctionalElement({
-    tagName: 'my-simple-element-with-named-listen',
-    renderCallback: () => html`
-        <!-- normal DOM events can be listened to  -->
-        <button ${namedListen('click', (event) => console.log(event.buttons))}>click me</button>
-    `,
-});
-```
-
 ### assignWithCleanup
 
-This directive is the same as the `assign` directive but it accepts an additional `cleanupCallback` input. Use this directive to assign values which need some kind of cleanup if they're overwritten. For example, a 3D rendering engine which uses the canvas that should free up memory when it's swapped out.
+This directive is the same as the `assign` directive but it accepts an additional `cleanupCallback` input. Use this directive to assign values which need some kind of cleanup when they're overwritten. For example, a 3D rendering engine which uses the canvas that should free up memory when it's swapped out.
 
 <!-- example-link: src/readme-examples/my-app-with-cleanup.element.ts -->
 
 ```TypeScript
-import {assign, defineFunctionalElement, html} from 'element-vir';
-import {assignWithCleanup} from '../functional-element/directives/assign-with-clean-up.directive';
+import {assign, assignWithCleanup, defineFunctionalElement, html} from 'element-vir';
 import {MySimpleWithPropsElement} from './my-simple-with-props.element';
 
 export const MyAppWithPropsElement = defineFunctionalElement({
@@ -373,7 +377,13 @@ To require all child elements to be functional elements defined by this package,
 <!-- example-link: src/readme-examples/require-functional-element.ts -->
 
 ```TypeScript
-import {requireAllCustomElementsToBeFunctionalElement} from '../require-functional-element';
+import {requireAllCustomElementsToBeFunctionalElement} from 'element-vir';
 
 requireAllCustomElementsToBeFunctionalElement();
 ```
+
+# Dev
+
+## markdown out of date
+
+If you see this: `Code in Markdown file(s) is out of date. Run without --check to update. code-in-markdown failed.`, run `npm run update-docs` to fix it.

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

@@ -27,7 +27,6 @@ export function defineFunctionalElement(functionalElementInit) {
         },
         _a.tagName = functionalElementInit.tagName,
         _a.styles = functionalElementInit.styles || css ``,
-        _a.propNames = Object.keys(functionalElementInit.props || {}),
         _a.events = eventsMap,
         _a.renderCallback = functionalElementInit.renderCallback,
         _a.props = createPropertyDescriptorMap(functionalElementInit.props),

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

@@ -20,7 +20,6 @@ export declare type FunctionalElementInit<PropertyInitGeneric extends PropertyIn
 export declare abstract class FunctionalElementBaseClass<PropertyInitGeneric extends PropertyInitMapBase> extends LitElement {
     static readonly tagName: string;
     static readonly styles: CSSResult;
-    static readonly propNames: string[];
     abstract render(): TemplateResult | Promise<TemplateResult>;
     abstract readonly instanceProps: PropertyInitGeneric;
 }
@@ -37,5 +36,4 @@ export declare type ExtraStaticFunctionalElementProperties<PropertyInitGeneric e
      */
     tagName: string;
     styles: CSSResult;
-    propNames: string[];
 }>;

package/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>Element Vir Test</title>
+        <script type="module" src="/src/test/elements/app.element.ts"></script>
+        <link rel="stylesheet" type="text/css" href="/index.css" />
+        <script>
+            console.log('yo');
+        </script>
+    </head>
+    <body>
+        <element-vir-test-app></element-vir-test-app>
+    </body>
+</html>

package/jest/jest.config.ts

@@ -0,0 +1,32 @@
+import {dirname, join} from 'path';
+import {pathsToModuleNameMapper} from 'ts-jest';
+import {InitialOptionsTsJest} from 'ts-jest/dist/types';
+import {findTsConfigFile, getTsconfigPathAliases} from './read-tsconfig';
+
+const repoRootDir = dirname(__dirname);
+
+const config: InitialOptionsTsJest = {
+    preset: 'ts-jest',
+    testEnvironment: 'jsdom',
+    verbose: false,
+    // type tests are caught by the typescript compiler
+    testPathIgnorePatterns: ['.type.test.ts'],
+    rootDir: repoRootDir,
+    silent: false,
+    moduleNameMapper: pathsToModuleNameMapper(getTsconfigPathAliases(), {
+        prefix: '<rootDir>/',
+    }) as Record<string, string | string[]>,
+    roots: [join(repoRootDir, 'src')],
+    setupFilesAfterEnv: [join(__dirname, 'jest.setup.ts')],
+    globals: {
+        'ts-jest': {
+            tsconfig: findTsConfigFile(),
+            diagnostics: {
+                warnOnly: true,
+                ignoreCodes: ['TS151001'],
+            },
+        },
+    },
+};
+
+export default config;

package/jest/jest.setup.ts

@@ -0,0 +1,12 @@
+import {CustomConsole, LogMessage, LogType} from '@jest/console';
+
+function simpleFormatter(type: LogType, message: LogMessage): string {
+    const consoleIndent = '      ';
+
+    return message
+        .split(/\n/)
+        .map((line) => consoleIndent + line)
+        .join('\n');
+}
+
+global.console = new CustomConsole(process.stdout, process.stderr, simpleFormatter);

package/jest/read-tsconfig.ts

@@ -0,0 +1,27 @@
+import {dirname} from 'path';
+import {findConfigFile, parseJsonConfigFileContent, readConfigFile, sys as tsSys} from 'typescript';
+
+export function findTsConfigFile(): string {
+    const dirToCheck = __dirname;
+    const configFileName = findConfigFile(dirToCheck, tsSys.fileExists, 'tsconfig.json');
+    if (!configFileName) {
+        throw new Error(
+            `Could not find tsconfig.json file from starting search at "${dirToCheck}"`,
+        );
+    }
+    return configFileName;
+}
+
+export function getTsconfigPathAliases() {
+    const configFileName = findTsConfigFile();
+
+    if (!configFileName) {
+        throw new Error(`Failed to find tsconfig.`);
+    }
+
+    const configFile = readConfigFile(configFileName, tsSys.readFile);
+    const tsConfig = parseJsonConfigFileContent(configFile.config, tsSys, dirname(configFileName));
+    const tsConfigPaths = tsConfig.options.paths || {};
+
+    return tsConfigPaths;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "3.1.0",
+    "version": "4.0.0",
     "keywords": [
         "custom",
         "web",
@@ -25,23 +25,28 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
-        "compile": "virmator compile",
+        "compile": "tsc",
         "format": "virmator format write",
+        "jest": "jest --config ./jest/jest.config.ts",
         "prepublishOnly": "npm run test:full",
         "spellcheck": "virmator spellcheck",
-        "start": "npm install && snowpack dev",
-        "test": "npm run compile",
+        "start": "npm install && vite --force --config ./vite/vite.config.ts",
+        "test": "npm run type-check && npm run jest",
         "test:full": "npm test && npm run spellcheck && virmator format check && npm run update-docs -- --check",
-        "update-docs": "virmator code-in-markdown README.md"
+        "type-check": "tsc --noEmit",
+        "update-docs": "virmator code-in-markdown README.md --index src/index.ts"
     },
     "dependencies": {
-        "augment-vir": "^1.4.2",
-        "lit": "^2.0.2"
+        "augment-vir": "^1.4.3",
+        "lit": "^2.1.1"
     },
     "devDependencies": {
-        "@snowpack/plugin-typescript": "^1.2.1",
-        "snowpack": "^3.8.8",
-        "typescript": "^4.4.4",
-        "virmator": "^1.3.7"
+        "@types/jest": "^27.4.0",
+        "jest": "^27.4.7",
+        "ts-jest": "^27.1.3",
+        "ts-node": "^10.4.0",
+        "typescript": "^4.5.4",
+        "virmator": "^1.3.7",
+        "vite": "^2.7.12"
     }
 }

package/public/index.css

@@ -0,0 +1,7 @@
+html,
+body {
+    margin: 0;
+    padding: 0;
+    height: 100%;
+    width: 100%;
+}

package/vite/always-reload-plugin.ts

@@ -0,0 +1,90 @@
+import chalk from 'chalk';
+import {existsSync, lstatSync, readlinkSync} from 'fs';
+import {relative} from 'path';
+import {PluginOption} from 'vite';
+
+/**
+ * Include actual paths and symlinked target paths if they exist.
+ *
+ * This is needed because when removing files from the watcher, sym links have be removed with the
+ * path to the symlink itself AND the path to the symlink target or the path will still be watched.
+ */
+function mapToActualPaths(paths: Readonly<string[]>): Readonly<string[]> {
+    return paths.reduce((accum, path) => {
+        if (existsSync(path)) {
+            if (lstatSync(path).isSymbolicLink()) {
+                console.info('reading symlink from', path);
+                // sym links AND the original path both need to be included
+                return accum.concat(readlinkSync(path), path);
+            } else {
+                return accum.concat(path);
+            }
+        } else {
+            return accum;
+        }
+    }, [] as string[]);
+}
+
+/**
+ * There are similar plugins out there that try to do this but they aren't aggressive enough. This
+ * plugin literally always reloads on save, no questions asked.
+ */
+export function alwaysReloadPlugin(
+    config: Partial<{
+        exclusions: string[];
+        /** Inclusions apply after exclusions so they will override exclusions. */
+        inclusions: string[];
+        root: string;
+    }> = {},
+): PluginOption {
+    return {
+        name: 'alwaysReloadPlugin',
+        apply: 'serve',
+        config: () => ({server: {watch: {disableGlobbing: false}}}),
+        configureServer({watcher, ws, config: {logger}}) {
+            const {root = process.cwd(), inclusions = [], exclusions = []} = config;
+            let callingAlready = false;
+            let loggedAlready = false;
+
+            const reloadCallback = (path: string) => {
+                if (!loggedAlready) {
+                    loggedAlready = true;
+                    // log watched stuff so that we can make sure it's not watching too much
+                    // console.info({watched: watcher.getWatched()});
+                }
+                // prevent duplicate calls cause the watcher is very eager to call callbacks multiple times in a row
+                if (!callingAlready) {
+                    callingAlready = true;
+                    ws.send({
+                        type: 'full-reload',
+                        path: '*',
+                    });
+                    logger.info(
+                        `${chalk.green('page reload')} ${chalk.dim(relative(root, path))}`,
+                        {clear: true, timestamp: true},
+                    );
+                    /**
+                     * Debounce reloads calls so that they don't get spammed. If you're saving
+                     * faster than this, then what the heck are you doing anyway?
+                     */
+                    setTimeout(() => {
+                        callingAlready = false;
+                    }, 100);
+                }
+            };
+
+            if (exclusions.length) {
+                watcher.unwatch(mapToActualPaths(exclusions));
+                // ignore macOS file system metadata stuff
+                watcher.unwatch('./**/.DS_Store');
+            }
+            if (inclusions.length) {
+                watcher.add(inclusions);
+            }
+            if (!watcher.listeners('change').includes(reloadCallback)) {
+                watcher.on('change', reloadCallback);
+                watcher.on('add', reloadCallback);
+            }
+        },
+    };
+}

package/vite/vite.config.ts

@@ -0,0 +1,10 @@
+import {dirname} from 'path';
+import {alwaysReloadPlugin} from './always-reload-plugin';
+
+const viteConfig = {
+    clearScreen: false,
+    plugins: [alwaysReloadPlugin()],
+    rootDir: dirname(__dirname),
+};
+
+export default viteConfig;