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

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,7 +34,7 @@ type ComponentLifecycle = {
  * only.
  */
 export declare class LitElement extends OriginalLitElement implements ComponentLifecycle {
-    /** @internal */
+    /** @private */
     static runtime: Runtime;
     static tagName: string;
     /**
@@ -54,7 +55,7 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * loading logic calls document.createElement(), it temporary sets this static
      * property.
      *
-     * @internal
+     * @private
      * */
     static lazy: ProxyComponent | undefined;
     static readonly lumina = true;
@@ -78,43 +79,35 @@ 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
      */
-    manager: import("@arcgis/components-controllers").ControllerManager<never>;
+    readonly _controllers: Set<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 */
+    readonly manager: ControllerManager;
+    /** @private */
     _postLoad: ProxyComponent["_postLoad"];
     /**
      * 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
+     * @private
      */
     _ancestorLoad: ProxyComponent["_ancestorLoad"];
     private _originalShouldUpdate?;
@@ -229,6 +222,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.js

@@ -1,9 +1,16 @@
-import {
-  PropertyFlags,
-  lazyMetaGroupJoiner,
-  lazyMetaItemJoiner,
-  lazyMetaSubItemJoiner
-} from "./chunk-PGHUBTOM.js";
+const lazyMetaGroupJoiner = ";";
+const lazyMetaItemJoiner = ",";
+const lazyMetaSubItemJoiner = ":";
+var PropertyFlags = /* @__PURE__ */ ((PropertyFlags2) => {
+  PropertyFlags2[PropertyFlags2["ATTRIBUTE"] = 1] = "ATTRIBUTE";
+  PropertyFlags2[PropertyFlags2["REFLECT"] = 2] = "REFLECT";
+  PropertyFlags2[PropertyFlags2["BOOLEAN"] = 4] = "BOOLEAN";
+  PropertyFlags2[PropertyFlags2["NUMBER"] = 8] = "NUMBER";
+  PropertyFlags2[PropertyFlags2["STATE"] = 16] = "STATE";
+  PropertyFlags2[PropertyFlags2["READ_ONLY"] = 32] = "READ_ONLY";
+  PropertyFlags2[PropertyFlags2["NO_ACCESSOR"] = 64] = "NO_ACCESSOR";
+  return PropertyFlags2;
+})(PropertyFlags || {});
 export {
   PropertyFlags,
   lazyMetaGroupJoiner,

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>;
@@ -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 function 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,153 @@
+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 {
+    protected _callbacks: {
+        readonly [KEY in keyof Omit<ControllerLifecycleMethods, "controllerRemoved">]-?: NonNullable<ControllerLifecycleMethods[KEY]>[];
+    };
+    protected _ready: Deferred<Exports>;
+    private _lifecycleCleanups;
+    /** @private */
+    assignedProperty?: string | false;
+    connectedCalled: boolean;
+    protected _loadCalled: 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;
+    private _exports;
+    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;
+    private _exportWatchers;
+    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;
+    private _callLifecycle;
+}
+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,59 @@
+import { Controller } from './Controller';
+import { BaseController } from './types';
+import { LitElement } from '../LitElement';
+export declare function setAmbientComponent(component: LitElement): void;
+export declare function retrieveComponent(name?: string): LitElement;
+export declare function 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 function retrieveParentControllers(): readonly BaseController[];
+export declare function 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;
+/** @deprecated */
+export declare let shouldBypassGetter: boolean;
+export declare let shouldBypassReadOnly: boolean;
+/**
+ * Permits updating read-only properties
+ *
+ * @see https://qawebgis.esri.com/components/lumina/properties#read-only-properties
+ */
+export declare function bypassReadOnly<T = void>(callback: () => T): T | void;
+/**
+ * @deprecated see https://qawebgis.esri.com/components/lumina/properties#get-set-properties
+ */
+export declare const bypassSetter: typeof bypassReadOnly;
+/**
+ * @deprecated see https://qawebgis.esri.com/components/lumina/properties#get-set-properties
+ */
+export declare function bypassGetter<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,83 @@
+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> {
+    hasDestroy: boolean;
+    destroyed: boolean;
+    private _autoDestroyTimeout?;
+    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
+     */
+    _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 _enforceReadonly;
+    /** @private */
+    _trackedValue: unknown;
+    /** @private */
+    _keyTrackers: ((key: string | undefined, value: unknown) => void)[];
+    /** @private */
+    _firePropTrackers(key: string | undefined, value: unknown): void;
+    /** @private */
+    readonly _accessorGetter: Record<string, (value: unknown, propertyName: string) => unknown>;
+    /** @private */
+    readonly _accessorSetter: Record<string, (newValue: unknown, oldValue: unknown, propertyName: string) => 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 updated() lifecycle hooks.
+     *
+     * @private
+     */
+    _changes?: PropertyValues;
+    /**
+     * Configure a getter or setter for a given \@property/\@state
+     *
+     * Since props are defined on the prototype, they are shared between all
+     * instances of a component. Thus, instead of passing a reference to the
+     * getter/setter function, you should update the
+     * ComponentInternals.getters/setters properties, and then call getSetProxy
+     * to apply the changes to the prototype
+     *
+     * @deprecated
+     */
+    private _getSetProxy;
+    private _exportsStore;
+    /**
+     * 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,2 @@
+export { makeAccessorController, AccessorController, accessorSupport } from './useAccessor';
+export { reEmitEvent } from './reEmitEvent';