@norith/glimmer-component 1.0.0

package/README.md

@@ -0,0 +1,42 @@
+# @glimmer/component
+
+[![npm version](https://badge.fury.io/js/%40glimmer%2Fcomponent.svg)](https://badge.fury.io/js/%40glimmer%2Fcomponent)
+[![CI](https://github.com/glimmerjs/glimmer.js/workflows/CI/badge.svg)](https://github.com/glimmerjs/glimmer.js/actions?query=workflow%3ACI)
+
+## Installation
+
+Add this package to your project with Yarn:
+
+```bash
+yarn add @glimmer/component
+```
+
+Or alternatively with npm:
+
+```bash
+npm install --save-dev @glimmer/component
+```
+
+## Usage
+
+To use this in a Glimmer application, import the package and export an extended class:
+
+```ts
+import Component from '@glimmer/component';
+
+export default class MyComponent extends Component {
+}
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/glimmerjs/glimmer.js.
+
+## Acknowledgements
+
+Thanks to [Monegraph](http://monegraph.com) for funding the initial development
+of this library.
+
+## License
+
+MIT License.

package/addon/-private/base-component-manager.ts

@@ -0,0 +1,35 @@
+import { DEBUG } from '@glimmer/env';
+import { ComponentManager, ComponentCapabilities } from '@norith/glimmer-core';
+import { Arguments } from '@glimmer/interfaces';
+import BaseComponent, { ARGS_SET } from './component';
+
+export interface Constructor<T> {
+  new (owner: unknown, args: Record<string, unknown>): T;
+}
+
+export default abstract class BaseComponentManager<GlimmerComponent extends BaseComponent>
+  implements ComponentManager<GlimmerComponent>
+{
+  abstract capabilities: ComponentCapabilities;
+
+  private owner: unknown;
+
+  constructor(owner: unknown) {
+    this.owner = owner;
+  }
+
+  createComponent(
+    ComponentClass: Constructor<GlimmerComponent>,
+    args: Arguments
+  ): GlimmerComponent {
+    if (DEBUG) {
+      ARGS_SET.set(args.named, true);
+    }
+
+    return new ComponentClass(this.owner, args.named);
+  }
+
+  getContext(component: GlimmerComponent): GlimmerComponent {
+    return component;
+  }
+}

package/addon/-private/component.ts

@@ -0,0 +1,287 @@
+import { DEBUG } from '@glimmer/env';
+
+const DESTROYING = new WeakMap<GlimmerComponent<object>, boolean>();
+const DESTROYED = new WeakMap<GlimmerComponent<object>, boolean>();
+
+export function setDestroying(component: GlimmerComponent<object>): void {
+  DESTROYING.set(component, true);
+}
+export function setDestroyed(component: GlimmerComponent<object>): void {
+  DESTROYED.set(component, true);
+}
+
+// This provides a type-safe `WeakMap`: the getter and setter link the key to a
+// specific value. This is how `WeakMap`s actually behave, but the TS type
+// system does not (yet!) have a good way to capture that for types like
+// `WeakMap` where the type is generic over another generic type (here, `Args`).
+interface ArgsSetMap extends WeakMap<Args<unknown>, boolean> {
+  get<S>(key: Args<S>): boolean | undefined;
+  set<S>(key: Args<S>, value: boolean): this;
+  has<S>(key: Args<S>): boolean;
+}
+
+// SAFETY: this only holds because we *only* acces this when `DEBUG` is `true`.
+// There is not a great way to connect that data in TS at present.
+export let ARGS_SET: ArgsSetMap;
+
+if (DEBUG) {
+  ARGS_SET = new WeakMap() as ArgsSetMap;
+}
+
+// --- Type utilities for component signatures --- //
+// Type-only "symbol" to use with `EmptyObject` below, so that it is *not*
+// equivalent to an empty interface.
+declare const Empty: unique symbol;
+
+/**
+ * This provides us a way to have a "fallback" which represents an empty object,
+ * without the downsides of how TS treats `{}`. Specifically: this will
+ * correctly leverage "excess property checking" so that, given a component
+ * which has no named args, if someone invokes it with any named args, they will
+ * get a type error.
+ *
+ * @internal This is exported so declaration emit works (if it were not emitted,
+ *   declarations which fall back to it would not work). It is *not* intended for
+ *   public usage, and the specific mechanics it uses may change at any time.
+ *   The location of this export *is* part of the public API, because moving it
+ *   will break existing declarations, but is not legal for end users to import
+ *   themselves, so ***DO NOT RELY ON IT***.
+ */
+export type EmptyObject = { [Empty]?: true };
+
+type GetOrElse<Obj, K extends PropertyKey, Fallback> = Obj extends { [Key in K]: infer U }
+  ? U
+  : Fallback;
+
+/** Given a signature `S`, get back the `Args` type. */
+type ArgsFor<S> = S extends { Args: infer Args }
+  ? Args extends { Named?: object; Positional?: unknown[] } // Are they longhand already?
+    ? {
+        Named: GetOrElse<S['Args'], 'Named', EmptyObject>;
+        Positional: GetOrElse<S['Args'], 'Positional', []>;
+      }
+    : { Named: S['Args']; Positional: [] }
+  : { Named: EmptyObject; Positional: [] };
+
+type _ExpandSignature<T> = {
+  Element: GetOrElse<T, 'Element', null>;
+  Args: keyof T extends 'Args' | 'Element' | 'Blocks' // Is this a `Signature`?
+    ? ArgsFor<T> // Then use `Signature` args
+    : { Named: T; Positional: [] }; // Otherwise fall back to classic `Args`.
+  Blocks: T extends { Blocks: infer Blocks }
+    ? {
+        [Block in keyof Blocks]: Blocks[Block] extends unknown[]
+          ? { Params: { Positional: Blocks[Block] } }
+          : Blocks[Block];
+      }
+    : EmptyObject;
+};
+/**
+ * Given any allowed shorthand form of a signature, desugars it to its full
+ * expanded type.
+ *
+ * @internal This is only exported so we can avoid duplicating it in
+ *   [Glint](https://github.com/typed-ember/glint) or other such tooling. It is
+ *   *not* intended for public usage, and the specific mechanics it uses may
+ *   change at any time. Although the signature produced by is part of Glimmer's
+ *   public API the existence and mechanics of this specific symbol are *not*,
+ *   so ***DO NOT RELY ON IT***.
+ */
+// The conditional type here is because TS applies conditional types
+// distributively. This means that for union types, checks like `keyof T` get
+// all the keys from all elements of the union, instead of ending up as `never`
+// and then always falling into the `Signature` path instead of falling back to
+// the legacy args handling path.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ExpandSignature<T> = T extends any ? _ExpandSignature<T> : never;
+
+/**
+ * @internal we use this type for convenience internally; inference means users
+ *   should not normally need to name it
+ */
+export type Args<S> = ExpandSignature<S>['Args']['Named'];
+
+/**
+ * The `Component` class defines an encapsulated UI element that is rendered to
+ * the DOM. A component is made up of a template and, optionally, this component
+ * object.
+ *
+ * ## Defining a Component
+ *
+ * To define a component, subclass `Component` and add your own properties,
+ * methods and lifecycle hooks:
+ *
+ * ```ts
+ * import Component from '@norith/glimmer-component';
+ *
+ * export default class extends Component {
+ * }
+ * ```
+ *
+ * ## Lifecycle Hooks
+ *
+ * Lifecycle hooks allow you to respond to changes to a component, such as when
+ * it gets created, rendered, updated or destroyed. To add a lifecycle hook to a
+ * component, implement the hook as a method on your component subclass.
+ *
+ * For example, to be notified when Glimmer has rendered your component so you
+ * can attach a legacy jQuery plugin, implement the `didInsertElement()` method:
+ *
+ * ```ts
+ * import Component from '@norith/glimmer-component';
+ *
+ * export default class extends Component {
+ *   didInsertElement() {
+ *     $(this.element).pickadate();
+ *   }
+ * }
+ * ```
+ *
+ * ## Data for Templates
+ *
+ * `Component`s have two different kinds of data, or state, that can be
+ * displayed in templates:
+ *
+ * 1. Arguments
+ * 2. Properties
+ *
+ * Arguments are data that is passed in to a component from its parent
+ * component. For example, if I have a `UserGreeting` component, I can pass it
+ * a name and greeting to use:
+ *
+ * ```hbs
+ * <UserGreeting @name="Ricardo" @greeting="Olá" />
+ * ```
+ *
+ * Inside my `UserGreeting` template, I can access the `@name` and `@greeting`
+ * arguments that I've been given:
+ *
+ * ```hbs
+ * {{@greeting}}, {{@name}}!
+ * ```
+ *
+ * Arguments are also available inside my component:
+ *
+ * ```ts
+ * console.log(this.args.greeting); // prints "Olá"
+ * ```
+ *
+ * Properties, on the other hand, are internal to the component and declared in
+ * the class. You can use properties to store data that you want to show in the
+ * template, or pass to another component as an argument.
+ *
+ * ```ts
+ * import Component from '@norith/glimmer-component';
+ *
+ * export default class extends Component {
+ *   user = {
+ *     name: 'Robbie'
+ *   }
+ * }
+ * ```
+ *
+ * In the above example, we've defined a component with a `user` property that
+ * contains an object with its own `name` property.
+ *
+ * We can render that property in our template:
+ *
+ * ```hbs
+ * Hello, {{user.name}}!
+ * ```
+ *
+ * We can also take that property and pass it as an argument to the
+ * `UserGreeting` component we defined above:
+ *
+ * ```hbs
+ * <UserGreeting @greeting="Hello" @name={{user.name}} />
+ * ```
+ *
+ * ## Arguments vs. Properties
+ *
+ * Remember, arguments are data that was given to your component by its parent
+ * component, and properties are data your component has defined for itself.
+ *
+ * You can tell the difference between arguments and properties in templates
+ * because arguments always start with an `@` sign (think "A is for arguments"):
+ *
+ * ```hbs
+ * {{@firstName}}
+ * ```
+ *
+ * We know that `@firstName` came from the parent component, not the current
+ * component, because it starts with `@` and is therefore an argument.
+ *
+ * On the other hand, if we see:
+ *
+ * ```hbs
+ * {{name}}
+ * ```
+ *
+ * We know that `name` is a property on the component. If we want to know where
+ * the data is coming from, we can go look at our component class to find out.
+ *
+ * Inside the component itself, arguments always show up inside the component's
+ * `args` property. For example, if `{{@firstName}}` is `Tom` in the template,
+ * inside the component `this.args.firstName` would also be `Tom`.
+ */
+export default class GlimmerComponent<S = unknown> {
+  /**
+   * Constructs a new component and assigns itself the passed properties. You
+   * should not construct new components yourself. Instead, Glimmer will
+   * instantiate new components automatically as it renders.
+   *
+   * @param owner
+   * @param args
+   */
+  constructor(owner: unknown, args: Args<S>) {
+    if (DEBUG && !(owner !== null && typeof owner === 'object' && ARGS_SET.has(args))) {
+      throw new Error(
+        `You must pass both the owner and args to super() in your component: ${this.constructor.name}. You can pass them directly, or use ...arguments to pass all arguments through.`
+      );
+    }
+
+    this.args = args;
+
+    DESTROYING.set(this, false);
+    DESTROYED.set(this, false);
+  }
+
+  /**
+   * Named arguments passed to the component from its parent component.
+   * They can be accessed in JavaScript via `this.args.argumentName` and in the template via `@argumentName`.
+   *
+   * Say you have the following component, which will have two `args`, `firstName` and `lastName`:
+   *
+   * ```hbs
+   * <my-component @firstName="Arthur" @lastName="Dent" />
+   * ```
+   *
+   * If you needed to calculate `fullName` by combining both of them, you would do:
+   *
+   * ```ts
+   * didInsertElement() {
+   *   console.log(`Hi, my full name is ${this.args.firstName} ${this.args.lastName}`);
+   * }
+   * ```
+   *
+   * While in the template you could do:
+   *
+   * ```hbs
+   * <p>Welcome, {{@firstName}} {{@lastName}}!</p>
+   * ```
+   */
+  readonly args: Readonly<Args<S>>;
+
+  get isDestroying(): boolean {
+    return DESTROYING.get(this) || false;
+  }
+
+  get isDestroyed(): boolean {
+    return DESTROYED.get(this) || false;
+  }
+
+  /**
+   * Called before the component has been removed from the DOM.
+   */
+  willDestroy(): void {} // eslint-disable-line @typescript-eslint/no-empty-function
+}

package/addon/-private/ember-component-manager.ts

@@ -0,0 +1,99 @@
+import { DEBUG } from '@glimmer/env';
+import { set } from '@ember/object';
+import { destroy } from '@ember/destroyable';
+import { capabilities } from '@ember/component';
+import { schedule } from '@ember/runloop';
+import { gte } from 'ember-compatibility-helpers';
+import BaseComponentManager from './base-component-manager';
+
+import GlimmerComponent, { setDestroyed, setDestroying } from './component';
+import { ComponentCapabilities } from '@norith/glimmer-core';
+import { Arguments } from '@glimmer/interfaces';
+
+const CAPABILITIES = gte('3.13.0-beta.1')
+  ? capabilities('3.13', {
+      destructor: true,
+      asyncLifeCycleCallbacks: false,
+      updateHook: false,
+    })
+  : capabilities('3.4', {
+      destructor: true,
+      asyncLifeCycleCallbacks: false,
+    });
+
+function scheduledDestroyComponent(component: GlimmerComponent): void {
+  if (component.isDestroyed) {
+    return;
+  }
+
+  destroy(component);
+  setDestroyed(component);
+}
+
+/**
+ * This component manager runs in Ember.js environments and extends the base component manager to:
+ *
+ * 1. Properly destroy the component's associated `meta` data structure
+ * 2. Schedule destruction using Ember's runloop
+ */
+class EmberGlimmerComponentManager extends BaseComponentManager<GlimmerComponent> {
+  capabilities = CAPABILITIES;
+
+  destroyComponent(component: GlimmerComponent): void {
+    if (component.isDestroying) {
+      return;
+    }
+
+    setDestroying(component);
+
+    schedule('actions', component, component.willDestroy);
+    schedule('destroy', this, scheduledDestroyComponent, component);
+  }
+}
+
+interface EmberGlimmerComponentManager {
+  updateComponent?: (component: GlimmerComponent, args: Arguments) => void;
+}
+
+// In Ember 3.12 and earlier, the updateComponent hook was mandatory.
+// As of Ember 3.13, the `args` object is stable and each property of the
+// object participates in the autotrack stack on its own. This means we do not
+// need to set the `args` property on the component instance to invalidate
+// tracked getters that rely on `args`, and therefore don't require the `updateComponent`
+// hook at all.
+if (!gte('3.13.0-beta.1')) {
+  EmberGlimmerComponentManager.prototype.updateComponent = function updateComponent(
+    component: GlimmerComponent,
+    args: Arguments
+  ): void {
+    let argSnapshot = args.named;
+
+    if (DEBUG) {
+      argSnapshot = Object.freeze(argSnapshot);
+    }
+
+    set(component, 'args', argSnapshot);
+  };
+}
+
+export default EmberGlimmerComponentManager;
+
+interface EmberMeta {
+  setSourceDestroying(): void;
+  setSourceDestroyed(): void;
+}
+
+declare module 'ember' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  export namespace Ember {
+    function destroy(obj: {}): void;
+    function meta(obj: {}): EmberMeta;
+  }
+}
+
+declare module '@ember/component' {
+  export function capabilities(
+    version: '3.13' | '3.4',
+    capabilities: Partial<ComponentCapabilities>
+  ): ComponentCapabilities;
+}

package/addon/index.ts

@@ -0,0 +1,34 @@
+import { DEBUG } from '@glimmer/env';
+import ApplicationInstance from '@ember/application/instance';
+
+// Hax because Ember does not have types for `setComponentManager`
+declare module '@ember/component' {
+  export function setComponentManager<T extends object>(
+    factory: (owner: ApplicationInstance) => GlimmerComponentManager,
+    componentClass: T
+  ): T;
+}
+
+import { setComponentManager } from '@ember/component';
+
+import GlimmerComponentManager from './-private/ember-component-manager';
+import _GlimmerComponent, { Args } from './-private/component';
+import { setOwner } from '@ember/application';
+
+export default class GlimmerComponent<S = unknown> extends _GlimmerComponent<S> {
+  constructor(owner: object, args: Args<S>) {
+    super(owner, args);
+
+    if (DEBUG && !(owner !== null && typeof owner === 'object')) {
+      throw new Error(
+        `You must pass both the owner and args to super() in your component: ${this.constructor.name}. You can pass them directly, or use ...arguments to pass all arguments through.`
+      );
+    }
+
+    setOwner(this, owner);
+  }
+}
+
+setComponentManager((owner: ApplicationInstance) => {
+  return new GlimmerComponentManager(owner);
+}, GlimmerComponent);

package/config/environment.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = function (/* environment, appConfig */) {
+  return {};
+};

package/dist/commonjs/addon/-private/base-component-manager.d.ts

@@ -0,0 +1,13 @@
+import { ComponentManager, ComponentCapabilities } from '@norith/glimmer-core';
+import { Arguments } from '@glimmer/interfaces';
+import BaseComponent from './component';
+export interface Constructor<T> {
+    new (owner: unknown, args: Record<string, unknown>): T;
+}
+export default abstract class BaseComponentManager<GlimmerComponent extends BaseComponent> implements ComponentManager<GlimmerComponent> {
+    abstract capabilities: ComponentCapabilities;
+    private owner;
+    constructor(owner: unknown);
+    createComponent(ComponentClass: Constructor<GlimmerComponent>, args: Arguments): GlimmerComponent;
+    getContext(component: GlimmerComponent): GlimmerComponent;
+}

package/dist/commonjs/addon/-private/base-component-manager.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const env_1 = require("@glimmer/env");
+const component_1 = require("./component");
+class BaseComponentManager {
+    constructor(owner) {
+        this.owner = owner;
+    }
+    createComponent(ComponentClass, args) {
+        if (env_1.DEBUG) {
+            component_1.ARGS_SET.set(args.named, true);
+        }
+        return new ComponentClass(this.owner, args.named);
+    }
+    getContext(component) {
+        return component;
+    }
+}
+exports.default = BaseComponentManager;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZS1jb21wb25lbnQtbWFuYWdlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uLy4uL3BhY2thZ2VzL0BnbGltbWVyL2NvbXBvbmVudC9hZGRvbi8tcHJpdmF0ZS9iYXNlLWNvbXBvbmVudC1tYW5hZ2VyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7O0FBQUEsc0NBQXFDO0FBR3JDLDJDQUFzRDtBQU10RCxNQUE4QixvQkFBb0I7SUFPaEQsWUFBWSxLQUFjO1FBQ3hCLElBQUksQ0FBQyxLQUFLLEdBQUcsS0FBSyxDQUFDO0lBQ3JCLENBQUM7SUFFRCxlQUFlLENBQ2IsY0FBNkMsRUFDN0MsSUFBZTtRQUVmLElBQUksV0FBSyxFQUFFO1lBQ1Qsb0JBQVEsQ0FBQyxHQUFHLENBQUMsSUFBSSxDQUFDLEtBQUssRUFBRSxJQUFJLENBQUMsQ0FBQztTQUNoQztRQUVELE9BQU8sSUFBSSxjQUFjLENBQUMsSUFBSSxDQUFDLEtBQUssRUFBRSxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUM7SUFDcEQsQ0FBQztJQUVELFVBQVUsQ0FBQyxTQUEyQjtRQUNwQyxPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDO0NBQ0Y7QUF6QkQsdUNBeUJDIiwic291cmNlc0NvbnRlbnQiOlsiaW1wb3J0IHsgREVCVUcgfSBmcm9tICdAZ2xpbW1lci9lbnYnO1xuaW1wb3J0IHsgQ29tcG9uZW50TWFuYWdlciwgQ29tcG9uZW50Q2FwYWJpbGl0aWVzIH0gZnJvbSAnQG5vcml0aC9nbGltbWVyLWNvcmUnO1xuaW1wb3J0IHsgQXJndW1lbnRzIH0gZnJvbSAnQGdsaW1tZXIvaW50ZXJmYWNlcyc7XG5pbXBvcnQgQmFzZUNvbXBvbmVudCwgeyBBUkdTX1NFVCB9IGZyb20gJy4vY29tcG9uZW50JztcblxuZXhwb3J0IGludGVyZmFjZSBDb25zdHJ1Y3RvcjxUPiB7XG4gIG5ldyAob3duZXI6IHVua25vd24sIGFyZ3M6IFJlY29yZDxzdHJpbmcsIHVua25vd24+KTogVDtcbn1cblxuZXhwb3J0IGRlZmF1bHQgYWJzdHJhY3QgY2xhc3MgQmFzZUNvbXBvbmVudE1hbmFnZXI8R2xpbW1lckNvbXBvbmVudCBleHRlbmRzIEJhc2VDb21wb25lbnQ+XG4gIGltcGxlbWVudHMgQ29tcG9uZW50TWFuYWdlcjxHbGltbWVyQ29tcG9uZW50Plxue1xuICBhYnN0cmFjdCBjYXBhYmlsaXRpZXM6IENvbXBvbmVudENhcGFiaWxpdGllcztcblxuICBwcml2YXRlIG93bmVyOiB1bmtub3duO1xuXG4gIGNvbnN0cnVjdG9yKG93bmVyOiB1bmtub3duKSB7XG4gICAgdGhpcy5vd25lciA9IG93bmVyO1xuICB9XG5cbiAgY3JlYXRlQ29tcG9uZW50KFxuICAgIENvbXBvbmVudENsYXNzOiBDb25zdHJ1Y3RvcjxHbGltbWVyQ29tcG9uZW50PixcbiAgICBhcmdzOiBBcmd1bWVudHNcbiAgKTogR2xpbW1lckNvbXBvbmVudCB7XG4gICAgaWYgKERFQlVHKSB7XG4gICAgICBBUkdTX1NFVC5zZXQoYXJncy5uYW1lZCwgdHJ1ZSk7XG4gICAgfVxuXG4gICAgcmV0dXJuIG5ldyBDb21wb25lbnRDbGFzcyh0aGlzLm93bmVyLCBhcmdzLm5hbWVkKTtcbiAgfVxuXG4gIGdldENvbnRleHQoY29tcG9uZW50OiBHbGltbWVyQ29tcG9uZW50KTogR2xpbW1lckNvbXBvbmVudCB7XG4gICAgcmV0dXJuIGNvbXBvbmVudDtcbiAgfVxufVxuIl19