ember-source 4.8.0-alpha.5 → 4.8.0-beta.2

package/types/preview/@ember/array/mutable.d.ts

@@ -0,0 +1,94 @@
+declare module '@ember/array/mutable' {
+  import Mixin from '@ember/object/mixin';
+  import MutableEnumerable from '@ember/array/-private/mutable-enumerable';
+  import EmberArray from '@ember/array';
+
+  type AnyArray<T> = EmberArray<T> | Array<T>;
+
+  /**
+   * This mixin defines the API for modifying array-like objects. These methods
+   * can be applied only to a collection that keeps its items in an ordered set.
+   * It builds upon the Array mixin and adds methods to modify the array.
+   * One concrete implementations of this class include ArrayProxy.
+   */
+  interface MutableArray<T> extends EmberArray<T>, MutableEnumerable {
+    /**
+     * __Required.__ You must implement this method to apply this mixin.
+     */
+    replace(idx: number, amt: number, objects: T[]): this;
+    /**
+     * Remove all elements from the array. This is useful if you
+     * want to reuse an existing array without having to recreate it.
+     */
+    clear(): this;
+    /**
+     * This will use the primitive `replace()` method to insert an object at the
+     * specified index.
+     */
+    insertAt(idx: number, object: T): this;
+    /**
+     * Remove an object at the specified index using the `replace()` primitive
+     * method. You can pass either a single index, or a start and a length.
+     */
+    removeAt(start: number, len?: number): this;
+    /**
+     * Push the object onto the end of the array. Works just like `push()` but it
+     * is KVO-compliant.
+     */
+    pushObject(obj: T): T;
+    /**
+     * Add the objects in the passed numerable to the end of the array. Defers
+     * notifying observers of the change until all objects are added.
+     */
+    pushObjects(objects: AnyArray<T>): this;
+    /**
+     * Pop object from array or nil if none are left. Works just like `pop()` but
+     * it is KVO-compliant.
+     */
+    popObject(): T;
+    /**
+     * Shift an object from start of array or nil if none are left. Works just
+     * like `shift()` but it is KVO-compliant.
+     */
+    shiftObject(): T;
+    /**
+     * Unshift an object to start of array. Works just like `unshift()` but it is
+     * KVO-compliant.
+     */
+    unshiftObject(obj: T): T;
+    /**
+     * Adds the named objects to the beginning of the array. Defers notifying
+     * observers until all objects have been added.
+     */
+    unshiftObjects(objects: AnyArray<T>): this;
+    /**
+     * Reverse objects in the array. Works just like `reverse()` but it is
+     * KVO-compliant.
+     */
+    reverseObjects(): this;
+    /**
+     * Replace all the receiver's content with content of the argument.
+     * If argument is an empty array receiver will be cleared.
+     */
+    setObjects(objects: AnyArray<T>): this;
+    /**
+     * __Required.__ You must implement this method to apply this mixin.
+     */
+    removeObject(object: T): T;
+    /**
+     * Removes each object in the passed array from the receiver.
+     */
+    removeObjects(objects: AnyArray<T>): this;
+    /**
+     * __Required.__ You must implement this method to apply this mixin.
+     */
+    addObject(object: T): T;
+    /**
+     * Adds each object in the passed enumerable to the receiver.
+     */
+    addObjects(objects: AnyArray<T>): this;
+  }
+
+  const MutableArray: Mixin;
+  export default MutableArray;
+}

package/types/preview/@ember/array/proxy.d.ts

@@ -0,0 +1,29 @@
+declare module '@ember/array/proxy' {
+  import Array from '@ember/array';
+  import type MutableArray from '@ember/array/mutable';
+  import EmberObject from '@ember/object';
+
+  /**
+   * An ArrayProxy wraps any other object that is a native or Ember `Array`
+   * (checked with [`Ember.isArray`](https://api.emberjs.com/ember/release/functions/@ember%2Farray/isArray)),
+   * forwarding all requests. This makes it very useful for a number of
+   * binding use cases or other cases where being able to swap out the
+   * underlying array is useful.
+   *
+   * NOTE: Attempting to mutate the underlying content of an object that
+   * is not a `MutableArray` (e.g. a native Javascript Array) may not
+   * behave as expected. [`Ember.A`](https://api.emberjs.com/ember/release/functions/@ember%2Farray/A)
+   * may be used in this case.
+   */
+  export default interface ArrayProxy<T> extends MutableArray<T> {}
+  export default class ArrayProxy<T> extends EmberObject {
+    content: T[] | Array<T>;
+
+    /**
+     * Should actually retrieve the object at the specified index from the
+     * content. You can override this method in subclasses to transform the
+     * content item to something new.
+     */
+    objectAtContent(idx: number): T | undefined;
+  }
+}

package/types/preview/@ember/array/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/component/-private/class-names-support.d.ts

@@ -0,0 +1,27 @@
+declare module '@ember/component/-private/class-names-support' {
+  import Mixin from '@ember/object/mixin';
+
+  interface ClassNamesSupport {
+    /**
+     * A list of properties of the view to apply as class names. If the property is a string value,
+     * the value of that string will be applied as a class name.
+     *
+     * If the value of the property is a Boolean, the name of that property is added as a dasherized
+     * class name.
+     *
+     * If you would prefer to use a custom value instead of the dasherized property name, you can
+     * pass a binding like this: `classNameBindings: ['isUrgent:urgent']`
+     *
+     * This list of properties is inherited from the component's superclasses as well.
+     */
+    classNameBindings: string[];
+    /**
+     * Standard CSS class names to apply to the view's outer element. This
+     * property automatically inherits any class names defined by the view's
+     * superclasses as well.
+     */
+    classNames: string[];
+  }
+  const ClassNamesSupport: Mixin;
+  export default ClassNamesSupport;
+}

package/types/preview/@ember/component/-private/core-view.d.ts

@@ -0,0 +1,14 @@
+declare module '@ember/component/-private/core-view' {
+  import EmberObject from '@ember/object';
+  import type Evented from '@ember/object/evented';
+  import type ActionHandler from '@ember/object/-private/action-handler';
+
+  /**
+   * Ember.CoreView is an abstract class that exists to give view-like behavior to both Ember's main
+   * view class Ember.Component and other classes that don't need the full functionality of Ember.Component.
+   *
+   * Unless you have specific needs for CoreView, you will use Ember.Component in your applications.
+   */
+  export default class CoreView extends EmberObject {}
+  export default interface CoreView extends Evented, ActionHandler {}
+}

package/types/preview/@ember/component/-private/glimmer-interfaces.d.ts

@@ -0,0 +1,45 @@
+declare module '@ember/component/-private/glimmer-interfaces' {
+  // NOTE: this is a bare-minimum subset of the definitions of the types in
+  // `@glimmer/interfaces`, supplied to make the public types in this package
+  // accurate.
+
+  // This is only present to "brand" the type, and it brands it in a way that
+  // matches [the implementation][1], which *also* uses it as a type-only brand.
+  //
+  // [1]: https://github.com/glimmerjs/glimmer-vm/blob/d6d776cf3797dafa923bcdad47e1897231ef6539/packages/%40glimmer/interfaces/lib/managers/capabilities.d.ts#L1
+  const CAPABILITIES: unique symbol;
+
+  export interface Capabilities {
+    [CAPABILITIES]: true;
+  }
+
+  export interface Arguments {
+    positional: readonly unknown[];
+    named: Record<string, unknown>;
+  }
+
+  export interface ComponentCapabilitiesVersions {
+    '3.4': {
+      asyncLifecycleCallbacks?: boolean;
+      destructor?: boolean;
+    };
+
+    '3.13': {
+      asyncLifecycleCallbacks?: boolean;
+      destructor?: boolean;
+      updateHook?: boolean;
+    };
+  }
+
+  export interface ComponentCapabilities extends Capabilities {
+    asyncLifeCycleCallbacks: boolean;
+    destructor: boolean;
+    updateHook: boolean;
+  }
+
+  export interface ComponentManager<ComponentStateBucket> {
+    capabilities: ComponentCapabilities;
+    createComponent(factory: object, args: Arguments): ComponentStateBucket;
+    getContext(instance: ComponentStateBucket): unknown;
+  }
+}

package/types/preview/@ember/component/-private/signature-utils.d.ts

@@ -0,0 +1,107 @@
+declare module '@ember/component/-private/signature-utils' {
+  /**
+   * @module Type utilities for signatures
+   */
+
+  // Type-only "symbol" to use with `EmptyObject` below, so that it is *not*
+  // equivalent to an empty interface.
+  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 interface EmptyObject {
+    [Empty]?: true;
+  }
+
+  type DefaultPositional = unknown[];
+  type DefaultNamed = EmptyObject;
+
+  type GetOrElse<Obj, K, Fallback> = K extends keyof Obj ? Obj[K] : Fallback;
+
+  /** Given a signature `S`, get back the `Args` type. */
+  type ArgsFor<S> = 'Args' extends keyof S
+    ? {
+        Named: GetOrElse<S['Args'], 'Named', DefaultNamed>;
+        Positional: GetOrElse<S['Args'], 'Positional', []>;
+      }
+    : { Named: DefaultNamed; Positional: [] };
+
+  interface LegacyArgsFor<T> {
+    Named: GetOrElse<T, 'NamedArgs', DefaultNamed>;
+    Positional: GetOrElse<T, 'PositionalArgs', DefaultPositional>;
+  }
+
+  // This type allows us to present a slightly-less-obtuse error message
+  // when attempting to resolve the signature of a helper that doesn't have
+  // one declared from within a tool like Glint.
+  const BadType: unique symbol;
+  /** @internal This is *only* exported to use in tests! */
+  export interface BadType<Message> {
+    [BadType]: Message;
+  }
+
+  interface MissingSignatureArgs {
+    Named: BadType<'This helper is missing a signature'>;
+    Positional: unknown[];
+  }
+
+  /**
+   * 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***.
+   */
+  // This is similar but not identical to the `ExpandSignature` type used in the
+  // Glimmer Component API: it uses the same basic mechanics, but does not have
+  // an identical signature because we had not yet normalized the `Signature` when
+  // we designed the first pass of this. In the future, we will be able to make
+  // all `ExpandSignature` types fully general to work with *any* invokable. But
+  // "future" here probably means Ember v5. :sobbing:
+  // prettier-ignore
+  export interface ExpandSignature<T> {
+  Args:
+    // Is this the default (i.e. unspecified) signature?
+    // Then return our special "missing signature" type
+    unknown extends T ? MissingSignatureArgs :
+    // Is this a `Signature`? Then use `Signature` args
+    keyof T extends 'Args' | 'Return' ? ArgsFor<T> :
+    // Otherwise fall back to classic `Args`.
+    LegacyArgsFor<T>;
+  Return: 'Return' extends keyof T ? T['Return'] : unknown;
+}
+
+  // The `unknown extends S` checks on both of these are here to preserve backward
+  // compatibility with the existing non-`Signature` definition. When migrating
+  // into Ember or otherwise making a breaking change, we can drop the "default"
+  // in favor of just using `ExpandSignature`.
+  // prettier-ignore
+  export type NamedArgs<S> =
+  unknown extends S
+  ? Record<string, unknown>
+  : ExpandSignature<S>['Args']['Named'];
+
+  // prettier-ignore
+  export type PositionalArgs<S> =
+  unknown extends S
+  ? unknown[]
+  : ExpandSignature<S>['Args']['Positional'];
+
+  export type Return<S> = GetOrElse<S, 'Return', unknown>;
+}

package/types/preview/@ember/component/-private/view-mixin.d.ts

@@ -0,0 +1,59 @@
+declare module '@ember/component/-private/view-mixin' {
+  import Mixin from '@ember/object/mixin';
+
+  interface ViewMixin {
+    /**
+     * A list of properties of the view to apply as attributes. If the property
+     * is a string value, the value of that string will be applied as the value
+     * for an attribute of the property's name.
+     */
+    attributeBindings: string[];
+    /**
+     * Returns the current DOM element for the view.
+     */
+    element: Element;
+    /**
+     * The HTML `id` of the view's element in the DOM. You can provide this
+     * value yourself but it must be unique (just as in HTML):
+     */
+    elementId: string;
+    /**
+     * Tag name for the view's outer element. The tag name is only used when an
+     * element is first created. If you change the `tagName` for an element, you
+     * must destroy and recreate the view element.
+     */
+    tagName: string;
+    /**
+     * Renders the view again. This will work regardless of whether the
+     * view is already in the DOM or not. If the view is in the DOM, the
+     * rendering process will be deferred to give bindings a chance
+     * to synchronize.
+     */
+    rerender(): void;
+    /**
+     * Called when a view is going to insert an element into the DOM.
+     */
+    willInsertElement(): void;
+    /**
+     * Called when the element of the view has been inserted into the DOM.
+     * Override this function to do any set up that requires an element
+     * in the document body.
+     */
+    didInsertElement(): void;
+    /**
+     * Called when the view is about to rerender, but before anything has
+     * been torn down. This is a good opportunity to tear down any manual
+     * observers you have installed based on the DOM state
+     */
+    willClearRender(): void;
+    /**
+     * Called when the element of the view is going to be destroyed. Override
+     * this function to do any teardown that requires an element, like removing
+     * event listeners.
+     */
+    willDestroyElement(): void;
+  }
+  const ViewMixin: Mixin;
+
+  export default ViewMixin;
+}

package/types/preview/@ember/component/helper.d.ts

@@ -0,0 +1,122 @@
+declare module '@ember/component/helper' {
+  import EmberObject from '@ember/object';
+  import { Opaque } from 'ember/-private/type-utils';
+  import {
+    DefaultNamed,
+    DefaultPositional,
+    EmptyObject,
+    ExpandSignature,
+    NamedArgs,
+    PositionalArgs,
+    Return,
+  } from '@ember/component/-private/signature-utils';
+
+  // Immediately re-export these.
+  export { EmptyObject, ExpandSignature };
+
+  /**
+   * The public shape of a helper.
+   * @deprecated Do not use this directly. Instead, write a `Signature` with the
+   *   "normal" signature shape: `Args: { Named: { ... }, Positional: [...] }`.
+   */
+  export interface HelperSignature {
+    NamedArgs?: DefaultNamed;
+    PositionalArgs?: DefaultPositional;
+    Return?: unknown;
+  }
+
+  /**
+   * Ember Helpers are functions that can compute values, and are used in templates.
+   * For example, this code calls a helper named `format-currency`:
+   */
+  export default class Helper<S = unknown> extends EmberObject {
+    /**
+     * In many cases, the ceremony of a full `Ember.Helper` class is not required.
+     * The `helper` method create pure-function helpers without instances. For
+     * example:
+     */
+    static helper<P extends DefaultPositional, N = EmptyObject, R = unknown>(
+      helper: (positional: P, named: N) => R
+    ): Helper<{ Args: { Positional: P; Named: N }; Return: R }>;
+    /**
+     * Override this function when writing a class-based helper.
+     */
+    compute(positional: PositionalArgs<S>, named: NamedArgs<S>): Return<S>;
+    /**
+     * On a class-based helper, it may be useful to force a recomputation of that
+     * helpers value. This is akin to `rerender` on a component.
+     */
+    recompute(): void;
+  }
+
+  // The generic here is for a *signature*: a way to hang information for tools
+  // like Glint which can provide type checking for component templates using
+  // information supplied via this generic. While it may appear useless on this
+  // class definition and extension, it is used by external tools and should not
+  // be removed.
+  export default interface Helper<S> extends Opaque<S> {}
+
+  // This type exists to provide a non-user-constructible, non-subclassable
+  // type representing the conceptual "instance type" of a function helper.
+  // The abstract field of type `never` presents subclassing in userspace of
+  // the value returned from `helper()`. By extending `Helper<S>`, any
+  // augmentations of the `Helper` type performed by tools like Glint will
+  // also apply to function-based helpers as well.
+  export abstract class FunctionBasedHelperInstance<S> extends Helper<S> {
+    protected abstract __concrete__: never;
+  }
+
+  /**
+   * The type of a function-based helper.
+   *
+   * @note This is *not* user-constructible: it is exported only so that the type
+   *   returned by the `helper` function can be named (and indeed can be exported
+   *   like `export default helper(...)` safely).
+   */
+  // Making `FunctionBasedHelper` a bare constructor type allows for type
+  // parameters to be preserved when `helper()` is passed a generic function.
+  // By making it `abstract` and impossible to subclass (see above), we prevent
+  // users from attempting to instantiate a return value from `helper()`.
+  export type FunctionBasedHelper<S> = abstract new () => FunctionBasedHelperInstance<S>;
+
+  /**
+   * In many cases, the ceremony of a full `Helper` class is not required.
+   * The `helper` method create pure-function helpers without instances. For
+   * example:
+   * ```app/helpers/format-currency.js
+   * import { helper } from '@ember/component/helper';
+   * export default helper(function(params, hash) {
+   *   let cents = params[0];
+   *   let currency = hash.currency;
+   *   return `${currency}${cents * 0.01}`;
+   * });
+   * ```
+   */
+  // This overload allows users to write types directly on the callback passed to
+  // the `helper` function and infer the resulting type correctly.
+  export function helper<P extends DefaultPositional, N = EmptyObject, R = unknown>(
+    helperFn: (positional: P, named: N) => R
+  ): FunctionBasedHelper<{
+    Args: {
+      Positional: P;
+      Named: N;
+    };
+    Return: R;
+  }>;
+
+  // This overload allows users to provide a `Signature` type explicitly at the
+  // helper definition site, e.g. `helper<Sig>((pos, named) => {...})`. **Note:**
+  // this overload must appear second, since TS' inference engine will not
+  // correctly infer the type of `S` here from the types on the supplied callback.
+  export function helper<S>(
+    helperFn: (positional: PositionalArgs<S>, named: NamedArgs<S>) => Return<S>
+  ): FunctionBasedHelper<{
+    Args: {
+      Positional: PositionalArgs<S>;
+      Named: NamedArgs<S>;
+    };
+    Return: Return<S>;
+  }>;
+
+  export {};
+}

package/types/preview/@ember/component/index.d.ts

@@ -0,0 +1,132 @@
+declare module '@ember/component' {
+  import CoreView from '@ember/component/-private/core-view';
+  import ClassNamesSupport from '@ember/component/-private/class-names-support';
+  import ViewMixin from '@ember/component/-private/view-mixin';
+  import { ComponentManager, Capabilities } from '@ember/component/-private/glimmer-interfaces';
+  import { Opaque } from 'ember/-private/type-utils';
+
+  // Re-export these types so people can use them!
+  export { ComponentManager, Capabilities };
+
+  interface TemplateFactory {
+    __htmlbars_inline_precompile_template_factory: any;
+  }
+
+  // The generic here is for a *signature: a way to hang information for tools
+  // like Glint which can provide typey checking for component templates using
+  // information supplied via this generic. While it may appear useless on this
+  // class definition and extension, it is used by external tools and should not
+  // be removed.
+  export default interface Component<S = unknown> extends ViewMixin, ClassNamesSupport, Opaque<S> {}
+  export default class Component<S = unknown> extends CoreView {
+    // methods
+    readDOMAttr(name: string): string;
+    // properties
+    /**
+     * The WAI-ARIA role of the control represented by this view. For example, a button may have a
+     * role of type 'button', or a pane may have a role of type 'alertdialog'. This property is
+     * used by assistive software to help visually challenged users navigate rich web applications.
+     */
+    ariaRole: string;
+    /**
+     * The HTML id of the component's element in the DOM. You can provide this value yourself but
+     * it must be unique (just as in HTML):
+     *
+     * If not manually set a default value will be provided by the framework. Once rendered an
+     * element's elementId is considered immutable and you should never change it. If you need
+     * to compute a dynamic value for the elementId, you should do this when the component or
+     * element is being instantiated:
+     */
+    elementId: string;
+    /**
+     * A component may contain a layout. A layout is a regular template but supersedes the template
+     * property during rendering. It is the responsibility of the layout template to retrieve the
+     * template property from the component (or alternatively, call Handlebars.helpers.yield,
+     * {{yield}}) to render it in the correct location. This is useful for a component that has a
+     * shared wrapper, but which delegates the rendering of the contents of the wrapper to the
+     * template property on a subclass.
+     */
+    layout: TemplateFactory | string;
+    /**
+     * Enables components to take a list of parameters as arguments.
+     */
+    static positionalParams: string[] | string;
+    // events
+    /**
+     * Called when the attributes passed into the component have been updated. Called both during the
+     * initial render of a container and during a rerender. Can be used in place of an observer; code
+     * placed here will be executed every time any attribute updates.
+     */
+    didReceiveAttrs(): void;
+    /**
+     * Called after a component has been rendered, both on initial render and in subsequent rerenders.
+     */
+    didRender(): void;
+    /**
+     * Called when the component has updated and rerendered itself. Called only during a rerender,
+     * not during an initial render.
+     */
+    didUpdate(): void;
+    /**
+     * Called when the attributes passed into the component have been changed. Called only during a
+     * rerender, not during an initial render.
+     */
+    didUpdateAttrs(): void;
+    /**
+     * Called before a component has been rendered, both on initial render and in subsequent rerenders.
+     */
+    willRender(): void;
+    /**
+     * Called when the component is about to update and rerender itself. Called only during a rerender,
+     * not during an initial render.
+     */
+    willUpdate(): void;
+
+    /**
+     * `reopen()` was deprecated and removed from `Component`. It is given an
+     * illegitimate type in these types so that you cannot call it or use it!
+     * Unfortunately, it cannot actually be *removed* from this type, because TS
+     * rightly complains that `Component` is no longer a valid subtype of the
+     * `EmberObject` base class, and will not let you use it.
+     */
+    static reopen(): never;
+  }
+
+  /**
+   * Associate a class with a component manager (an object that is responsible for
+   * coordinating the lifecycle events that occurs when invoking, rendering and
+   * re-rendering a component).
+   *
+   * @param managerFactory a function to create the owner for an object
+   * @param object the object to associate with the componetn manager
+   * @return the same object passed in, now associated with the manager
+   */
+  export function setComponentManager<T>(
+    managerFactory: (owner: unknown) => ComponentManager<unknown>,
+    object: T
+  ): T;
+
+  // In normal TypeScript, these built-in components are essentially opaque tokens
+  // that just need to be importable. Declaring them with unique interfaces
+  // like this, however, gives tools like Glint (that DO have a richer
+  // notion of what they are) a place to install more detailed type information.
+  export interface Input extends Opaque<'component:input'> {}
+  export interface Textarea extends Opaque<'component:textarea'> {}
+
+  /**
+   * The `Input` component lets you create an HTML `<input>` element.
+   *
+   * @see https://api.emberjs.com/ember/4.1/classes/Ember.Templates.components/methods/Input?anchor=Input
+   */
+  export const Input: Input;
+
+  /**
+   * The `Textarea` component inserts a new instance of `<textarea>` tag into the template.
+   *
+   * @see https://api.emberjs.com/ember/4.1/classes/Ember.Templates.components/methods/Textarea?anchor=Textarea
+   */
+  export const Textarea: Textarea;
+
+  // Do not export anything but what we *explicitly* say to export.
+  export {};
+}