@joist/element 4.0.0-next.10 → 4.0.0-next.11

package/README.md

@@ -65,16 +65,99 @@ Joist ships with a very simple template library. It is designed to be very small
   ]
 })
 export class MyElement extends HTMLElement {
-  @attr()
-  accessor greeting = 'Hello World';
+  greeting = 'Hello World';
 
   items = ['first', 'second', 'third', 'fourth', 'fifth'];
 
+  // initialize renderer
   #render = template();
 
   @ready()
   onReady() {
+    // called once element is ready
+
     this.#render();
   }
 }
 ```
+
+## Styles
+
+To apply styles simply pass the result of the `css` tag to the `shadow` array.
+
+```ts
+@element({
+  tagName: 'my-element',
+  shadow: [
+    css`
+      h1 {
+        color: red;
+      }
+    `,
+    html`<h1>Hello World</h1>`
+  ]
+})
+export class MyElement extends HTMLElement {}
+```
+
+## Listeners
+
+The `@listen` decorator allows you to easy setup event listeners. By default the listener will be attached to the shadow root if it exists or the host element if it doesn't. This can be customized by pass a selector function to the decorator
+
+```ts
+@element({
+  tagName: 'my-element',
+  shadow: []
+})
+export class MyElement extends HTMLElement {
+  @listen('eventname')
+  onEventName1() {
+    // all listener to the shadow root
+  }
+
+  @listen('eventname', (host) => host)
+  onEventName2() {
+    // all listener to the host element
+  }
+
+  @listen('eventname', (host) => host.querySelector('button'))
+  onEventName3() {
+    // add listener to a button found in the light dom
+  }
+
+  @listen('eventname', '#test')
+  onEventName4() {
+    // add listener to element with the id of "test" that is found in the shadow dom
+  }
+}
+```
+
+## Queries
+
+The `query` function will query for a particular element and allow you to easily patch that element with new properties.
+
+```ts
+@element({
+  tagName: 'my-element',
+  shadow: [
+    html`
+      <label for="my-input">
+        <slot></slot>
+      </label>
+
+      <input id="my-input" />
+    `
+  ]
+})
+export class MyElement extends HTMLElement {
+  @observe()
+  value: string;
+
+  #input = query('input');
+
+  @effect()
+  onChange() {
+    this.#input({ value: this.value });
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joist/element",
-  "version": "4.0.0-next.10",
+  "version": "4.0.0-next.11",
   "type": "module",
   "main": "./target/lib.js",
   "module": "./target/lib.js",

package/target/lib/element.d.ts

@@ -43,6 +43,7 @@ export declare function element<Target extends CustomElementConstructor, Instanc
         readonly clientTop: number;
         readonly clientWidth: number;
         id: string;
+        innerHTML: string;
         readonly localName: string;
         readonly namespaceURI: string | null;
         onfullscreenchange: ((this: Element, ev: Event) => any) | null;
@@ -82,12 +83,13 @@ export declare function element<Target extends CustomElementConstructor, Instanc
         getElementsByTagNameNS(namespaceURI: "http://www.w3.org/2000/svg", localName: string): HTMLCollectionOf<SVGElement>;
         getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1998/Math/MathML", localName: string): HTMLCollectionOf<MathMLElement>;
         getElementsByTagNameNS(namespace: string | null, localName: string): HTMLCollectionOf<Element>;
+        getHTML(options?: GetHTMLOptions): string;
         hasAttribute(qualifiedName: string): boolean;
         hasAttributeNS(namespace: string | null, localName: string): boolean;
         hasAttributes(): boolean;
         hasPointerCapture(pointerId: number): boolean;
         insertAdjacentElement(where: InsertPosition, element: Element): Element | null;
-        insertAdjacentHTML(position: InsertPosition, text: string): void;
+        insertAdjacentHTML(position: InsertPosition, string: string): void;
         insertAdjacentText(where: InsertPosition, data: string): void;
         matches(selectors: string): boolean;
         releasePointerCapture(pointerId: number): void;
@@ -95,7 +97,7 @@ export declare function element<Target extends CustomElementConstructor, Instanc
         removeAttributeNS(namespace: string | null, localName: string): void;
         removeAttributeNode(attr: Attr): Attr;
         requestFullscreen(options?: FullscreenOptions): Promise<void>;
-        requestPointerLock(): void;
+        requestPointerLock(options?: PointerLockOptions): Promise<void>;
         scroll(options?: ScrollToOptions): void;
         scroll(x: number, y: number): void;
         scrollBy(options?: ScrollToOptions): void;
@@ -205,7 +207,6 @@ export declare function element<Target extends CustomElementConstructor, Instanc
         before(...nodes: (Node | string)[]): void;
         remove(): void;
         replaceWith(...nodes: (Node | string)[]): void;
-        innerHTML: string;
         readonly nextElementSibling: Element | null;
         readonly previousElementSibling: Element | null;
         readonly childElementCount: number;
@@ -247,7 +248,9 @@ export declare function element<Target extends CustomElementConstructor, Instanc
         onchange: ((this: GlobalEventHandlers, ev: Event) => any) | null;
         onclick: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null;
         onclose: ((this: GlobalEventHandlers, ev: Event) => any) | null;
+        oncontextlost: ((this: GlobalEventHandlers, ev: Event) => any) | null;
         oncontextmenu: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null;
+        oncontextrestored: ((this: GlobalEventHandlers, ev: Event) => any) | null;
         oncopy: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null;
         oncuechange: ((this: GlobalEventHandlers, ev: Event) => any) | null;
         oncut: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null;