@arcgis/lumina 4.33.0-next.10 → 4.33.0-next.101

package/dist/controllers/tests/autoDestroyMock.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Mocking utility for changing auto-destroy timeout in ControllerManager to 0ms.
+ * Also, returns a convenient promise that resolves after the timeout.
+ */
+export declare function autoDestroyMock(timeout?: number): () => Promise<void>;

package/dist/controllers/tests/utils.d.ts

@@ -0,0 +1 @@
+export declare function captureConsoleErrors(): unknown[][];

package/dist/controllers/toFunction.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A tiny helper for using a class-based controller as if it's a function.
+ * Main advantage of this is that it's a bit shorter to type.
+ *
+ * This utility can be used for converting non-controller classes to functions
+ * too
+ */
+export declare const toFunction: <T, const P extends unknown[]>(Class: new (...args: P) => T) => ((...args: P) => T);

package/dist/controllers/trackKey.d.ts

@@ -0,0 +1,8 @@
+import { LitElement } from '../LitElement';
+import { BaseController, TrackKeyResolution } from './types';
+/**
+ * A combination of trackPropertyKey() and trackPropKey(). For usage when
+ * you want to track a property, but don't know if it will be defined with the
+ * \@property() decorator or not
+ */
+export declare function trackKey<T>(hostsCandidates: ((BaseController | LitElement)[] | BaseController | LitElement) | undefined, onResolved: (resolution: TrackKeyResolution | undefined) => void, defaultValue: T): T;

package/dist/controllers/trackPropKey.d.ts

@@ -0,0 +1,21 @@
+import { LitElement } from '../LitElement';
+/**
+ * Like trackPropertyKey(), but for props that have \@state() or \@property()
+ * decorator
+ *
+ * @example
+ * function trackMe() {
+ *   const component = retrieveComponent();
+ *   const defaultValue = 'some value';
+ *   return trackPropKey(component, (key)=>console.log(key), defaultValue);
+ * }
+ *
+ * class MyComponent extends LitElement {
+ *   // Will console log "myProp"
+ *   \@property() myProp = trackMe();
+ *
+ *   // Will console log "myState"
+ *   \@state() myState = trackMe();
+ * }
+ */
+export declare function trackPropKey<T>(component: LitElement, onResolved: (key: string | undefined) => void, defaultValue: T): T;

package/dist/controllers/trackPropertyKey.d.ts

@@ -0,0 +1,29 @@
+import { LitElement } from '../LitElement';
+import { BaseController } from './types';
+/**
+ * A magical solution to finding out what property name a given controller
+ * on a given object was assigned to.
+ *
+ * @remarks
+ * This does not work for properties that have \@property() or \@state()
+ * decorator - for those, use trackPropKey() instead.
+ *
+ * @example
+ * function trackMe<T>(defaultValue: T, component: LitElement):T {
+ *   trackPropertyKey(component, (key)=>console.log(key), defaultValue);
+ *   return defaultValue;
+ * }
+ *
+ * class MyComponent extends LitElement {
+ *   // Will console log "myProp"
+ *   myProp = trackMe('a', this);
+ * }
+ *
+ */
+export declare function trackPropertyKey<T>(object: BaseController | LitElement, onResolved: (key: string | undefined) => void, defaultValue: T): T;
+/**
+ * Resolve all pending trackPropertyKey() calls. This must be called after a
+ * property you are trying to resolve had it's default value set, thus after
+ * constructor. At the start of connectedCallback is a perfect place.
+ */
+export declare function keyTrackResolve(): void;

package/dist/controllers/types.d.ts

@@ -0,0 +1,152 @@
+import { IHandle } from '@arcgis/components-utils';
+import { ReactiveControllerHost, ReactiveController, PropertyDeclaration, PropertyValues } from 'lit';
+import { LitElement } from '../LitElement';
+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>;
+};
+/**
+ * Helper utility to get component type from a controller. Can be used in
+ * "implements"
+ * @example
+ * 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
+ */
+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"];
+};
+/**
+ * A symbol is used to mark providers/controllers on a component instance.
+ * This helps to distinguish them from regular properties.
+ */
+export declare 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;
+};

package/dist/controllers/useDirection.d.ts

@@ -0,0 +1,11 @@
+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://qawebgis.esri.com/components/lumina/controllers/useDirection
+ *
+ * Design decisions: https://devtopia.esri.com/WebGIS/arcgis-web-components/discussions/987
+ */
+export declare const useDirection: () => Direction;
+export {};

package/dist/controllers/useMedia.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Lets you query whether a given CSS media query applies to the page (i.e.
+ * whether user asked to use reduced motion, or whether the screen size is above
+ * certain threshold).
+ *
+ * Documentation: https://qawebgis.esri.com/components/lumina/controllers/useMedia
+ */
+export declare const useMedia: (query: string) => boolean;

package/dist/controllers/usePropertyChange.d.ts

@@ -0,0 +1,12 @@
+import { EventEmitter } from '../createEvent';
+import { LitElement } from '../LitElement';
+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://qawebgis.esri.com/components/lumina/controllers/usePropertyChange
+ */
+export declare const usePropertyChange: <Component extends LitElement>(_component?: LitElement) => PropertyChangeController<Component>;
+export {};

package/dist/controllers/useT9n.d.ts

@@ -0,0 +1,48 @@
+import { GenericT9nStrings, LocaleObserver } from '@arcgis/components-utils';
+export type T9nMeta<T9nStrings extends GenericT9nStrings> = {
+    _lang: LocaleObserver["lang"];
+    _t9nLocale: LocaleObserver["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 ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+type Options = {
+    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>;
+}
+/**
+ * Load component's localization strings.
+ *
+ * Documentation: https://qawebgis.esri.com/components/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
+ */
+export declare const makeT9nController: (getAssetPath: (path: string) => string) => UseT9n;
+export {};

package/dist/controllers/useWatchAttributes.d.ts

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

package/dist/controllers/utils.d.ts

@@ -0,0 +1,15 @@
+import { Controller } from './Controller';
+import { ControllerLifecycleMethods } from './types';
+export declare const isController: (value: unknown) => value is ControllerLifecycleMethods;
+/**
+ * In development, on hot module reload, controller would be re-initialized
+ * with all Props and State values persistent, but properties lost. This unsafe
+ * development-only API lets you set or get data for a controller that would
+ * persist across hot reloads.
+ */
+export declare const devOnlySetPersistentControllerData: ((controller: Controller<unknown>, data: unknown) => void) | undefined;
+export declare const devOnlyGetPersistentControllerData: (<T>(controller: Controller<unknown>) => T | undefined) | undefined;
+/**
+ * Checks if the argument is a promise by checking if it has a `then` method.
+ */
+export declare function isPromise<T>(arg: Promise<T> | T): arg is Promise<T>;

package/dist/createEvent.d.ts

@@ -1,4 +1,9 @@
-import type { BaseComponent, EventEmitter } from "@arcgis/components-controllers";
+/**
+ * An event emitter object
+ */
+export type EventEmitter<T = undefined> = {
+    emit(payload: T extends undefined ? void : 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
@@ -27,7 +32,7 @@ export type EventOptions = {
      */
     composed?: boolean;
 };
-export declare const createEventFactory: <T = undefined>(eventName?: string, options?: EventOptions, component?: BaseComponent) => EventEmitter<T>;
+export declare const createEventFactory: <T = undefined>(eventName?: string, options?: EventOptions, component?: import('./LitElement').LitElement) => EventEmitter<T>;
 /**
  * Creates an event emitter.
  * Events emitted by your component will be included in the documentation.

package/dist/decorators.d.ts

@@ -1,5 +1,5 @@
-import type { LuminaPropertyDeclaration } from "@arcgis/components-controllers";
-export { state } from "@lit/reactive-element/decorators/state.js";
+import { LuminaPropertyDeclaration } from './controllers/types';
+export { state } from '@lit/reactive-element/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

package/dist/devOnlyDetectIncorrectLazyUsages.d.ts

@@ -1,4 +1,4 @@
-import type { LitElement } from "./LitElement";
+import { LitElement } from './LitElement';
 /**
  * When in lazy-build, the actual Lit element is never attached to the DOM.
  * Instead, a proxy element is present and should be used for all DOM actions.

package/dist/hmrSupport.d.ts

@@ -1,4 +1,4 @@
-import type { ModuleNamespace } from "vite/types/hot.js";
+import { ModuleNamespace } from 'vite/types/hot.js';
 /**
  * Update web component proxies when a module is updated.
  *

package/dist/hmrSupport.js

@@ -1,10 +1,4 @@
-import {
-  ProxyComponent,
-  noShadowRoot
-} from "./chunk-NO7HOBNA.js";
-import "./chunk-PGHUBTOM.js";
-
-// src/hmrSupport.ts
+import { n as noShadowRoot, P as ProxyComponent } from "./utils-DBdf1Dqp.js";
 import { camelToKebab } from "@arcgis/components-utils";
 function handleHmrUpdate(newModules) {
   newModules.forEach((newModule) => {

package/dist/index.d.ts

@@ -1,16 +1,17 @@
-export { useContextProvider, useContextConsumer } from "./context";
-export type { EventOptions } from "./createEvent";
-export { createEvent } from "./createEvent";
-export { state, property, method } from "./decorators";
-export type { DefineCustomElements, LazyLoadOptions, GlobalThisWithPuppeteerEnv } from "./lazyLoad";
-export { makeDefineCustomElements } from "./lazyLoad";
-export { LitElement } from "./LitElement";
-export type { PublicLitElement } from "./PublicLitElement";
-export type { Runtime, RuntimeOptions, DevOnlyGlobalRuntime, DevOnlyGlobalComponentRefCallback } from "./runtime";
-export { makeRuntime } from "./runtime";
-export type { EventHandler } from "./jsx/baseTypes";
-export * from "./jsx/types";
-export { safeClassMap, safeStyleMap, directive, live } from "./jsx/directives";
-export { nothing, noChange, setAttribute, stringOrBoolean } from "./jsx/utils";
-export { noShadowRoot } from "./utils";
-export { makeReactWrapperFactory, getReactWrapperOptions } from "./wrappersUtils";
+export { useContextProvider, useContextConsumer } from './context';
+export type { EventEmitter, EventOptions } from './createEvent';
+export { createEvent } from './createEvent';
+export { state, property, method } from './decorators';
+export type { DefineCustomElements, LazyLoadOptions, GlobalThisWithPuppeteerEnv } from './lazyLoad';
+export { makeDefineCustomElements } from './lazyLoad';
+export { LitElement } from './LitElement';
+export type { PublicLitElement } from './PublicLitElement';
+export type { Runtime, RuntimeOptions, DevOnlyGlobalRuntime, DevOnlyGlobalComponentRefCallback } from './makeRuntime';
+export { makeRuntime } from './makeRuntime';
+export type { EventHandler } from './jsx/baseTypes';
+export * from './jsx/types';
+export { safeClassMap, safeStyleMap, deferLoad, deferredLoaders, directive, live } from './jsx/directives';
+export { nothing, noChange, setAttribute, stringOrBoolean } from './jsx/utils';
+export { noShadowRoot } from './utils';
+export { makeReactWrapperFactory, getReactWrapperOptions } from './wrappersUtils';
+export { renderElement } from './render';