Merge pull request #159 from Polymer/query

Add @query, @QueryAll and @CustomElement decorators

Author: Steve Orvell

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+<!--
+   PRs should document their user-visible changes (if any) in the
+   Unreleased section, uncommenting the header as necessary.
+-->
+
+## Unreleased
+
+### Added
+* Added `@query()`, `@queryAll()`, and `@customElement` decorators ([#159](https://github.com/Polymer/lit-element/pull/159))
+
+<!-- ### Changed -->
+<!-- ### Removed -->
+<!-- ### Fixed -->

src/lib/decorators.ts

@@ -0,0 +1,79 @@
+
+/**
+ * @license
+ * Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
+ * This code may only be used under the BSD style license found at
+ * http://polymer.github.io/LICENSE.txt
+ * The complete set of authors may be found at
+ * http://polymer.github.io/AUTHORS.txt
+ * The complete set of contributors may be found at
+ * http://polymer.github.io/CONTRIBUTORS.txt
+ * Code distributed by Google as part of the polymer project is also
+ * subject to an additional IP rights grant found at
+ * http://polymer.github.io/PATENTS.txt
+ */
+
+import {LitElement} from '../lit-element.js';
+
+export type Constructor<T> = {
+  new (...args: unknown[]): T
+};
+
+/**
+ * Class decorator factory that defines the decorated class as a custom element.
+ *
+ * @param tagName the name of the custom element to define
+ *
+ * In TypeScript, the `tagName` passed to `customElement` must be a key of the
+ * `HTMLElementTagNameMap` interface. To add your element to the interface,
+ * declare the interface in this module:
+ *
+ *     @customElement('my-element')
+ *     export class MyElement extends LitElement {}
+ *
+ *     declare global {
+ *       interface HTMLElementTagNameMap {
+ *         'my-element': MyElement;
+ *       }
+ *     }
+ *
+ */
+export const customElement = (tagName: keyof HTMLElementTagNameMap) =>
+    (clazz: Constructor<HTMLElement>) => {
+      window.customElements.define(tagName, clazz);
+      // Cast as any because TS doesn't recognize the return type as being a
+      // subtype of the decorated class when clazz is typed as
+      // `Constructor<HTMLElement>` for some reason. `Constructor<HTMLElement>`
+      // is helpful to make sure the decorator is applied to elements however.
+      return clazz as any;
+    };
+
+/**
+ * A property decorator that converts a class property into a getter that
+ * executes a querySelector on the element's renderRoot.
+ */
+export const query = _query((target: NodeSelector, selector: string) =>
+                                target.querySelector(selector));
+
+/**
+ * A property decorator that converts a class property into a getter
+ * that executes a querySelectorAll on the element's renderRoot.
+ */
+export const queryAll = _query((target: NodeSelector, selector: string) =>
+                                   target.querySelectorAll(selector));
+
+/**
+ * Base-implementation of `@query` and `@queryAll` decorators.
+ *
+ * @param queryFn exectute a `selector` (ie, querySelector or querySelectorAll)
+ * against `target`.
+ */
+function _query<T>(queryFn: (target: NodeSelector, selector: string) => T) {
+  return (selector: string) => (proto: any, propName: string) => {
+    Object.defineProperty(proto, propName, {
+      get(this: LitElement) { return queryFn(this.renderRoot!, selector); },
+      enumerable : true,
+      configurable : true,
+    });
+  };
+}

src/test/lib/decorators_test.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright (c) 2017 The Polymer Project Authors. All rights reserved.
+ * This code may only be used under the BSD style license found at
+ * http://polymer.github.io/LICENSE.txt
+ * The complete set of authors may be found at
+ * http://polymer.github.io/AUTHORS.txt
+ * The complete set of contributors may be found at
+ * http://polymer.github.io/CONTRIBUTORS.txt
+ * Code distributed by Google as part of the polymer project is also
+ * subject to an additional IP rights grant found at
+ * http://polymer.github.io/PATENTS.txt
+ */
+
+import {customElement, query, queryAll} from '../../lib/decorators.js';
+import {html, LitElement} from '../../lit-element.js';
+import { generateElementName } from '../test-helpers.js';
+
+const assert = chai.assert;
+
+suite('decorators', () => {
+  let container: HTMLElement;
+
+  setup(() => {
+    container = document.createElement('div');
+    container.id = 'test-container';
+    document.body.appendChild(container);
+  });
+
+  teardown(() => {
+    if (container !== undefined) {
+      container.parentElement!.removeChild(container);
+      (container as any) = undefined;
+    }
+  });
+
+  suite('@customElement', () => {
+    test('defines an element', () => {
+      const tagName = generateElementName();
+      @customElement(tagName as keyof HTMLElementTagNameMap)
+      class C0 extends HTMLElement {
+      }
+      const DefinedC = customElements.get(tagName);
+      assert.strictEqual(DefinedC, C0);
+    });
+  });
+
+  suite('@query', () => {
+    @customElement(generateElementName() as keyof HTMLElementTagNameMap)
+    class C extends LitElement {
+
+      @query('#blah') blah?: HTMLDivElement;
+
+      @query('span') nope?: HTMLSpanElement;
+
+      render() {
+        return html`
+          <div>Not this one</div>
+          <div id="blah">This one</div>
+        `;
+      }
+    }
+
+    test('returns an element when it exists', async () => {
+      const c = new C();
+      container.appendChild(c);
+      await c.updateComplete;
+      const div = c.blah;
+      assert.instanceOf(div, HTMLDivElement);
+      assert.equal(div!.innerText, 'This one');
+    });
+
+    test('returns null when no match', async () => {
+      const c = new C();
+      container.appendChild(c);
+      await Promise.resolve();
+      const span = c.nope;
+      assert.isNull(span);
+    });
+  });
+
+  suite('@queryAll', () => {
+    @customElement(generateElementName() as keyof HTMLElementTagNameMap)
+    class C extends LitElement {
+
+      @queryAll('div') divs!: NodeList;
+
+      @queryAll('span') spans!: NodeList;
+
+      render() {
+        return html`
+          <div>Not this one</div>
+          <div id="blah">This one</div>
+        `;
+      }
+    }
+
+    test('returns elements when they exists', async () => {
+      const c = new C();
+      container.appendChild(c);
+      await c.updateComplete;
+      const divs = c.divs!;
+      // This is not true in ShadyDOM:
+      // assert.instanceOf(divs, NodeList);
+      assert.lengthOf(divs, 2);
+    });
+
+    test('returns empty NodeList when no match', async () => {
+      const c = new C();
+      container.appendChild(c);
+      await c.updateComplete;
+      const spans = c.spans;
+      // This is not true in ShadyDOM:
+      // assert.instanceOf(divs, NodeList);
+      assert.lengthOf(spans, 0);
+    });
+  });
+});

test/runner.html

@@ -16,4 +16,5 @@
 <body>
   <script type="module" src="lit-element_test.js"></script>
   <script type="module" src="lit-element_styling_test.js"></script>
+  <script type="module" src="lib/decorators_test.js"></script>
 </body></html>