hyper-element 0.11.1 → 0.12.1

package/index.d.ts

@@ -0,0 +1,188 @@
+/**
+ * hyper-element - hyperHTML + WebComponents
+ * A lightweight library for creating custom elements with hyperHTML templating.
+ */
+
+/**
+ * Tagged template literal function for rendering HTML content.
+ * Use as a tagged template: Html`<div>${value}</div>`
+ *
+ * Supports auto-wire syntax for efficient list rendering:
+ * ```javascript
+ * Html`<ul>{+each ${users}}<li>{name}</li>{-each}</ul>`;
+ * ```
+ *
+ * This is equivalent to:
+ * ```javascript
+ * Html`<ul>${users.map(u => Html.wire(u, id)`<li>${u.name}</li>`)}</ul>`;
+ * ```
+ *
+ * Syntax:
+ * - `{+each ${array}}...{-each}` - Loop with auto-wire for DOM reuse
+ * - `{name}` - Access item property
+ * - `{address.city}` - Nested property access
+ * - `{...}` or `{ ... }` - Current item value (formatted: primitives escaped, arrays join(","), objects JSON, functions called)
+ * - `{@}` - Current array index (0-based)
+ * - `{+each {items}}...{-each}` - Nested loop using parent's property
+ */
+export interface HtmlFunction {
+  /**
+   * Render HTML content using tagged template literals
+   */
+  (strings: TemplateStringsArray, ...values: any[]): any;
+
+  /**
+   * Create a wired template bound to an object for efficient re-rendering
+   * @param obj - Object to bind the template to
+   * @param id - Optional template identifier
+   */
+  wire(
+    obj: object,
+    id?: string
+  ): (strings: TemplateStringsArray, ...values: any[]) => any;
+
+  /**
+   * Create a lightweight template without wire binding
+   */
+  lite(strings: TemplateStringsArray, ...values: any[]): any;
+
+  /**
+   * Mark a string as safe HTML that should not be escaped.
+   * Use with caution - only for trusted HTML content.
+   * @param html - The HTML string to mark as safe
+   */
+  raw(html: string): { value: string };
+
+  /**
+   * Template function available when template attribute is used on the element
+   */
+  template?: (data: Record<string, any>) => any;
+}
+
+/**
+ * Context object available as `this` in render() and setup() methods
+ */
+export interface ElementContext {
+  /** The DOM element */
+  element: HTMLElement;
+  /** Parsed attributes from the element with automatic type coercion */
+  attrs: Record<string, any>;
+  /** Dataset proxy with automatic type coercion */
+  dataset: Record<string, any>;
+  /** Store value from setup */
+  store?: any;
+  /** Text content of element */
+  wrappedContent: string;
+}
+
+/**
+ * Result object returned from fragment methods (methods starting with capital letter)
+ */
+export interface FragmentResult {
+  /** Rendered content */
+  any?: any;
+  /** Render only once */
+  once?: boolean;
+  /** Template string or promise resolving to template */
+  template?:
+    | string
+    | Promise<
+        string | { template: string; values: Record<string, any> | any[] }
+      >;
+  /** Template values */
+  values?: Record<string, any> | any[];
+  /** Text content */
+  text?: string;
+  /** HTML content */
+  html?: string;
+  /** Placeholder content */
+  placeholder?: any;
+}
+
+/**
+ * Callback for store updates in setup.
+ * Call this with a store value or getter function to enable reactive updates.
+ */
+export type OnNextCallback = (
+  store: any | (() => any)
+) => (...data: any[]) => void;
+
+/**
+ * Base class for creating custom elements with hyperHTML templating.
+ * Extend this class and implement the render() method to create a custom element.
+ *
+ * @example
+ * ```javascript
+ * class MyElement extends hyperElement {
+ *   render(Html) {
+ *     Html`<div>Hello ${this.attrs.name}!</div>`;
+ *   }
+ * }
+ * customElements.define('my-element', MyElement);
+ * ```
+ */
+export class hyperElement extends HTMLElement {
+  /** Unique identifier for this element instance */
+  identifier: symbol;
+
+  /** Parsed attributes from the element with automatic type coercion */
+  attrs: Record<string, any>;
+
+  /** Store value from setup */
+  store?: any;
+
+  /** Dataset proxy with automatic type coercion */
+  dataset: Record<string, any>;
+
+  /** Text content of element */
+  wrappedContent: string;
+
+  /** Reference to the DOM element */
+  element: HTMLElement;
+
+  /** Get the innerHTML of the shadow/element content */
+  get innerShadow(): string;
+
+  /**
+   * Optional setup lifecycle method. Called once when the element is connected.
+   * Use this to set up stores, subscriptions, or other initialization logic.
+   *
+   * @param onNext - Call this with a store value or getter to enable reactive updates
+   * @returns Optional teardown function called when element is disconnected
+   *
+   * @example
+   * ```javascript
+   * setup(onNext) {
+   *   const store = createStore({ count: 0 });
+   *   onNext(store.getState);
+   *   return store.subscribe(() => this.render());
+   * }
+   * ```
+   */
+  setup?(onNext: OnNextCallback): void | (() => void);
+
+  /**
+   * Required render lifecycle method. Called on every render cycle.
+   * Use the Html template tag to render content to the element.
+   *
+   * @param Html - Tagged template literal function for rendering
+   * @param data - Additional data passed from store updates
+   *
+   * @example
+   * ```javascript
+   * render(Html) {
+   *   Html`<div>Hello ${this.attrs.name}!</div>`;
+   * }
+   * ```
+   */
+  render(Html: HtmlFunction, ...data: any[]): void;
+}
+
+declare global {
+  interface Window {
+    hyperElement: typeof hyperElement;
+    hyperHTML: any;
+  }
+}
+
+export default hyperElement;

package/package.json

@@ -1,12 +1,27 @@
 {
-  "version": "0.11.1",
+  "version": "0.12.1",
   "name": "hyper-element",
   "author": "Brian Shannon (github.com/codemeasandwich)",
   "description": "hyperHTML + WebComponents",
-  "main": "source/hyperElement.js",
+  "main": "build/hyperElement.js",
+  "types": "index.d.ts",
+  "files": [
+    "build/hyperElement.min.js",
+    "build/hyperElement.min.js.map",
+    "index.d.ts"
+  ],
   "scripts": {
-    "build": "./node_modules/.bin/babel --presets es2015 source/hyperElement.js -o source/bundle.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "node scripts/build.js",
+    "test": "npm run build && playwright test; rm -rf build",
+    "test:ui": "npm run build && playwright test --ui; rm -rf build",
+    "test:headed": "npm run build && playwright test --headed; rm -rf build",
+    "kitchensink": "npx serve .",
+    "release": "bash scripts/publish.sh",
+    "hooks:install": "cp .hooks/pre-commit .git/hooks/ && cp .hooks/commit-msg .git/hooks/ && cp -r .hooks/pre-commit.d .git/hooks/ && chmod +x .git/hooks/pre-commit .git/hooks/commit-msg .git/hooks/pre-commit.d/*.sh",
+    "prepare": "npm run hooks:install",
+    "lint": "eslint src/",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write ."
   },
   "license": "MIT",
   "repository": {
@@ -22,11 +37,28 @@
     "webcomponents"
   ],
   "dependencies": {
-    "hyperhtml": "^2.4.3"
+    "hyperhtml": "^2.34.2"
   },
   "devDependencies": {
-    "babel-cli": "^6.26.0",
-    "babel-core": "^6.26.0",
-    "babel-preset-es2015": "^6.24.1"
+    "@commitlint/cli": "^18.6.1",
+    "@commitlint/config-conventional": "^18.6.3",
+    "@playwright/test": "^1.40.0",
+    "c8": "^10.1.3",
+    "decode-uri-component": "^0.2.2",
+    "esbuild": "^0.25.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-prettier": "^5.5.5",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.5.2",
+    "lodash": "^4.17.21",
+    "minimist": "^1.2.8",
+    "mkdirp": "^1.0.4",
+    "prettier": "^3.8.0",
+    "serve": "^14.2.5",
+    "set-value": "^2.0.1",
+    "typescript": "^5.9.3",
+    "union-value": "^2.0.1",
+    "v8-to-istanbul": "^9.3.0"
   }
 }

package/example/index.ejs

@@ -1,28 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-  <script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.19/webcomponents-lite.js"></script>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/mobx/3.3.2/mobx.umd.min.js"></script>
-  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js" type="text/javascript"></script>
-  <script src="http://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.3.3/underscore-min.js" type="text/javascript"></script>
-  <script src="http://cdnjs.cloudflare.com/ajax/libs/backbone.js/0.9.2/backbone-min.js" type="text/javascript"></script>
-  <script src="https://unpkg.com/hyperhtml@latest/min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/hyper-element@latest/source/hyperElement.js"></script>
-  <script src="./logic.js"></script>
-  <script src="./test-elem.js"></script>
-</head>
-
-<body>
-<div id="app"/>
-<test-elem max="50"></test-elem>
-<my-profile>my profile</my-profile>
-
-<script>
-  window.addEventListener('WebComponentsReady', function(e) {
-    console.log("App ready!","imports are loaded and elements have been registered")
-  });
-</script>
-</body>
-
-</html>

package/example/index.js

@@ -1,2 +0,0 @@
-//import hyperElement from '../source/hyperElement.js'
-//window.hyperElement = hyperElement

package/example/logic.js

@@ -1,95 +0,0 @@
-'use strict';
-//runInAction // https://www.youtube.com/watch?v=uAlxod75FIM
-const { observable, observe, autorun, computed, runInAction } = mobx;
-
-/*
-class Todo {
-//  id = Math.random();
-  @observable title;
-  @observable finished = false;
-  @computed get unfinishedTodoCount() {
-    return this.finished;
-  }
-  constructor(title) {
-    this.title = title;
-  }
-}*/
-
-
-var todoStore = observable({
-    /* some observable state */
-    todos: [],
-
-    /* a derived value */
-    get completedCount() {
-        return this.todos.filter(todo => todo.completed).length;
-    }
-});
-
-/* a function that observes the state */
-autorun(function() {
-    console.log("Completed %d of %d items",
-        todoStore.completedCount,
-        todoStore.todos.length
-    );
-});
-
-/* ..and some actions that modify the state */
-todoStore.todos[0] = {
-    title: "Take a walk",
-    completed: false
-};
-// -> synchronously prints 'Completed 0 of 1 items'
-
-todoStore.todos[0].completed = true;
-// -> synchronously prints 'Completed 1 of 1 items'
-
-
-
-(()=>{
-
-
-const appState = observable({
-
-    get fullName () {
-      console.count('fullName');
-      return this.firstName + ' ' + this.lastName;
-    },
-    firstName: 'Matt',
-    lastName: 'Ruby',
-    form:'',
-    top:0,
-    devices:["d1","d2"],
-    age: 34,
-    temperature:80,
-    todos:[
-      { title:"foo", done: false },
-      { title:"bar", done: true  },
-    ],
-    get completedCount() {
-      console.count('completedCount');
-        return this.todos.filter(todo => todo.done).length;
-    }
-})
-/*
-const appState = new class appState{
-  @observable firstName = 'Matt'
-  @observable lastName = 'Ruby'
-  @observable top =0
-  @observable devices =["d1","d2"]
-  @observable age = 34
-  @observable temperature=80
-  @observable todos=[
-    {  title:"foo", done: false  },
-    {  title:"bar", done: true  },
-  ],
-  @computed get completedCount() {
-    console.count('completedCount');
-      return this.todos.filter(todo => todo.done).length;
-  }
-
-}*/
-
-window.appState = appState;
-
-})()

package/example/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "example",
-  "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "start":"poi",
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "",
-  "license": "ISC",
-  "dependencies": {
-    "mobx": "^3.4.1"
-  }
-}

package/example/poi.config.js

@@ -1,4 +0,0 @@
-module.exports = {
-  minimize:true,
-  sourceMap:true
-}

package/example/test-elem.js

@@ -1,118 +0,0 @@
-'use strict';
-(()=>{
-
-//=====================================================
-//============================= Example: simple element
-//=====================================================
-
-    document.registerElement("the-max", class extends hyperElement{
-      render(Html){
-        Html`MAX:${this.props.max}`
-      }
-    })
-
-//=====================================================
-//============================= Example: using backbone
-//=====================================================
-
-//+++++++++++++++++++++++++++++++++++++ Backbone Model
-//++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-    var person = new (Backbone.Model.extend({
-        defaults: {
-            name: 'Guest User',
-        }
-    }));
-
-    // to change from console !!!!!
-    window.person = person;
-
-//++++++++++++++++++++++++++++++++++++++++ The Element
-//++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-    document.registerElement("my-profile", class extends hyperElement{
-
-      setup(onNext){
-        person.on("change",onNext(person.toJSON.bind(person)));
-        // OR person.on("change",onNext(()=>person.toJSON()));
-      }
-
-      render(Html,{name}){
-        Html`Profile: ${name}`
-      }
-    })
-
-
-//=====================================================
-//================================= Example: using mobx
-//======================================== using a wire
-
-    document.registerElement("alex-rocks", class extends hyperElement{
-
-      setup(onNext){
-        mobx.autorun(onNext(window.appState));
-      }
-
-      render(Html,{devices}){
-
-        const _ = Html.lite;
-
-        Html`
-
-        Your devices
-        <ul>${
-
-        devices.map(num=> _`<li>${num}</li>`)
-
-        }</ul>
-        <the-max max=20 />`
-      }
-    })
-
-//=====================================================
-//================================= Example: using mobx
-//========================================= with inputs
-
-  document.registerElement("test-elem", class extends hyperElement{
-
-    setup(onNext){
-      mobx.autorun(onNext(window.appState));
-    }
-
-    render(Html,store){
-
-      const max = this.props.max || 100
-
-      Html`
-
-          <h1 style=${{color:store.temperature < max ? "green":"red"}}>
-               temperature: ${store.temperature}
-          </h1>
-          ${store.fullName} ${store.completedCount} ${store.todos.length}
-          <h2>Time is ${new Date().toLocaleTimeString()}.</h2>
-
-              <input oninput=${this.oninput}
-                      value=${store.form}
-                      onkeyup=${this.onkeyup}/>
-
-          <br/>
-          <alex-rocks />
-
-      `}
-
-      onkeyup({key}){
-        if("Enter" === key)
-        this.save()
-      }
-
-      save(){
-          this.store.devices.push(this.store.form);
-          this.store.form = "";
-      }
-
-      oninput(event){
-        this.store.form = event.target.value
-      }
-  })
-
-})()