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

package/dist/controllers/index.js

@@ -0,0 +1,283 @@
+import { C as Controller, s as setAmbientComponent, i as isPromise, a as setParentController, b as retrieveParentControllers, t as trackKey, w as watch, r as retrieveComponent, d as createEventFactory, P as PropTypes } from "../useWatch-CFtSpNnN.js";
+import { G, h, g, k, f, e } from "../useWatch-CFtSpNnN.js";
+import { u } from "../ControllerManager-B2comd8J.js";
+import { p as proxyExports } from "../proxyExports-Dl5CHmHQ.js";
+import { a, b, c, d, g as g2, r } from "../proxyExports-Dl5CHmHQ.js";
+import { observeAncestorsMutation, isEsriInternalEnv, getElementAttribute, getElementLocales, startLocaleObserver } from "@arcgis/components-utils";
+const makeController = (constructor) => proxy(void 0, constructor);
+const makeGenericController = (constructor) => (component) => proxy(
+  component,
+  /**
+   * GenericController is identical to Controller, in all except for typing.
+   * So dying a type-cast here so as not to needlessly add one more object
+   * to the prototype chain
+   */
+  constructor
+);
+class FunctionalController extends Controller {
+  constructor(component, constructor) {
+    super(component);
+    const originalExports = this.exports;
+    try {
+      setAmbientComponent(this.component);
+      const value = constructor(this.component, this);
+      const constructorChangedExports = this.exports !== originalExports;
+      if (isPromise(value)) {
+        if (!constructorChangedExports) {
+          this.setProvisionalExports(value);
+        }
+        const resolved = value.then((result) => {
+          this.exports = result;
+          super.catchUpLifecycle();
+        }).catch((error) => {
+          this._ready.reject(error);
+          console.error(error);
+        });
+        this.onLoad(async () => await resolved);
+      } else {
+        if (!constructorChangedExports || value !== void 0) {
+          this.exports = value;
+        }
+        queueMicrotask(() => super.catchUpLifecycle());
+      }
+    } catch (error) {
+      this._ready.reject(error);
+      console.error(error);
+    }
+  }
+  /** Noop - will be called in the constructor instead */
+  catchUpLifecycle() {
+    return;
+  }
+}
+const proxy = proxyExports(FunctionalController);
+const useWatchAttributes = (attributes, callback) => new AttributeWatchController(attributes, callback);
+class AttributeWatchController extends Controller {
+  constructor(_attributes, _callback) {
+    super();
+    this._attributes = _attributes;
+    this._callback = _callback;
+    this._observer = new MutationObserver((mutations) => {
+      mutations.forEach((mutation) => {
+        if (_attributes.includes(mutation.attributeName)) {
+          _callback.call(
+            this.component,
+            this.component.el.getAttribute(mutation.attributeName),
+            mutation.oldValue,
+            mutation.attributeName
+          );
+        }
+      });
+    });
+  }
+  hostConnected() {
+    this._attributes.forEach((attribute) => {
+      if (this.component.el.hasAttribute(attribute)) {
+        this._callback.call(this.component, null, this.component.el.getAttribute(attribute), attribute);
+      }
+    });
+    this._observer.observe(this.component.el, {
+      attributes: true,
+      attributeOldValue: true,
+      attributeFilter: this._attributes
+    });
+  }
+  hostDisconnected() {
+    this._observer.disconnect();
+  }
+}
+const load = makeController;
+const toFunction = (Class) => (...args) => {
+  const ambientControllers = retrieveParentControllers();
+  const instance = new Class(...args);
+  setParentController(ambientControllers.at(-1));
+  return instance;
+};
+const useMedia = (query) => makeController((_component, controller) => {
+  const media = globalThis.matchMedia(query);
+  function changed() {
+    controller.exports = media.matches;
+  }
+  changed();
+  controller.onLifecycle(() => {
+    media.addEventListener("change", changed);
+    return () => media.removeEventListener("change", changed);
+  });
+  return void 0;
+});
+const defaultDirection = "ltr";
+const useDirection = () => makeController((component, controller) => {
+  controller.exports = defaultDirection;
+  controller.onLifecycle(() => {
+    function callback() {
+      const dir = getElementAttribute(component.el, "dir", defaultDirection);
+      controller.exports = dir === "rtl" ? "rtl" : "ltr";
+    }
+    callback();
+    return observeAncestorsMutation(component.el, ["dir"], callback);
+  });
+  if (process.env.NODE_ENV !== "production" && isEsriInternalEnv()) {
+    trackKey(
+      component,
+      (resolved) => {
+        if (resolved?.key === "dir") {
+          throw new Error(
+            `Do not assign this controller to a prop called \`dir\` as that will overwrite the \`dir\` attribute on the host element - component should not be setting the \`dir\` attribute on itself. Instead, assign this controller to a property called \`direction\`.`
+          );
+        }
+      },
+      controller.exports
+    );
+  }
+  return void 0;
+});
+const makeT9nController = (getAssetPath) => (options = {}) => (
+  // eslint-disable-next-line @typescript-eslint/promise-function-async
+  makeController((component, controller) => {
+    const locale = getElementLocales(component.el);
+    const pending = {
+      _lang: locale.lang,
+      _t9nLocale: locale.t9nLocale,
+      _loading: true
+    };
+    const componentWithOverrides = component;
+    controller.onLifecycle(
+      () => startLocaleObserver(
+        component.el,
+        () => getAssetPath("./assets"),
+        ({ t9nLocale, t9nStrings, lang }) => {
+          const withoutOverrides = {
+            ...t9nStrings,
+            _lang: lang,
+            _t9nLocale: t9nLocale,
+            _loading: false
+          };
+          controller.exports = withoutOverrides;
+          const label = t9nStrings.componentLabel;
+          if (typeof label === "string" && "label" in component && component.label == null) {
+            component.label ??= label;
+          }
+          applyOverrides(componentWithOverrides.messageOverrides);
+        },
+        options.name
+      )
+    );
+    function applyOverrides(messageOverrides) {
+      const currentValue = controller.exports;
+      const rawMessages = currentValue._original ?? currentValue;
+      const updated = deepMerge(rawMessages, messageOverrides);
+      if (messageOverrides) {
+        updated._original = rawMessages;
+      }
+      controller.exports = updated;
+    }
+    if ("messageOverrides" in componentWithOverrides) {
+      controller.onLifecycle(() => watch(componentWithOverrides, "messageOverrides", applyOverrides));
+    }
+    if (options.blocking) {
+      controller.setProvisionalExports(pending, false);
+      return controller.ready;
+    } else {
+      return pending;
+    }
+  })
+);
+function deepMerge(original, overwrites) {
+  if (!overwrites) {
+    return original;
+  }
+  const merged = { ...original };
+  Object.entries(overwrites).forEach(([key, value]) => {
+    if (typeof value === "object") {
+      merged[key] = deepMerge(original[key], value);
+    } else {
+      merged[key] = value ?? original[key];
+    }
+  });
+  return merged;
+}
+const usePropertyChange = (_component) => propertyChangeController;
+const eventName = "arcgisPropertyChange";
+function propertyChangeController(...toWatch) {
+  const component = retrieveComponent();
+  const eventedComponent = component;
+  let eventEmitter = eventedComponent[eventName];
+  if (component.manager.isLit) {
+    eventEmitter = createEventFactory(eventName, void 0, component);
+    if (process.env.NODE_ENV !== "production" && isEsriInternalEnv()) {
+      if (typeof eventEmitter !== "object" || eventEmitter === null || !("emit" in eventEmitter) || typeof eventEmitter.emit !== "function") {
+        throw new Error(`Expected to find $createEvent static property on Lumina's LitElement"`);
+      }
+    }
+  }
+  if (process.env.NODE_ENV !== "production" && isEsriInternalEnv()) {
+    if (typeof eventEmitter !== "object" || eventEmitter === null || !("emit" in eventEmitter) || typeof eventEmitter.emit !== "function") {
+      throw new Error(
+        `For consistency, usePropertyChange must be assigned to an arcgisPropertyChange property that has an @Event() decorator`
+      );
+    }
+    const allProps = new Set(
+      Object.entries(component.manager.internals.members).filter(([_name, [propType]]) => (propType & PropTypes.Prop) !== 0).map(([name]) => name)
+    );
+    toWatch.forEach((prop) => {
+      if (!allProps.has(prop)) {
+        throw new Error(
+          prop in component ? `For usePropertyChange to emit event on "${prop}" property change, you should add @${component.manager.isLit ? "property" : "Prop"}() to ${prop} in ${component.el.localName}` : `usePropertyChange can't emit event on "${prop}" property change as such property does not exist in ${component.el.localName}`
+        );
+      }
+    });
+  }
+  component.manager.onLoad(
+    () => component.manager.onLifecycle(
+      () => toWatch.map(
+        (name) => (
+          // Casting to 'el' to simplify dynamic prop name typing
+          watch(component, name, () => eventEmitter.emit({ name }))
+        )
+      )
+    )
+  );
+  if (process.env.NODE_ENV !== "production" && isEsriInternalEnv() && component.manager.isLit) {
+    trackKey(
+      component,
+      (resolution) => {
+        if (resolution === void 0 || resolution.isReactive || resolution.key !== eventName) {
+          throw new Error(
+            `For consistency, usePropertyChange must be assigned to an arcgisPropertyChange property and that property should not have @property() or @state() decorators: arcgisPropertyChange = usePropertyChange<this>()("prop1", "prop2");`
+          );
+        }
+      },
+      eventEmitter
+    );
+  }
+  return eventEmitter;
+}
+export {
+  Controller,
+  G as GenericController,
+  a as bypassGetter,
+  b as bypassReadOnly,
+  c as bypassSetter,
+  h as controllerSymbol,
+  d as dynamicGetSet,
+  g2 as getSet,
+  g as isController,
+  k as keyTrackResolve,
+  load,
+  makeController,
+  makeGenericController,
+  makeT9nController,
+  proxyExports,
+  r as readonly,
+  retrieveComponent,
+  toFunction,
+  trackKey,
+  f as trackPropKey,
+  e as trackPropertyKey,
+  u as useControllerManager,
+  useDirection,
+  useMedia,
+  usePropertyChange,
+  useWatchAttributes,
+  watch
+};

package/dist/controllers/load.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Load a value from a promise and provide it to the component
+ *
+ * Documentation: https://qawebgis.esri.com/components/lumina/controllers/load
+ */
+export declare const load: <T>(loader: () => Promise<T>) => T;

package/dist/controllers/proxyExports.d.ts

@@ -0,0 +1,27 @@
+import { Controller } from './Controller';
+import { ControllerLifecycleMethods } from './types';
+/**
+ * If you wish to directly expose the "exports" property of your controller,
+ * rather than the entire controller class, wrap your class definition in
+ * "proxyExports".
+ *
+ * This is especially convenient when your exports is not an object, or it is a
+ * dynamically created object, and so you don't want your Controller's methods
+ * interfering with the keys on the exported value.
+ *
+ * "proxyExports" is the default behavior for all controllers declared using
+ * the makeController()/makeGenericController() function
+ *
+ * @remarks
+ * If using readonly(), and controller updates its exports, the readonly prop
+ * will still get updated
+ *
+ * @remarks
+ * (Advanced) If you wish to use proxyExports() in a class that does not
+ * extend Controller class and does not have a useControllerManager(), then your
+ * class must subclass a class with the following constructor:
+ * `constructor() { setAmbientController(this); }`. This
+ * is necessary for proxyExports() to receive a reference to your object
+ * implicitly, and before any of your default values are assigned.
+ */
+export declare const proxyExports: <Exports, const Parameters extends unknown[]>(Class: new (...args: Parameters) => ControllerLifecycleMethods & Pick<Controller<Exports>, "component" | "exports" | "watchExports">) => ((...args: Parameters) => Exports);

package/dist/controllers/readonly.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Make a @Prop() or @State() readonly (prevent overwriting default value).
+ *
+ * For internal properties, prefer TypeScript's "readonly" modifier instead.
+ *
+ * @example
+ * ```ts
+ * // Defining readonly prop
+ * @Prop({ reflect: true }) prop = readonly('a');
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Overwriting readonly prop internally
+ * bypassReadOnly(()=>{
+ *   this.prop = 'b';
+ * });
+ * ```
+ *
+ * @deprecated see https://qawebgis.esri.com/components/lumina/properties#read-only-properties
+ */
+export declare function readonly<T>(value: T): T;
+/**
+ * Like bypassSetter(), but only bypasses readonly(), rather that
+ * all setters set using getSet()
+ *
+ * @deprecated see https://qawebgis.esri.com/components/lumina/properties#read-only-properties
+ */
+export declare function bypassReadOnly<T = void>(callback: () => T): T | void;

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 { TrackKeyResolution } from './ComponentInternals';
+import { BaseComponent, BaseController } 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
+ * \@Prop() decorator or not
+ */
+export declare function trackKey<T>(hostsCandidates: ((BaseComponent | BaseController)[] | BaseComponent | BaseController) | undefined, onResolved: (resolution: TrackKeyResolution | undefined) => void, defaultValue: T): T;

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 {};