@arcgis/lumina 4.33.0-next.15 → 4.33.0-next.151

package/dist/LitElement.d.ts

@@ -1,9 +1,10 @@
-import type { CSSResultGroup, CSSResultOrNative, PropertyValues } from "lit";
-import { LitElement as OriginalLitElement } from "lit";
-import type { LuminaPropertyDeclaration } from "@arcgis/components-controllers";
-import type { Runtime } from "./runtime";
-import type { ProxyComponent } from "./lazyLoad";
-import type { ToElement } from "./jsx/types";
+import { CSSResultGroup, CSSResultOrNative, PropertyValues, ReactiveController, LitElement as OriginalLitElement } from 'lit';
+import { Runtime } from './makeRuntime';
+import { ProxyComponent } from './lazyLoad';
+import { ToElement } from './jsx/types';
+import { BaseController, LuminaPropertyDeclaration } from './controllers/types';
+import { ControllerManager } from './controllers/ControllerManager';
+import { Controller } from './controllers/Controller';
 type ComponentLifecycle = {
     connectedCallback?: () => void;
     disconnectedCallback?: () => void;
@@ -33,9 +34,19 @@ type ComponentLifecycle = {
  * only.
  */
 export declare class LitElement extends OriginalLitElement implements ComponentLifecycle {
-    /** @internal */
-    static runtime: Runtime;
-    static tagName: string;
+    #private;
+    /**
+     * @private
+     * @remarks
+     * We prefix private variables with double underscore to avoid collisions with
+     * subclasses. All runtime properties that start with underscore are mangled
+     * in production build, so collision avoidance is mainly important to avoid
+     * triggering TypeScript errors.
+     */
+    static __runtime: Runtime;
+    /** @private */
+    static __tagName: string;
+    static elementProperties: Map<PropertyKey, LuminaPropertyDeclaration>;
     /**
      * Customize Lit's default style handling to support non-shadow-root styles
      */
@@ -49,14 +60,15 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * only to satisfy the type checker.
      */
     options?: LuminaPropertyDeclaration | number | [number, LuminaPropertyDeclaration]): void;
+    protected static getPropertyDescriptor(name: PropertyKey, key: string | symbol, options: LuminaPropertyDeclaration): PropertyDescriptor | undefined;
     /**
      * Since we can't pass arguments to web component constructor, before lazy
      * loading logic calls document.createElement(), it temporary sets this static
      * property.
      *
-     * @internal
+     * @private
      * */
-    static lazy: ProxyComponent | undefined;
+    static __lazy: ProxyComponent | undefined;
     static readonly lumina = true;
     /**
      * In lazy build, the actual DOM element differs from the class instance:
@@ -78,50 +90,36 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * const isLazy = this.el !== this;
      * ```
      */
-    el: ToElement<this>;
+    readonly el: ToElement<this>;
     /**
-     * Controller Manager orchestrates all controllers used by this component,
-     * connecting their lifecycle hooks and providing context information.
+     * Controller does not need to be an instance of the Controller class. Any
+     * Lit's Reactive controller will work as well. See examples:
+     * https://lit.dev/docs/composition/controllers/
+     *
+     * @private
+     * @privateRemarks
+     * For most private names I tried to prefix with __ to not conflict with
+     * private names on subclasses. However, Lit already has __controllers private.
      */
-    manager: import("@arcgis/components-controllers").ControllerManager<never>;
+    readonly _controllers: (BaseController | Controller<unknown>)[];
     /**
-     * Map with keys for any properties that have changed since the last
-     * update cycle with previous values.
-     *
-     * Do not access this directly as this value is only set during the update
-     * lifecycle. Instead, use the `changes` property that is provided
-     * to the shouldUpdate(), willUpdate() and didUpdate() lifecycle hooks.
-     *
-     * @internal
-     *
-     * @remarks
-     * The name does not start with `_` because in the future we may configure the
-     * minifier to mangle such properties - but this property is accessed from
-     * outside this package, so should not be mangled.
+     * Controller Manager orchestrates all controllers used by this component,
+     * connecting their lifecycle hooks and providing context information.
      */
-    $changes: PropertyValues;
-    /** @internal */
-    _postLoad: ProxyComponent["_postLoad"];
+    readonly manager: ControllerManager;
+    /** @private */
+    __postLoadDeferred: ProxyComponent["__postLoadDeferred"];
     /**
      * Direct offspring that should be awaited before loaded() is emitted.
      *
      * `attachToAncestor()` will add elements to this array
      *
-     * @internal
+     * @private
      */
-    _offspring: ProxyComponent["_offspring"];
-    /**
-     * Promise that resolves once parent's load() completed. False if there is no
-     * parent
-     *
-     * @internal
-     */
-    _ancestorLoad: ProxyComponent["_ancestorLoad"];
-    private _originalShouldUpdate?;
-    private _enableUpdating;
-    private _postLoaded;
+    __offspringComponents: ProxyComponent["__offspringComponents"];
     constructor();
     connectedCallback(): void;
+    disconnectedCallback(): void;
     /**
      * Overwrite Lit's default behavior of attaching shadow root to the lit
      * element, and instead use this.el to support lazy builds.
@@ -129,13 +127,12 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * Also, support the case when component asked to not use shadow root
      */
     protected createRenderRoot(): DocumentFragment | HTMLElement;
-    /** Do asynchronous component load */
-    private _load;
     /**
      * Overwriting default shouldUpdate simply to get access to
      * "changedProperties" so that we can later provide it to ControllerManager
      */
     protected shouldUpdate(_changedProperties: PropertyValues): boolean;
+    protected update(changedProperties: PropertyValues): void;
     /**
      * A helper for setting event listener on the current component.
      *
@@ -229,6 +226,20 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * });
      */
     componentOnReady(): Promise<this>;
+    /**
+     * Adds a controller to the host, which connects the controller's lifecycle
+     * methods to the host's lifecycle.
+     *
+     * @remarks
+     * Even though Lit's LitElement already has addController,
+     * we overwrite it with a compatible version to have more control over
+     * timing, and to add support for load/loaded lifecycle hooks.
+     */
+    addController(controller: BaseController | ReactiveController): void;
+    /**
+     * Removes a controller from the host.
+     */
+    removeController(controller: BaseController | ReactiveController): void;
 }
 type Listener<ThisType, EventType> = ((this: ThisType, event: EventType) => unknown) | {
     handleEvent(event: EventType): unknown;

package/dist/config.d.ts

@@ -12,12 +12,10 @@ export declare const lazyMetaSubItemJoiner = ":";
  * object, we pass it a compact number, that gets converted back to an object
  * in createProperty() at runtime.
  */
-export declare enum PropertyFlags {
-    ATTRIBUTE = 1,
-    REFLECT = 2,
-    BOOLEAN = 4,
-    NUMBER = 8,
-    STATE = 16,
-    READ_ONLY = 32,
-    NO_ACCESSOR = 64
-}
+export declare const propertyFlagAttribute: number;
+export declare const propertyFlagReflect: number;
+export declare const propertyFlagBoolean: number;
+export declare const propertyFlagNumber: number;
+export declare const propertyFlagState: number;
+export declare const propertyFlagReadOnly: number;
+export declare const propertyFlagNoAccessor: number;

package/dist/config.js

@@ -1,12 +1,22 @@
-import {
-  PropertyFlags,
-  lazyMetaGroupJoiner,
-  lazyMetaItemJoiner,
-  lazyMetaSubItemJoiner
-} from "./chunk-PGHUBTOM.js";
+const lazyMetaGroupJoiner = ";";
+const lazyMetaItemJoiner = ",";
+const lazyMetaSubItemJoiner = ":";
+const propertyFlagAttribute = 1 << 0;
+const propertyFlagReflect = 1 << 1;
+const propertyFlagBoolean = 1 << 2;
+const propertyFlagNumber = 1 << 3;
+const propertyFlagState = 1 << 4;
+const propertyFlagReadOnly = 1 << 5;
+const propertyFlagNoAccessor = 1 << 6;
 export {
-  PropertyFlags,
   lazyMetaGroupJoiner,
   lazyMetaItemJoiner,
-  lazyMetaSubItemJoiner
+  lazyMetaSubItemJoiner,
+  propertyFlagAttribute,
+  propertyFlagBoolean,
+  propertyFlagNoAccessor,
+  propertyFlagNumber,
+  propertyFlagReadOnly,
+  propertyFlagReflect,
+  propertyFlagState
 };

package/dist/context.d.ts

@@ -1,5 +1,5 @@
-import { type ControllerHost } from "@arcgis/components-controllers";
-import { ContextConsumer, ContextProvider, type Context, type ContextType } from "@lit/context";
+import { ContextConsumer, ContextProvider, Context, ContextType } from '@lit/context';
+import { ReactiveControllerHost } from 'lit';
 interface ContextProviderOptions<C extends Context<unknown, unknown>> {
     context: C;
     initialValue?: ContextType<C>;
@@ -14,7 +14,7 @@ interface ContextConsumerOptions<C extends Context<unknown, unknown>> {
  *
  * @see https://lit.dev/docs/data/context/
  */
-export declare function useContextProvider<C extends Context<unknown, unknown>>(options: ContextProviderOptions<C>): ContextProvider<C>;
+export declare const useContextProvider: <C extends Context<unknown, unknown>>(options: ContextProviderOptions<C>) => ContextProvider<C>;
 /**
  * Wrapper for Lit's ContextConsumer controller to provide lazy-loading compatibility.
  *
@@ -22,5 +22,15 @@ export declare function useContextProvider<C extends Context<unknown, unknown>>(
  *
  * FEATURE: wrap this in proxyExports to improve DX, or keep it simple?
  */
-export declare function useContextConsumer<C extends Context<unknown, unknown>>(options: ContextConsumerOptions<C>): ContextConsumer<C, ControllerHost & HTMLElement>;
+export declare const useContextConsumer: <C extends Context<unknown, unknown>>(options: ContextConsumerOptions<C>) => ContextConsumer<C, LitContextHost>;
+/**
+ * Lit context wasn't written with lazy loading proxy in mind. For it to
+ * work correctly, we must provide the DOM-attached element as the host element.
+ * Events will be fired/listened on it.
+ *
+ * At the same time, .addController() and .requestUpdate() methods will be
+ * called on it. We had to implement these on the lazy proxy to redirect the
+ * calls to the actual LitElement.
+ */
+type LitContextHost = HTMLElement & ReactiveControllerHost;
 export {};

package/dist/controllers/Controller.d.ts

@@ -0,0 +1,147 @@
+import { Deferred } from '@arcgis/components-utils';
+import { BaseController, ControllerLifecycleMethods, controllerSymbol } from './types';
+import { use, useRef, useRefSync } from './ControllerInternals';
+import { PropertyValues } from 'lit';
+import { LitElement } from '../LitElement';
+/**
+ * Base class for Controllers defined using a class rather than a function.
+ * Defining controller using makeController() function is more succinct for smaller
+ * controllers. For controllers that need to declare several methods, or need
+ * more flexibility, this class may be used
+ *
+ * See ./examples.tsx for many example controllers and their usages.
+ */
+export declare abstract class Controller<Exports = never> implements BaseController {
+    #private;
+    /** @private */
+    protected __ready: Deferred<Exports>;
+    /** @private */
+    __assignedProperty?: string | false;
+    connectedCalled: boolean;
+    loadedCalled: boolean;
+    readonly [controllerSymbol] = true;
+    component: LitElement;
+    ready: Promise<Exports>;
+    constructor(component?: LitElement);
+    /**
+     * If controller is being added dynamically, after the component
+     * construction, then trigger connected and load right away
+     */
+    catchUpLifecycle(): void;
+    get exports(): Exports;
+    /**
+     * Set controller's exports property (for usage with proxyExports()) and mark
+     * controller as ready (for usage in other controllers). Also, triggers
+     * re-render of the component
+     */
+    set exports(exports: Exports);
+    /**
+     * If controller needs to await a promise before it's exports are fully ready
+     * but it wishes to make some limited exports available before then,
+     * this method can be used.
+     *
+     * This is useful for permitting a limited usage of the controller in default
+     * values of properties or in component constructor.
+     *
+     * In order to help detect bugs, trying to access a prop on the exports value
+     * that does not exist will throw an error (in development only). This is
+     * useful to detect usages of controller that forgot to await it's exports.
+     * (the "value in this.myController" check won't cause an exception though)
+     *
+     * @param proxy [true] - whether to throw an error if unknown property is
+     *   accessed before the controller is loaded.
+     */
+    setProvisionalExports(exports: Exports, proxy?: boolean): void;
+    setProvisionalExports(exports: Exports extends object ? Partial<Exports> : Exports, proxy?: boolean): void;
+    setProvisionalExports<Props extends keyof Exports>(exports: Pick<Exports, Props>, proxy?: boolean): void;
+    watchExports(callback: (exports: Exports) => void): () => void;
+    /**
+     * A flexible utility for making sure a controller is loaded before it's used,
+     * regardless of how or where a controller was defined:
+     *
+     * @example
+     * makeGenericController(async (component, controller) => {
+     *   // Await some controller from the component:
+     *   await controller.use(component.someController);
+     *   // Initialize new controllers
+     *   await controller.use(load(importCoreReactiveUtils));
+     *   await controller.use(new ViewModelController(component,newWidgetsHomeHomeViewModel));
+     *   await controller.use(someController(component));
+     * });
+     *
+     * @remarks
+     * If your controller is not async, and you are not creating it async, then
+     * you are not required to use controller.use - you can use it directly.
+     * Similarly, accessing controllers after componentWillLoad callback does not
+     * require awaiting them as they are guaranteed to be loaded by then.
+     */
+    get use(): typeof use;
+    /**
+     * Just like controller.use, but returns the controller itself, rather than it's
+     * exports
+     *
+     * Use cases:
+     * - You have a controller and you want to make sure it's loaded before you
+     *   try to use it
+     * - Your controller is not using exports, so you wish to access some props on
+     *   it directly
+     * - You have a controller exports only, and you want to retrieve the
+     *   controller itself. This is useful if you wish to call .watchExports() or
+     *   some other method on the controller
+     */
+    get useRef(): typeof useRef;
+    /**
+     * Like useRef, but doesn't wait for the controller to get ready
+     *
+     * @private
+     */
+    get useRefSync(): typeof useRefSync;
+    controllerRemoved(): void;
+    onConnected(callback: NonNullable<ControllerLifecycleMethods["hostConnected"]>): void;
+    onDisconnected(callback: NonNullable<ControllerLifecycleMethods["hostDisconnected"]>): void;
+    onLoad(callback: NonNullable<ControllerLifecycleMethods["hostLoad"]>): void;
+    onLoaded(callback: NonNullable<ControllerLifecycleMethods["hostLoaded"]>): void;
+    onUpdate(callback: NonNullable<ControllerLifecycleMethods["hostUpdate"]>): void;
+    onUpdated(callback: NonNullable<ControllerLifecycleMethods["hostUpdated"]>): void;
+    onDestroy(callback: NonNullable<ControllerLifecycleMethods["hostDestroy"]>): void;
+    onLifecycle(callback: NonNullable<ControllerLifecycleMethods["hostLifecycle"]>): void;
+    /** @private */
+    triggerConnected(): void;
+    /** @private */
+    triggerDisconnected(): void;
+    /** @private */
+    triggerLoad(): Promise<void>;
+    /** @private */
+    triggerLoaded(): void;
+    /** @private */
+    triggerUpdate(changes: PropertyValues): void;
+    /** @private */
+    triggerUpdated(changes: PropertyValues): void;
+    /** @private */
+    triggerDestroy(): void;
+    /** @private */
+    triggerLifecycle(): void;
+}
+export declare abstract class GenericControllerType<Exports, Requires = LitElement> extends Controller<Exports> {
+    component: LitElement & Requires;
+    constructor(component: LitElement & Requires);
+}
+/**
+ * If your controller requires some specific properties to be present on the
+ * component, besides what's included in LitElement, use
+ * GenericController over the usual Controller. Use the 2nd generic argument
+ * on this class for specifying what properties your controller expects on the
+ * component
+ *
+ * When using a controller created using GenericController, consumer must
+ * pass in "this" explicitly to the constructor. If controller was
+ * created using Controller, that is not necessary
+ *
+ * @remarks
+ * GenericController class is identical to Controller class in all but typing.
+ * That is why, at runtime GenericController is actually equal to Controller
+ * class.
+ * You can use GenericControllerType type if you wish to reference generic
+ * controller instance type.
+ */
+export declare const GenericController: typeof GenericControllerType;

package/dist/controllers/ControllerInternals.d.ts

@@ -0,0 +1,53 @@
+import { Controller } from './Controller';
+import { BaseController } from './types';
+import { LitElement } from '../LitElement';
+export declare const setAmbientComponent: (component: LitElement) => void;
+export declare const retrieveComponent: (name?: string) => LitElement;
+export declare const setParentController: (controller: BaseController | undefined) => void;
+/**
+ * Get references to controllers this nested controller might have been called
+ * from. The list may include extra controllers, but at least one of them or
+ * the component itself is the parent for this controller.
+ */
+export declare const retrieveParentControllers: () => readonly BaseController[];
+export declare const setAmbientChildController: (controller: BaseController | undefined) => void;
+/**
+ * The type definition has to be duplicated due to this TypeScript error:
+ * "'use' is referenced directly or indirectly in its own type annotation."
+ */
+export declare const use: <Value>(value: Value, watchExports?: (value: NotNever<InferController<Value>>, unsubscribe: () => void) => void) => Promise<NotNever<InferController<Value>>>;
+export declare const useRef: <Value>(value: Value) => Promise<InferController<Value>>;
+export declare const useRefSync: <Value>(value: Value) => InferController<Value> | undefined;
+export declare let shouldBypassReadOnly: boolean;
+/**
+ * Permits updating read-only properties
+ *
+ * @see https://qawebgis.esri.com/components/lumina/properties#read-only-properties
+ */
+export declare const bypassReadOnly: <T = void>(callback: () => T) => T | void;
+/**
+ * @deprecated see https://qawebgis.esri.com/components/lumina/properties#get-set-properties
+ */
+export declare const bypassSetter: <T = void>(callback: () => T) => T | void;
+/**
+ * If passed value is a controller, then return it. Otherwise, assume it's a
+ * proxyExports() result and wrap it into a controller
+ *
+ * This won't type correctly if a proxyExports() controller is exporting a
+ * non-proxyExports() controller
+ */
+type InferController<ControllerOrExports> = ControllerOrExports extends BaseController ? ControllerOrExports & {
+    exports?: unknown;
+    ready?: Promise<void>;
+    watchExports?: Controller["watchExports"];
+} : Controller<ControllerOrExports>;
+/**
+ * If controller never sets it's exports, then it's default exports is "this".
+ * This allows usage of controller.use with controllers that don't have exports
+ */
+type NotNever<T extends {
+    exports?: any;
+}> = T extends {
+    exports: never;
+} ? T : T["exports"];
+export {};

package/dist/controllers/ControllerManager.d.ts

@@ -0,0 +1,68 @@
+import { BaseController } from './types';
+import { GenericController } from './Controller';
+import { PropertyValues } from 'lit';
+import { LitElement } from '../LitElement';
+/**
+ * A manager for all other controllers. It finds all controllers on the
+ * component, loads them, and forwards lifecycle events to them.
+ */
+export declare class ControllerManager extends GenericController<undefined> {
+    #private;
+    hasDestroy: boolean;
+    destroyed: boolean;
+    constructor(component: LitElement);
+    /**
+     * Throws an error if component does not implement destroy() lifecycle, but
+     * tries to use it. This check is only present in development mode
+     *
+     * @private
+     */
+    devOnly$ensureHasDestroy?: () => void;
+    destroy(): Promise<void>;
+    /** @private */
+    _setAutoDestroyTimeout(): void;
+    /**
+     * "readOnly" is not enabled initially since we need to allow to set property
+     * default values in the constructor.
+     *
+     * @private
+     */
+    _isEnforcingReadonly: boolean;
+    /** @private */
+    _trackedValue: unknown;
+    /** @private */
+    _keyTrackers: ((key: string | undefined, value: unknown) => void)[];
+    /** @private */
+    _firePropTrackers(key: string | undefined, value: unknown): void;
+    /**
+     * Map with keys for any properties that have changed since the last
+     * update cycle with previous values.
+     *
+     * Do not access this directly as this value is only set during the update
+     * lifecycle. Instead, use the `changes` property that is provided
+     * to the shouldUpdate(), willUpdate() and updated() lifecycle hooks.
+     *
+     * @private
+     */
+    _changedProperties?: PropertyValues;
+    /**
+     * Associate an exports object with a controller for reverse lookup in
+     * controller.use
+     *
+     * @private
+     */
+    _markExports(controller: BaseController, exports: unknown): void;
+    /** @private */
+    _resolveExports(exports: unknown): BaseController | undefined;
+}
+export declare let autoDestroyOnDisconnectTimeout: number;
+export declare const autoDestroyDisabledPropName = "autoDestroyDisabled";
+export declare const exportsForTests: {
+    setAutoDestroyOnDisconnectTimeout: (timeout: number) => void;
+} | undefined;
+export type LuminaLifecycles = {
+    connectedCallback?: LitElement["connectedCallback"];
+    disconnectedCallback?: LitElement["disconnectedCallback"];
+    load?: () => Promise<void> | void;
+    loaded?: () => void;
+};

package/dist/controllers/accessor/index.d.ts

@@ -0,0 +1,4 @@
+export { reEmitEvent } from './reEmitEvent';
+export { makeAccessorController, AccessorController, reCreateAccessor, makeBinderProxy, getAccessorControllerBoundProperties, } from './useAccessor';
+export { createStore, createLegacyStore } from './store';
+export type { ObservableMap } from './store';