ember-source 4.10.0-beta.2 → 4.11.0-alpha.2

package/types/stable/@ember/-internals/glimmer/lib/components/abstract-input.d.ts

@@ -0,0 +1,37 @@
+declare module '@ember/-internals/glimmer/lib/components/abstract-input.d.ts' {
+  import type { Reference } from '@glimmer/reference';
+  import type { EventListener } from './internal';
+  import InternalComponent from './internal';
+  type VirtualEventListener = (value: string, event: Event) => void;
+  export function valueFrom(reference?: Reference<unknown>): Value;
+  interface Value {
+      get(): unknown;
+      set(value: unknown): void;
+  }
+  export default abstract class AbstractInput extends InternalComponent {
+      validateArguments(): void;
+      private _value;
+      get value(): unknown;
+      set value(value: unknown);
+      valueDidChange(event: Event): void;
+      /**
+       * The `change` and `input` actions need to be overridden in the `Input`
+       * subclass. Unfortunately, some ember-source builds currently uses babel
+       * loose mode to transpile its classes. Having the `@action` decorator on the
+       * super class creates a getter on the prototype, and when the subclass
+       * overrides the method, the loose mode transpilation would emit something
+       * like `Subclass.prototype['change'] = function change() { ... }`, which
+       * fails because `prototype['change']` is getter-only/readonly. The correct
+       * solution is to use `Object.defineProperty(prototype, 'change', ...)` but
+       * that requires disabling loose mode. For now, the workaround is to add the
+       * decorator only on the subclass. This is more of a configuration issue on
+       * our own builds and doesn't really affect apps.
+       */
+      change(event: Event): void;
+      input(event: Event): void;
+      keyUp(event: KeyboardEvent): void;
+      protected listenerFor(name: string): EventListener;
+      protected isVirtualEventListener(name: string, _listener: Function): _listener is VirtualEventListener;
+  }
+  export {};
+}

package/types/stable/@ember/-internals/glimmer/lib/components/input.d.ts

@@ -0,0 +1,4 @@
+declare module '@ember/-internals/glimmer/lib/components/input.d.ts' {
+  const _default: import("./internal").OpaqueInternalComponentConstructor;
+  export default _default;
+}

package/types/stable/@ember/-internals/glimmer/lib/components/internal.d.ts

@@ -0,0 +1,48 @@
+declare module '@ember/-internals/glimmer/lib/components/internal.d.ts' {
+  import type { InternalOwner } from '@ember/-internals/owner';
+  import type { CapturedArguments, TemplateFactory } from '@glimmer/interfaces';
+  export type EventListener = (event: Event) => void;
+  export default class InternalComponent {
+      protected owner: InternalOwner;
+      protected readonly args: CapturedArguments;
+      protected readonly caller: unknown;
+      static toString(): string;
+      constructor(owner: InternalOwner, args: CapturedArguments, caller: unknown);
+      /**
+       * The default HTML id attribute. We don't really _need_ one, this is just
+       * added for compatibility as it's hard to tell if people rely on it being
+       * present, and it doens't really hurt.
+       *
+       * However, don't rely on this internally, like passing it to `getElementId`.
+       * This can be (and often is) overriden by passing an `id` attribute on the
+       * invocation, which shadows this default id via `...attributes`.
+       */
+      get id(): string;
+      /**
+       * The default HTML class attribute. Similar to the above, we don't _need_
+       * them, they are just added for compatibility as it's similarly hard to tell
+       * if people rely on it in their CSS etc, and it doens't really hurt.
+       */
+      get class(): string;
+      protected validateArguments(): void;
+      protected named(name: string): unknown;
+      protected positional(index: number): unknown;
+      protected listenerFor(name: string): EventListener;
+      protected isSupportedArgument(_name: string): boolean;
+      protected onUnsupportedArgument(_name: string): void;
+      toString(): string;
+  }
+  export interface InternalComponentConstructor<T extends InternalComponent = InternalComponent> {
+      new (owner: InternalOwner, args: CapturedArguments, caller: unknown): T;
+      prototype: T;
+      toString(): string;
+  }
+  const OPAQUE_INTERNAL_COMPONENT_CONSTRUCTOR: unique symbol;
+  export interface OpaqueInternalComponentConstructor {
+      create(): never;
+      toString(): string;
+      [OPAQUE_INTERNAL_COMPONENT_CONSTRUCTOR]: true;
+  }
+  export function opaquify(constructor: InternalComponentConstructor, template: TemplateFactory): OpaqueInternalComponentConstructor;
+  export {};
+}

package/types/stable/@ember/-internals/glimmer/lib/components/link-to.d.ts

@@ -0,0 +1,4 @@
+declare module '@ember/-internals/glimmer/lib/components/link-to.d.ts' {
+  const _default: import("./internal").OpaqueInternalComponentConstructor;
+  export default _default;
+}

package/types/stable/@ember/-internals/glimmer/lib/components/textarea.d.ts

@@ -0,0 +1,4 @@
+declare module '@ember/-internals/glimmer/lib/components/textarea.d.ts' {
+  const _default: import("./internal").OpaqueInternalComponentConstructor;
+  export default _default;
+}

package/types/stable/@ember/-internals/glimmer/lib/dom.d.ts

@@ -0,0 +1,4 @@
+declare module '@ember/-internals/glimmer/lib/dom.d.ts' {
+  export { DOMChanges, DOMTreeConstruction, clientBuilder, rehydrationBuilder, } from '@glimmer/runtime';
+  export { NodeDOMTreeConstruction, serializeBuilder } from '@glimmer/node';
+}

package/types/stable/@ember/-internals/glimmer/lib/environment.d.ts

@@ -0,0 +1,11 @@
+declare module '@ember/-internals/glimmer/lib/environment.d.ts' {
+  import type { InternalOwner } from '@ember/-internals/owner';
+  import type { EnvironmentDelegate } from '@glimmer/runtime';
+  export class EmberEnvironmentDelegate implements EnvironmentDelegate {
+      owner: InternalOwner;
+      isInteractive: boolean;
+      enableDebugTooling: boolean;
+      constructor(owner: InternalOwner, isInteractive: boolean);
+      onTransactionCommit(): void;
+  }
+}

package/types/stable/@ember/-internals/glimmer/lib/glimmer-component-docs.d.ts

@@ -0,0 +1,387 @@
+declare module '@ember/-internals/glimmer/lib/glimmer-component-docs.d.ts' {
+  /**
+    A component is a reusable UI element that consists of a `.hbs` template and an
+    optional JavaScript class that defines its behavior. For example, someone
+    might make a `button` in the template and handle the click behavior in the
+    JavaScript file that shares the same name as the template.
+
+    Components are broken down into two categories:
+
+    - Components _without_ JavaScript, that are based only on a template. These
+      are called Template-only or TO components.
+    - Components _with_ JavaScript, which consist of a template and a backing
+      class.
+
+    Ember ships with two types of JavaScript classes for components:
+
+    1. Glimmer components, imported from `@glimmer/component`, which are the
+       default components for Ember Octane (3.15) and more recent editions.
+    2. Classic components, imported from `@ember/component`, which were the
+       default for older editions of Ember (pre 3.15).
+
+    Below is the documentation for Template-only and Glimmer components. If you
+    are looking for the API documentation for Classic components, it is
+    [available here](/ember/release/classes/Component). The source code for
+    Glimmer components can be found in [`@glimmer/component`](https://github.com/glimmerjs/glimmer.js/tree/master/packages/%40glimmer/component).
+
+    ## Defining a Template-only Component
+
+    The simplest way to create a component is to create a template file in
+    `app/templates/components`. For example, if you name a template
+    `app/templates/components/person-profile.hbs`:
+
+    ```app/templates/components/person-profile.hbs
+    <h1>{{@person.name}}</h1>
+    <img src={{@person.avatar}}>
+    <p class='signature'>{{@person.signature}}</p>
+    ```
+
+    You will be able to use `<PersonProfile />` to invoke this component elsewhere
+    in your application:
+
+    ```app/templates/application.hbs
+    <PersonProfile @person={{this.currentUser}} />
+    ```
+
+    Note that component names are capitalized here in order to distinguish them
+    from regular HTML elements, but they are dasherized in the file system.
+
+    While the angle bracket invocation form is generally preferred, it is also
+    possible to invoke the same component with the `{{person-profile}}` syntax:
+
+    ```app/templates/application.hbs
+    {{person-profile person=this.currentUser}}
+    ```
+
+    Note that with this syntax, you use dashes in the component name and
+    arguments are passed without the `@` sign.
+
+    In both cases, Ember will render the content of the component template we
+    created above. The end result will be something like this:
+
+    ```html
+    <h1>Tomster</h1>
+    <img src="https://emberjs.com/tomster.jpg">
+    <p class='signature'>Out of office this week</p>
+    ```
+
+    ## File System Nesting
+
+    Components can be nested inside sub-folders for logical groupping. For
+    example, if we placed our template in
+    `app/templates/components/person/short-profile.hbs`, we can invoke it as
+    `<Person::ShortProfile />`:
+
+    ```app/templates/application.hbs
+    <Person::ShortProfile @person={{this.currentUser}} />
+    ```
+
+    Or equivalently, `{{person/short-profile}}`:
+
+    ```app/templates/application.hbs
+    {{person/short-profile person=this.currentUser}}
+    ```
+
+    ## Using Blocks
+
+    You can use `yield` inside a template to include the **contents** of any block
+    attached to the component. For instance, if we added a `{{yield}}` to our
+    component like so:
+
+    ```app/templates/components/person-profile.hbs
+    <h1>{{@person.name}}</h1>
+    {{yield}}
+    ```
+
+    We could then invoke it like this:
+
+    ```handlebars
+    <PersonProfile @person={{this.currentUser}}>
+      <p>Admin mode</p>
+    </PersonProfile>
+    ```
+
+    or with curly syntax like this:
+
+    ```handlebars
+    {{#person-profile person=this.currentUser}}
+      <p>Admin mode</p>
+    {{/person-profile}}
+    ```
+
+    And the content passed in between the brackets of the component would be
+    rendered in the same place as the `{{yield}}` within it, replacing it.
+
+    Blocks are executed in their original context, meaning they have access to the
+    scope and any in-scope variables where they were defined.
+
+    ### Passing parameters to blocks
+
+    You can also pass positional parameters to `{{yield}}`, which are then made
+    available in the block:
+
+    ```app/templates/components/person-profile.hbs
+    <h1>{{@person.name}}</h1>
+    {{yield @person.signature}}
+    ```
+
+    We can then use this value in the block like so:
+
+    ```handlebars
+    <PersonProfile @person={{this.currentUser}} as |signature|>
+      {{signature}}
+    </PersonProfile>
+    ```
+
+    ### Passing multiple blocks
+
+    You can pass multiple blocks to a component by giving them names, and
+    specifying which block you are yielding to with `{{yield}}`. For instance, if
+    we wanted to add a way for users to customize the title of our
+    `<PersonProfile>` component, we could add a named block inside of the header:
+
+    ```app/templates/components/person-profile.hbs
+    <h1>{{yield to="title"}}</h1>
+    {{yield}}
+    ```
+
+    This component could then be invoked like so:
+
+    ```handlebars
+    <PersonProfile @person={{this.currentUser}}>
+      <:title>{{this.currentUser.name}}</:title>
+      <:default>{{this.currentUser.signature}}</:default>
+    </PersonProfile>
+    ```
+
+    When passing named blocks, you must name every block, including the `default`
+    block, which is the block that is defined if you do not pass a `to` parameter
+    to `{{yield}}`. Whenever you invoke a component without passing explicitly
+    named blocks, the passed block is considered the `default` block.
+
+    ### Passing parameters to named blocks
+
+    You can also pass parameters to named blocks:
+
+    ```app/templates/components/person-profile.hbs
+    <h1>{{yield @person.name to="title"}}</h1>
+    {{yield @person.signature}}
+    ```
+
+    These parameters can then be used like so:
+
+    ```handlebars
+    <PersonProfile @person={{this.currentUser}}>
+      <:title as |name|>{{name}}</:title>
+      <:default as |signature|>{{signature}}</:default>
+    </PersonProfile>
+    ```
+
+    ### Checking to see if a block exists
+
+    You can also check to see if a block exists using the `(has-block)` keyword,
+    and conditionally use it, or provide a default template instead.
+
+    ```app/templates/components/person-profile.hbs
+    <h1>
+      {{#if (has-block "title")}}
+        {{yield @person.name to="title"}}
+      {{else}}
+        {{@person.name}}
+      {{/if}}
+    </h1>
+
+    {{#if (has-block)}}
+      {{yield @person.signature}}
+    {{else}}
+      {{@person.signature}}
+    {{/if}}
+    ```
+
+    With this template, we can then optionally pass in one block, both blocks, or
+    none at all:
+
+    ```handlebars
+    {{! passing both blocks }}
+    <PersonProfile @person={{this.currentUser}}>
+      <:title as |name|>{{name}}</:title>
+      <:default as |signature|>{{signature}}</:default>
+    </PersonProfile>
+
+    {{! passing just the title block }}
+    <PersonProfile @person={{this.currentUser}}>
+      <:title as |name|>{{name}}</:title>
+    </PersonProfile>
+
+    {{! passing just the default block }}
+    <PersonProfile @person={{this.currentUser}} as |signature|>
+      {{signature}}
+    </PersonProfile>
+
+    {{! not passing any blocks }}
+    <PersonProfile @person={{this.currentUser}}/>
+    ```
+
+    ### Checking to see if a block has parameters
+
+    We can also check if a block receives parameters using the `(has-block-params)`
+    keyword, and conditionally yield different values if so.
+
+    ```app/templates/components/person-profile.hbs
+    {{#if (has-block-params)}}
+      {{yield @person.signature}}
+    {{else}}
+      {{yield}}
+    {{/if}}
+    ```
+
+    ## Customizing Components With JavaScript
+
+    To add JavaScript to a component, create a JavaScript file in the same
+    location as the template file, with the same name, and export a subclass
+    of `Component` as the default value. For example, to add Javascript to the
+    `PersonProfile` component which we defined above, we would create
+    `app/components/person-profile.js` and export our class as the default, like
+    so:
+
+    ```app/components/person-profile.js
+    import Component from '@glimmer/component';
+
+    export default class PersonProfileComponent extends Component {
+      get displayName() {
+        let { title, firstName, lastName } = this.args.person;
+
+        if (title) {
+          return `${title} ${lastName}`;
+        } else {
+          return `${firstName} ${lastName}`;
+        }
+      })
+    }
+    ```
+
+    You can add your own properties, methods, and lifecycle hooks to this
+    subclass to customize its behavior, and you can reference the instance of the
+    class in your template using `{{this}}`. For instance, we could access the
+    `displayName` property of our `PersonProfile` component instance in the
+    template like this:
+
+    ```app/templates/components/person-profile.hbs
+    <h1>{{this.displayName}}</h1>
+    {{yield}}
+    ```
+
+    ## `constructor`
+
+    params: `owner` object and `args` object
+
+    Constructs a new component and assigns itself the passed properties. The
+    constructor is run whenever a new instance of the component is created, and
+    can be used to setup the initial state of the component.
+
+    ```javascript
+    import Component from '@glimmer/component';
+
+    export default class SomeComponent extends Component {
+      constructor(owner, args) {
+        super(owner, args);
+
+        if (this.args.displayMode === 'list') {
+          this.items = [];
+        }
+      }
+    }
+    ```
+
+    Service injections and arguments are available in the constructor.
+
+    ```javascript
+    import Component from '@glimmer/component';
+    import { service } from '@ember/service';
+
+    export default class SomeComponent extends Component {
+      @service myAnimations;
+
+      constructor(owner, args) {
+        super(owner, args);
+
+        if (this.args.fadeIn === true) {
+          this.myAnimations.register(this, 'fade-in');
+        }
+      }
+    }
+    ```
+
+    ## `willDestroy`
+
+    `willDestroy` is called after the component has been removed from the DOM, but
+    before the component is fully destroyed. This lifecycle hook can be used to
+    cleanup the component and any related state.
+
+    ```javascript
+    import Component from '@glimmer/component';
+    import { service } from '@ember/service';
+
+    export default class SomeComponent extends Component {
+      @service myAnimations;
+
+      willDestroy() {
+        super.willDestroy(...arguments);
+
+        this.myAnimations.unregister(this);
+      }
+    }
+    ```
+
+    ## `args`
+
+    The `args` property of Glimmer components is an object that contains the
+    _arguments_ that are passed to the component. For instance, the
+    following component usage:
+
+    ```handlebars
+    <SomeComponent @fadeIn={{true}} />
+    ```
+
+    Would result in the following `args` object to be passed to the component:
+
+    ```javascript
+    { fadeIn: true }
+    ```
+
+    `args` can be accessed at any point in the component lifecycle, including
+    `constructor` and `willDestroy`. They are also automatically marked as tracked
+    properties, and they can be depended on as computed property dependencies:
+
+    ```javascript
+    import Component from '@glimmer/component';
+    import { computed } from '@ember/object';
+
+    export default class SomeComponent extends Component {
+
+      @computed('args.someValue')
+      get computedGetter() {
+        // updates whenever args.someValue updates
+        return this.args.someValue;
+      }
+
+      get standardGetter() {
+        // updates whenever args.anotherValue updates (Ember 3.13+)
+        return this.args.anotherValue;
+      }
+    }
+    ```
+
+    ## `isDestroying`
+
+    A boolean flag to tell if the component is in the process of destroying. This is set to
+    true before `willDestroy` is called.
+
+    ## `isDestroyed`
+    A boolean to tell if the component has been fully destroyed. This is set to true
+    after `willDestroy` is called.
+
+    @module @glimmer/component
+    @public
+  */
+}