@arcgis/lumina 5.2.0-next.2 → 5.2.0-next.21

package/dist/controllers/types.d.ts

@@ -1,187 +1,116 @@
-import { IHandle } from '@arcgis/toolkit/type';
-import { ReactiveControllerHost, ReactiveController, PropertyDeclaration, PropertyValues } from 'lit';
-import { LitElement } from '../LitElement.ts';
-export type TrackKeyResolution = {
-    readonly key: string;
-    readonly host: BaseController | LitElement;
-    /**
-     * True if property is decorated with a `@state()` or `@property()` decorator
-     */
-    readonly isReactive: boolean;
-};
-/**
- * @deprecated use LitElement instead
- */
-export type BaseComponent = Omit<LitElement, "componentOnReady"> & {
-    autoDestroyDisabled?: boolean;
-    destroy?: () => Promise<void>;
-};
+import type { IHandle } from "@arcgis/toolkit/type";
+import type { ReactiveController, PropertyDeclaration, PropertyValues } from "lit";
+import type { LitElement } from "../LitElement.js";
+
+export interface TrackKeyResolution {
+  readonly key: string;
+  readonly host: BaseController | LitElement;
+  /** True if property is decorated with a `@state()` or `@property()` decorator */
+  readonly isReactive: boolean;
+}
+
 /**
  * Helper utility to get component type from a controller. Can be used in
- * "implements"
+ * "implements".
+ *
+ * TypeScript detects errors even without `Use<typeof useHomeViewModel>`, but Use
+ * makes errors display in a more readable format.
+ *
  * @example
+ * ```ts
  * const useHomeViewModel = makeViewModelController(newWidgetsHomeHomeViewModel);
  * export class Home extends LitElement implements Use<typeof useHomeViewModel> {
- *
- * @remarks
- * TypeScript detects errors even without Use<typeof useHomeViewModel>, but Use
- * makes errors display in a more readable format
+ * ```
  */
 export type Use<Callback extends (component: any) => unknown> = Parameters<Callback>[0];
-/**
- * Base API for a controller. Compatible with Lit's Reactive controllers
- */
+
+/** Base API for a controller. Compatible with Lit's Reactive controllers */
 export type ControllerLifecycleMethods = {
-    readonly hostConnected?: ReactiveController["hostConnected"];
-    readonly hostDisconnected?: ReactiveController["hostDisconnected"];
-    readonly hostLoad?: () => Promise<void> | void;
-    readonly hostLoaded?: () => void;
-    /**
-     * Called during the client-side host update, just before the host calls
-     * its own update.
-     *
-     * Code in `update()` can depend on the DOM as it is not called in
-     * server-side rendering.
-     */
-    hostUpdate?(changes: PropertyValues): void;
-    /**
-     * Called after a host update, just before the host calls firstUpdated and
-     * updated. It is not called in server-side rendering.
-     */
-    hostUpdated?(changes: PropertyValues): void;
-    /**
-     * Called when the component is finally being destroyed (rather than
-     * temporary disconnected from the DOM)
-     */
-    readonly hostDestroy?: () => void;
-    /**
-     * lifecycle() is a convenience higher-level callback that:
-     * - calls the provided callback right away the first time if
-     *   connectedCallback has already happened once
-     *   - otherwise, calls it on connectedCallback
-     * - calls the callback on each future connectedCallback
-     * - if you returned a function, or an object like {remove:()=>void}, that
-     *   function will be called on the next disconnectedCallback
-     *
-     * This is a bit like useEffect(callback, []) in React
-     */
-    readonly hostLifecycle?: () => (() => void)[] | IHandle | IHandle[] | (() => void) | undefined | void;
-    /**
-     * Called after component.removeComponent(controller) was called on this
-     * controller
-     */
-    readonly controllerRemoved?: () => void;
-};
-/**
- * Controller host interface, compatible with both Lit's Reactive controllers
- * and Stencil's lifecycle.
- * These members are added to the component instance by ControllerManager.
- *
- * @deprecated use LitElement instead
- */
-export type ControllerHost = {
-    /**
-     * Adds a controller to the host, which connects the controller's lifecycle
-     * methods to the host's lifecycle.
-     */
-    addController(controller: BaseController): void;
-    addController(controller: ReactiveController): void;
-    /**
-     * Removes a controller from the host.
-     */
-    removeController(controller: BaseController): void;
-    removeController(controller: ReactiveController): void;
-    /**
-     * Requests a host update which is processed asynchronously. The update can
-     * be waited on via the `updateComplete` property.
-     *
-     * @remarks
-     * It is recommended to provide the property name describing what property
-     * triggered the update - property name will be provided to the willUpdate()
-     * lifecycle hook, giving it the ability to react to the change.
-     *
-     * @see https://lit.dev/docs/api/ReactiveElement/#ReactiveElement.requestUpdate
-     */
-    requestUpdate: (name?: PropertyKey, oldValue?: unknown, options?: PropertyDeclaration) => void;
-    readonly updateComplete: ReactiveControllerHost["updateComplete"];
+  readonly hostConnected?: ReactiveController["hostConnected"];
+  readonly hostDisconnected?: ReactiveController["hostDisconnected"];
+  hostLoad?(): Promise<void> | void;
+  hostLoaded?(): void;
+  /**
+   * Called during the client-side host update, just before the host calls
+   * its own update.
+   *
+   * Code in `update()` can depend on the DOM as it is not called in
+   * server-side rendering.
+   *
+   * @param changes
+   */
+  hostUpdate?(changes: PropertyValues): void;
+  /**
+   * Called after a host update, just before the host calls firstUpdated and
+   * updated. It is not called in server-side rendering.
+   *
+   * @param changes
+   */
+  hostUpdated?(changes: PropertyValues): void;
+  /**
+   * Called when the component is finally being destroyed (rather than
+   * temporary disconnected from the DOM)
+   */
+  hostDestroy?(): void;
+  /**
+   * lifecycle() is a convenience higher-level callback that:
+   * - calls the provided callback right away the first time if
+   *   connectedCallback has already happened once
+   *   - otherwise, calls it on connectedCallback
+   * - calls the callback on each future connectedCallback
+   * - if you returned a function, or an object like {remove:()=>void}, that
+   *   function will be called on the next disconnectedCallback
+   *
+   * This is a bit like `useEffect(callback, [])` in React
+   */
+  hostLifecycle?(): (() => void)[] | IHandle | IHandle[] | (() => void) | undefined | void;
+  /**
+   * Called after component.removeComponent(controller) was called on this
+   * controller
+   */
+  controllerRemoved?(): void;
 };
+
 /**
  * A symbol is used to mark providers/controllers on a component instance.
  * This helps to distinguish them from regular properties.
+ *
+ * @internal
  */
-export declare const controllerSymbol: unique symbol;
+export const controllerSymbol: unique symbol;
+
 /**
  * Adding an optional symbol to satisfy TypeScript
  * "type Controller has no properties in common with BaseController"
  */
-export type BaseController = ControllerLifecycleMethods & {
-    readonly [controllerSymbol]?: true;
-};
-/**
- * Property declaration with additional `reaDonly` option (handled by Controllers)
- */
-export type LuminaPropertyDeclaration = PropertyDeclaration & {
-    /**
-     * Declare a property that can't be modified by the developer.
-     *
-     * @example
-     * ```ts
-     * \@property({ readOnly: true })
-     * myReadonlyProp = 'initialValue';
-     * ```
-     *
-     * @example
-     * Inside the component code, you can overwrite the readOnly property like so:
-     * ```ts
-     * bypassReadOnly(() => {
-     *  this.myReadonlyProp = 'newValue';
-     * });
-     * ```
-     *
-     * @example
-     * Alternatively, you can declare a readOnly prop like so:
-     *
-     * ```ts
-     * \@property()
-     * get myReadonlyProp(): string {
-     *   return 'someValue';
-     * }
-     * ```
-     */
-    readonly readOnly?: boolean;
-    /**
-     * Short for "changed"
-     *
-     * Temporary set during a setter to track whether property is considered
-     * changed.
-     * @private
-     */
-    c?: boolean;
-    /**
-     * Short for "descriptor"
-     *
-     * Stores a reference to the property getter and setter. This is overwritten
-     * in useAccessor to proxy the get/set through the Accessor instance.
-     * @private
-     */
-    d?: PropertyDescriptor;
-    /**
-     * The positional index of the Accessor controller to which this property is
-     * bound.
-     * @private
-     */
-    i?: number;
-};
-/** @private */
-export type AccessorObservableLike = {
-    /**
-     * A callback that will be called in the setter if the value hasChanged to
-     * integrate with Accessor's reactivity notification system.
-     */
-    notify: () => void;
-};
-/** @private */
-export type ReactiveTrackingTarget = {
-    clear: () => void;
-    destroy: () => void;
-};
+export type BaseController = ControllerLifecycleMethods;
+
+/** Property declaration with additional `reaDonly` option (handled by Controllers) */
+export interface LuminaPropertyDeclaration extends PropertyDeclaration {
+  /**
+   * Declare a property that can't be modified by the developer.
+   *
+   * @example
+   * ```ts
+   * \@property({ readOnly: true })
+   * myReadonlyProp = 'initialValue';
+   * ```
+   * @example
+   * Inside the component code, you can overwrite the readOnly property like so:
+   * ```ts
+   * bypassReadOnly(() => {
+   *  this.myReadonlyProp = 'newValue';
+   * });
+   * ```
+   * @example
+   * Alternatively, you can declare a readOnly prop like so:
+   *
+   * ```ts
+   * \@property()
+   * get myReadonlyProp(): string {
+   *   return 'someValue';
+   * }
+   * ```
+   */
+  readonly readOnly?: boolean;
+}

package/dist/controllers/useDirection.d.ts

@@ -1,11 +1,10 @@
-type Direction = "ltr" | "rtl";
+export type Direction = "ltr" | "rtl";
+
 /**
  * Finds the closest "dir" attribute to current component and returns it's value.
  * Watches for changes to "dir" and will re-render your component if needed.
  *
- * Documentation: https://webgis.esri.com/references/lumina/controllers/useDirection
- *
- * Design decisions: https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/987
+ * @see https://webgis.esri.com/references/lumina/controllers/useDirection
+ * @see [Design decisions](https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/987)
  */
-export declare const useDirection: () => Direction;
-export {};
+export function useDirection(): Direction;

package/dist/controllers/useMedia.d.ts

@@ -3,6 +3,7 @@
  * whether user asked to use reduced motion, or whether the screen size is above
  * certain threshold).
  *
- * Documentation: https://webgis.esri.com/references/lumina/controllers/useMedia
+ * @param query
+ * @see https://webgis.esri.com/references/lumina/controllers/useMedia
  */
-export declare const useMedia: (query: string) => boolean;
+export function useMedia(query: string): boolean;

package/dist/controllers/usePropertyChange.d.ts

@@ -1,14 +1,13 @@
-import { EventEmitter } from '../createEvent.ts';
-import { LitElement } from '../LitElement.ts';
-type PropertyChangeController<Component extends LitElement> = <ToWatch extends keyof Component>(...toWatch: ToWatch[]) => EventEmitter<{
-    name: ToWatch & string;
-}>;
+import type { EventEmitter } from "../createEvent.js";
+import type { LitElement } from "../LitElement.js";
+
+/** @param toWatch */
+export type PropertyChangeController<Component extends LitElement> = <ToWatch extends keyof Component>(...toWatch: ToWatch[]) => EventEmitter<{ name: ToWatch & string; }>;
+
 /**
  * Let user easily set watchers for component properties.
  *
- * Documentation: https://webgis.esri.com/references/lumina/controllers/usePropertyChange
+ * @param component
+ * @see [Documentation](https://webgis.esri.com/references/lumina/controllers/usePropertyChange)
  */
-export declare const usePropertyChange: <Component extends LitElement>(
-/** Needed for typings only */
-_component?: LitElement) => PropertyChangeController<Component>;
-export {};
+export function usePropertyChange<Component extends LitElement>(component?: LitElement): PropertyChangeController<Component>;

package/dist/controllers/useSlottableRequest.d.ts

@@ -1,15 +1,21 @@
-import { EventEmitter } from '../createEvent.ts';
-import { LitElement } from '../LitElement.ts';
-type SlottableRequestDetail = {
-    name: string;
-    slotName: string;
-    data: unknown;
-};
-type WatchedProps<Component extends LitElement, ToWatch extends readonly (keyof Component)[]> = Pick<Component, ToWatch[number]>;
+import type { EventEmitter } from "../createEvent.js";
+import type { LitElement } from "../LitElement.js";
+
+export interface SlottableRequestDetail {
+  name: string;
+  slotName: string;
+  data: unknown;
+}
+
+export type WatchedProps<Component extends LitElement, ToWatch extends readonly (keyof Component)[]> = Pick<Component, ToWatch[number]>;
+
 /**
  * Watches host properties and emits slottable request details when the
  * requested slot details are added, removed, or changed.
  *
+ * @param component
+ * @param watch
+ * @param getDetailsBySlotName
  * @example
  * ```ts
  * const slottableRequest = useSlottableRequest(this, ["item"], ({ item }) => {
@@ -18,5 +24,4 @@ type WatchedProps<Component extends LitElement, ToWatch extends readonly (keyof
  *  return details;
  * });
  */
-export declare const useSlottableRequest: <Component extends LitElement, const ToWatch extends readonly (keyof Component)[], Detail extends SlottableRequestDetail>(component: Component, watch: ToWatch, getDetailsBySlotName: (component: WatchedProps<Component, ToWatch>) => ReadonlyMap<string, Detail>) => EventEmitter<Detail>;
-export {};
+export function useSlottableRequest<Component extends LitElement, const ToWatch extends readonly (keyof Component)[], Detail extends SlottableRequestDetail>(component: Component, watch: ToWatch, getDetailsBySlotName: (component: WatchedProps<Component, ToWatch>) => ReadonlyMap<string, Detail>): EventEmitter<Detail>;

package/dist/controllers/useT9n.d.ts

@@ -1,48 +1,54 @@
-import { GenericT9nStrings, LocaleObserverResult } from '@arcgis/toolkit/intl';
+import type { GenericT9nStrings, LocaleObserverResult } from "@arcgis/toolkit/intl";
+
 export type T9nMeta<T9nStrings extends GenericT9nStrings> = {
-    _lang: LocaleObserverResult["lang"];
-    _t9nLocale: LocaleObserverResult["t9nLocale"];
-    _loading: boolean;
-    /**
-     * The "_overrides" property won't actually exist at runtime and exists only
-     * to simplify typing like so:
-     *
-     * @example
-     * ```ts
-     *   // Type of the messageOverrides is set automatically based on _overrides:
-     *   @property() messageOverrides?: typeof this.messages._overrides;
-     * ```
-     */
-    _overrides: DeepPartial<T9nStrings>;
-    /**
-     * If messageOverrides are in effect, this will contain original strings
-     */
-    _original?: T9nStrings;
+  _lang: LocaleObserverResult["lang"];
+  _t9nLocale: LocaleObserverResult["t9nLocale"];
+  _loading: boolean;
+  /**
+   * The "_overrides" property won't actually exist at runtime and exists only
+   * to simplify typing like so:
+   *
+   * @example
+   * ```ts
+   *   // Type of the messageOverrides is set automatically based on _overrides:
+   *   \@property() messageOverrides?: typeof this.messages._overrides;
+   * ```
+   */
+  _overrides: DeepPartial<T9nStrings>;
+  /** If messageOverrides are in effect, this will contain original strings */
+  _original?: T9nStrings;
 };
-type DeepPartial<T> = T extends object ? {
+
+export type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
-type Options = {
-    readonly name?: string | null;
-    /** @default false */
-    readonly blocking?: boolean;
-};
+
+export interface Options {
+  /**
+   * The name of the bundle to fetch. By default, lowercase tag-name of the
+   * component without the "arcgis-" part
+   *
+   * Set to null if the component has no localization strings, but you still
+   * wish to use `useT9n` to get the locale information.
+   */
+  readonly name?: string | null;
+  /** @default false */
+  readonly blocking?: boolean;
+}
+
 export interface UseT9n {
-    <Strings extends GenericT9nStrings>(options: Options & {
-        readonly blocking: true;
-    }): Strings & T9nMeta<Strings>;
-    <Strings extends GenericT9nStrings>(options?: Options & {
-        readonly blocking?: false;
-    }): Partial<Strings> & T9nMeta<Strings>;
+  /** @param options */
+  <Strings extends GenericT9nStrings>(options: Options & { readonly blocking: true; }): Strings & T9nMeta<Strings>;
+  /** @param options */
+  <Strings extends GenericT9nStrings>(options?: Options & { readonly blocking?: false; }): Partial<Strings> & T9nMeta<Strings>;
 }
+
 /**
  * Load component's localization strings.
  *
- * Documentation: https://webgis.esri.com/references/lumina/controllers/useT9n
- *
- * Design decisions:
- * - https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/969
- * - https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/987
+ * @param getAssetPath
+ * @see [Documentation](https://webgis.esri.com/references/lumina/controllers/useT9n)
+ * @see [Design decisions 1](https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/969)
+ * @see [Design decisions 2](https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/987)
  */
-export declare const makeT9nController: (getAssetPath: (path: string) => string) => UseT9n;
-export {};
+export function makeT9nController(getAssetPath: (path: string) => string): UseT9n;

package/dist/controllers/useWatchAttributes.d.ts

@@ -1,7 +1,10 @@
-import { Controller } from './Controller.ts';
+import type { Controller } from "./Controller.js";
+
 /**
  * Watch when given attributes change on the component element.
  *
- * Documentation: https://webgis.esri.com/references/lumina/controllers/useWatchAttributes
+ * @param attributes
+ * @param callback
+ * @see https://webgis.esri.com/references/lumina/controllers/useWatchAttributes
  */
-export declare const useWatchAttributes: <T extends string>(attributes: readonly T[], callback: (newValue: string | null, oldValue: string | null, attribute: T) => void) => Controller;
+export function useWatchAttributes<T extends string>(attributes: readonly T[], callback: (newValue: string | null, oldValue: string | null, attribute: T) => void): Controller;

package/dist/controllers/utils.d.ts

@@ -1,12 +1,20 @@
-import { LitElement } from '../LitElement.ts';
-import { ControllerLifecycleMethods } from './types.ts';
-export declare const isController: (value: unknown) => value is ControllerLifecycleMethods;
+import type { LitElement } from "../LitElement.js";
+import type { ControllerLifecycleMethods } from "./types.js";
+
+/** @param value */
+export function isController(value: unknown): value is ControllerLifecycleMethods;
+
 /**
  * Checks if the argument is a promise by checking if it has a `then` method.
+ *
+ * @param arg
  */
-export declare const isPromise: <T>(arg: Promise<T> | T) => arg is Promise<T>;
+export function isPromise<T>(arg: Promise<T> | T): arg is Promise<T>;
+
 /**
  * Get the number of controllers current component has. Can be used to get a
  * unique id for each controller.
+ *
+ * @param component
  */
-export declare const getControllersCount: (component: LitElement) => number;
+export function getControllersCount(component: LitElement): number;

package/dist/createEvent.d.ts

@@ -1,42 +1,43 @@
-/**
- * An event emitter object
- */
-export type EventEmitter<T = void> = {
-    emit(payload: T): CustomEvent<T>;
-};
+/** An event emitter object. */
+export interface EventEmitter<T = void> {
+  /** @param payload */
+  emit(payload: T): CustomEvent<T>;
+}
+
 /**
  * While these defaults don't match DOM defaults (all false), they match
  * Stencil and Shoelace defaults. Also, they make more sense for our
  * usage (i.e why would you want events to not be cancelable by default?)
  */
-export type EventOptions = {
-    /**
-     * A Boolean indicating whether the event bubbles up through the DOM or not.
-     *
-     * @default true
-     */
-    bubbles?: boolean;
-    /**
-     * A Boolean indicating whether the event is cancelable. Defaults to `true`,
-     * unlike the DOM's default of `false`, as that is the desired behavior most
-     * of the time.
-     *
-     * @default true
-     */
-    cancelable?: boolean;
-    /**
-     * A Boolean value indicating whether or not the event can bubble across the
-     * boundary between the shadow DOM and the regular DOM.
-     *
-     * @default true
-     */
-    composed?: boolean;
-};
-export declare const createEventFactory: <T = void>(eventName?: string, options?: EventOptions, component?: import('./LitElement.ts').LitElement) => EventEmitter<T>;
+export interface EventOptions {
+  /**
+   * A Boolean indicating whether the event bubbles up through the DOM or not.
+   *
+   * @default true
+   */
+  bubbles?: boolean;
+  /**
+   * A Boolean indicating whether the event is cancelable. Defaults to `true`,
+   * unlike the DOM's default of `false`, as that is the desired behavior most
+   * of the time.
+   *
+   * @default true
+   */
+  cancelable?: boolean;
+  /**
+   * A Boolean value indicating whether or not the event can bubble across the
+   * boundary between the shadow DOM and the regular DOM.
+   *
+   * @default true
+   */
+  composed?: boolean;
+}
+
 /**
  * Creates an event emitter.
  * Events emitted by your component will be included in the documentation.
  *
+ * @param options
  * @example
  * Declaring an event whose payload is of type `number`:
  *
@@ -45,6 +46,5 @@ export declare const createEventFactory: <T = void>(eventName?: string, options?
  *   arcgisClick = createEvent<number>();
  * }
  * ```
- *
  */
-export declare const createEvent: <T = void>(options?: EventOptions) => EventEmitter<T>;
+export const createEvent: <T = void>(options?: EventOptions) => EventEmitter<T>;

package/dist/decorators.d.ts

@@ -1,5 +1,7 @@
-import { LuminaPropertyDeclaration } from './controllers/types.ts';
-export { state } from 'lit/decorators/state.js';
+import type { LuminaPropertyDeclaration } from "./controllers/types.js";
+
+export { state } from "lit/decorators/state.js";
+
 /**
  * A class field or accessor decorator which creates a reactive property that
  * reflects a corresponding attribute value. When a decorated property is set
@@ -22,15 +24,14 @@ export { state } from 'lit/decorators/state.js';
  * needed, state properties can be initialized via public properties to
  * facilitate complex interactions.
  *
+ * @param options
  * @example
- *
  * ```ts
  * class MyElement {
  *   \@property()
  *   clicked = false;
  * }
  * ```
- *
  * @example
  * Declaring a readOnly property:
  *
@@ -41,15 +42,21 @@ export { state } from 'lit/decorators/state.js';
  * }
  * ```
  */
-export declare const property: (options?: Omit<LuminaPropertyDeclaration, "state">) => PropertyDecorator;
-declare type CustomMethodDecorator<T> = (target: unknown, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+export const property: (options?: Omit<LuminaPropertyDeclaration, "state">) => PropertyDecorator;
+
+/**
+ * @param target
+ * @param propertyKey
+ * @param descriptor
+ */
+export type CustomMethodDecorator<T> = (target: unknown, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+
 /**
  * The `@method()` decorator is used to expose methods on the public API.
  * Class methods decorated with the `@method()` decorator can be called directly
  * from the element, meaning they are intended to be callable from the outside.
  *
- * @remarks
  * This decorator does not exist at runtime and is only used as a hint for the
- * compiler to declare certain methods as public.
+ * compiler to expose the methods in NPM and CDN builds.
  */
-export declare const method: () => CustomMethodDecorator<(...args: never[]) => any>;
+export const method: () => CustomMethodDecorator<(...args: never[]) => any>;