@arcgis/lumina 4.33.0-next.94 → 4.33.0-next.95

package/dist/controllers/trackPropKey.d.ts

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

package/dist/controllers/trackPropertyKey.d.ts

@@ -0,0 +1,28 @@
+import { BaseComponent, 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 \@Prop() or \@State()
+ * decorator - for those, use manager.trackPropKey() instead.
+ *
+ * @example
+ * function trackMe<T>(defaultValue:T, component:BaseComponent):T {
+ *   component.manager.trackPropertyKey(component, (key)=>console.log(key), defaultValue);
+ *   return defaultValue;
+ * }
+ *
+ * class MyComponent extends BaseComponent {
+ *   // Will console log "myProp"
+ *   myProp = trackMe('a', this);
+ * }
+ *
+ */
+export declare function trackPropertyKey<T>(object: BaseComponent | BaseController, 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,182 @@
+import { IHandle } from '@arcgis/components-utils';
+import { ReactiveControllerHost, ReactiveController, PropertyDeclaration, PropertyValues } from 'lit';
+import { LitElement } from '../LitElement';
+/**
+ * Explicitly picking rather than extending everything because the interface
+ * has "[memberName: string]: any;", which ruins type-safety of components
+ *
+ * @deprecated use LitElement instead
+ */
+export type StencilLifecycles = {
+    connectedCallback?: () => void;
+    disconnectedCallback?: () => void;
+    componentWillLoad?: () => Promise<void> | void;
+    componentDidLoad?: () => void;
+    componentShouldUpdate?: (newVal: any, oldVal: any, propName: string) => boolean | void;
+    componentWillUpdate?: () => Promise<void> | void;
+    componentDidUpdate?: () => void;
+};
+/**
+ * @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 implements Use<typeof useHomeViewModel> {
+ * // No need for "implements BaseComponent" as that's already included in
+ * // every controller
+ *
+ * @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 both Lit's Reactive controllers
+ * and Stencil's lifecycle
+ */
+export type ControllerLifecycleMethods = {
+    readonly hostConnected?: ReactiveController["hostConnected"];
+    readonly hostDisconnected?: ReactiveController["hostDisconnected"];
+    readonly hostLoad?: StencilLifecycles["componentWillLoad"];
+    readonly hostLoaded?: StencilLifecycles["componentDidLoad"];
+    /**
+     * 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.
+     *
+     * @remarks
+     * The `changes` parameter will only be present in Lumina, not in Stencil
+     */
+    readonly 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.
+     *
+     * @remarks
+     * The `changes` parameter will only be present in Lumina, not in Stencil
+     */
+    readonly 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.
+ */
+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
+     * In Stencil:
+     * This method will re-render your component. All passed parameters are ignored
+     *
+     * In Lit:
+     * 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;
+};
+/**
+ * A reference to Lit's map of changed properties that triggered the update
+ */
+export type LitElementWithChangedPropertiesMap = {
+    $changes: PropertyValues;
+};
+/**
+ * An event emitter object
+ */
+export type EventEmitter<T = undefined> = {
+    emit(payload: T extends undefined ? void : T): CustomEvent<T>;
+};
+/**
+ * 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,11 @@
+import { BaseComponent, EventEmitter } from './types';
+type PropertyChangeController<Component extends BaseComponent> = <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 BaseComponent>(_component?: BaseComponent) => 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:
+     *   @Prop() 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/useWatch.d.ts

@@ -0,0 +1,27 @@
+import { BaseComponent } from './types';
+/**
+ * Dynamically set a watcher for any reactive property
+ *
+ * @example
+ * ```ts
+ * this.manager.onLifecycle(()=>
+ *   watch(this, "myProp", (newValue,oldValue)=>console.log(newValue,oldValue))
+ * )
+ * ```
+ *
+ * @remarks
+ * If you are in Lit, you should prefer the willUpdate() lifecycle method
+ * over watch(). willUpdate() is going to be more memory-efficient, and more
+ * flexible (can watch multiple props at once or provide dynamic prop name)
+ *
+ * ```ts
+ * willUpdate(changes: PropertyValues<this>) {
+ *   if (changes.has('firstName') || changes.has('lastName')) {
+ *     this.sha = computeSHA(`${this.firstName} ${this.lastName}`);
+ *   }
+ * }
+ * ```
+ *
+ * @deprecated see https://qawebgis.esri.com/components/lumina/lifecycle#willupdate and https://qawebgis.esri.com/components/lumina/controllers/lifecycle
+ */
+export declare function watch<Component extends BaseComponent, Property extends keyof Component>(component: Component, property: Property, callback: (newValue: Component[Property], oldValue: Component[Property], property: Property) => void): () => void;

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,4 @@
-import { BaseComponent, EventEmitter } from '@arcgis/components-controllers';
+import { BaseComponent, EventEmitter } from './controllers/types';
 /**
  * While these defaults don't match DOM defaults (all false), they match
  * Stencil and Shoelace defaults. Also, they make more sense for our

package/dist/decorators.d.ts

@@ -1,4 +1,4 @@
-import { LuminaPropertyDeclaration } from '@arcgis/components-controllers';
+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

package/dist/index.d.ts

@@ -6,8 +6,8 @@ export type { DefineCustomElements, LazyLoadOptions, GlobalThisWithPuppeteerEnv
 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 { 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';

package/dist/index.js

@@ -1,12 +1,14 @@
-import { retrieveComponent, trackKey, keyTrackResolve, useControllerManager } from "@arcgis/components-controllers";
 import { ContextProvider, ContextConsumer } from "@lit/context";
-import { isEsriInternalEnv, Deferred, camelToKebab } from "@arcgis/components-utils";
+import { r as retrieveComponent } from "./useWatch-CFtSpNnN.js";
+import { c } from "./useWatch-CFtSpNnN.js";
 import { state } from "@lit/reactive-element/decorators/state.js";
 import { property as property$1 } from "@lit/reactive-element/decorators/property.js";
 import { n as noShadowRoot, a as attachToAncestor } from "./utils-GhKD5Lo-.js";
 import { m } from "./utils-GhKD5Lo-.js";
+import { Deferred, isEsriInternalEnv, camelToKebab } from "@arcgis/components-utils";
 import { LitElement as LitElement$1, isServer, noChange as noChange$1 } from "lit";
 import { PropertyFlags } from "./config.js";
+import { u as useControllerManager } from "./ControllerManager-B2comd8J.js";
 import { classMap } from "lit-html/directives/class-map.js";
 import { styleMap } from "lit/directives/style-map.js";
 import { directive as directive$1, Directive } from "lit-html/directive.js";
@@ -24,44 +26,6 @@ function useContextConsumer(options) {
   component.addController(controller);
   return controller;
 }
-const createEventFactory = (eventName = "", options = {}, component = retrieveComponent()) => {
-  const emitter = {
-    emit: (payload) => {
-      if (process.env.NODE_ENV !== "production" && isEsriInternalEnv() && !component.el.isConnected) {
-        console.warn(`Trying to emit an ${eventName} event on a disconnected element ${component.el.localName}`);
-      }
-      if (eventName === "") {
-        keyTrackResolve();
-        if (process.env.NODE_ENV !== "production" && isEsriInternalEnv() && eventName === "") {
-          throw new Error("Unable to resolve event name from property name");
-        }
-      }
-      const event = new CustomEvent(eventName, {
-        detail: payload,
-        cancelable: true,
-        bubbles: true,
-        composed: true,
-        ...options
-      });
-      component.el.dispatchEvent(event);
-      return event;
-    }
-  };
-  if (eventName === "") {
-    trackKey(
-      void 0,
-      (resolution) => {
-        if (process.env.NODE_ENV !== "production" && isEsriInternalEnv() && resolution === void 0) {
-          throw new Error(`createEvent must be called in property default value only`);
-        }
-        eventName = resolution.key;
-      },
-      emitter
-    );
-  }
-  return emitter;
-};
-const createEvent = createEventFactory.bind(null, "");
 const property = property$1;
 const method = void 0;
 const emptyFunction = () => void 0;
@@ -249,7 +213,6 @@ class LitElement extends LitElement$1 {
     return this;
   }
 }
-LitElement.$createEvent = createEventFactory;
 if (process.env.NODE_ENV !== "production" && isEsriInternalEnv()) {
   const globalWithLit = globalThis;
   globalWithLit.litIssuedWarnings ??= /* @__PURE__ */ new Set();
@@ -390,7 +353,7 @@ export {
   bindBooleanAttribute,
   bindEvent,
   bindProperty,
-  createEvent,
+  c as createEvent,
   deferLoad,
   deferredLoaders,
   directive,

package/dist/lazyLoad.d.ts

@@ -1,7 +1,7 @@
 import { Deferred } from '@arcgis/components-utils';
 import { LitElement } from './LitElement';
-import { Runtime } from './runtime';
-import { ControllerManager } from '@arcgis/components-controllers';
+import { Runtime } from './makeRuntime';
+import { ControllerManager } from './controllers/ControllerManager';
 /**
  * Defines lazy-loading proxy components for all web components in this package.
  *

package/dist/makeRuntime.d.ts

@@ -0,0 +1,109 @@
+import { CSSResult } from 'lit';
+import { LitElement } from './LitElement';
+/**
+ * `@arcgis/lumina` package may be bundled once but used by multiple packages with
+ * different configuration options. For that reason, the configuration options
+ * cannot be a global object, but has to be an object that you pass around.
+ */
+export type Runtime = RuntimeOptions & {
+    /**
+     * Get the base path to where the package assets can be found.
+     * By default, the package asset path is set to `https://js.arcgis.com/<simplified-package-name>/<released-verion>/`.
+     * We are hosting our assets on a CDN (Content Delivery Network) to ensure fast and reliable access.
+     * It is CORS-enabled, so you can load the assets from any domain.
+     * Use "setAssetPath(path)" if the path needs to be customized.
+     */
+    readonly getAssetPath: (suffix: string) => string;
+    /**
+     * Used to manually set the base path where package assets (like localization
+     * and icons) can be found.
+     *
+     * By default, the package asset path is set to `https://js.arcgis.com/<simplified-package-name>/<released-verion>/`.
+     * For example, `https://js.arcgis.com/map-components/4.30/`.
+     * We are hosting our assets on a CDN (Content Delivery Network) to ensure fast and reliable access.
+     * It is CORS-enabled, so you can load the assets from any domain.
+     * This is the recommended way to load the assets and avoid bundling them with your application.
+     * It means that by default, you don't need to use "setAssetPath" since the path is already set.
+     *
+     * However, if you need to host the assets locally, you can use "setAssetPath" to set the base path.
+     * If the script is used as "module", it's recommended to use "import.meta.url",
+     * such as "setAssetPath(import.meta.url)". Other options include
+     * "setAssetPath(document.currentScript.src)", or using a bundler's replace plugin to
+     * dynamically set the path at build time, such as "setAssetPath(process.env.ASSET_PATH)".
+     * But do note that this configuration depends on how your script is bundled, or lack of
+     * bundling, and where your assets can be loaded from. Additionally custom bundling
+     * will have to ensure the static assets are copied to its build directory.
+     */
+    readonly setAssetPath: (path: URL | string) => void;
+    /**
+     * The customElement decorator. Unlike default Lit's decorator this one
+     * provides runtime instance to the LitElement class
+     *
+     * @remarks
+     * You do not need to call this decorator in your component.
+     * It will be added automatically at build time.
+     *
+     * Instead, make sure your component file has the following:
+     * ```ts
+     * declare global {
+     *  interface DeclareElements {
+     *      "arcgis-your-component": ArcgisYourComponent;
+     *   }
+     * }
+     * ```
+     */
+    readonly customElement: (tagName: string, component: typeof LitElement) => void;
+};
+export type RuntimeOptions = {
+    /**
+     * The default asset path to use in NPM and CDN builds.
+     *
+     * This option will be set by Lumina compiler based on the value of the
+     * `assets.defaultPath` option in the `useLumina()` plugin.
+     */
+    readonly defaultAssetPath: string;
+    /**
+     * The attribute that indicates a component has rendered it's content.
+     * Usually this attribute is added after your component's `loaded()` lifecycle
+     * happened. However, during SSR, "hydrated" is added right away on the
+     * server.
+     *
+     * Until element has this attribute, it will have `visibility:hidden` style
+     * applied.
+     *
+     * This option will be set by the Lumina compiler based on the value of
+     * the `css.hydratedAttribute` option in the `useLumina()` plugin.
+     */
+    readonly hydratedAttribute: string;
+    /**
+     * Styles that you wish to make available in each component's shadow root, but
+     * to not apply outside the shadow root
+     *
+     * This option will be set by Lumina compiler based on the value of the
+     * `css.commonStylesPath` option in the `useLumina()` plugin.
+     */
+    readonly commonStyles?: CSSResult;
+};
+/**
+ * The options object will be provided by Lumina compiler at build-time.
+ * It should not be specified in the source code.
+ */
+export declare function makeRuntime(options?: RuntimeOptions): Runtime;
+/**
+ * Exposing the reference to the runtime globally when in tests or development.
+ * This is primarily for usage by dynamically created components in tests
+ *
+ * @private
+ */
+export type DevOnlyGlobalRuntime = typeof globalThis & {
+    devOnly$luminaRuntime?: Runtime;
+};
+/**
+ * Called from the component constructor when in development or test mode.
+ * Used primarily by mount to get a reference to the rendered component.
+ *
+ * @private
+ */
+export type DevOnlyGlobalComponentRefCallback = typeof globalThis & {
+    devOnly$luminaComponentRefCallback?: (component: LitElement) => void;
+};