@arcgis/lumina 4.31.0-next.84

package/LICENSE.md

@@ -0,0 +1,13 @@
+# Licensing
+
+COPYRIGHT © 2024 Esri
+
+All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
+
+This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement. You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
+
+See use restrictions at http://www.esri.com/legal/pdfs/mla_e204_e300/english
+
+For additional information, contact: Environmental Systems Research Institute, Inc. Attn: Contracts and Legal Services Department 380 New York Street Redlands, California, USA 92373 USA
+
+email: contracts@esri.com

package/README.md

@@ -0,0 +1,21 @@
+# ArcGIS Maps SDK for JavaScript - Lit
+
+**No Esri Technical Support included.**
+
+Package that is part of the [ArcGIS Maps SDK for JavaScript](https://developers.arcgis.com/javascript).
+
+It is not intended to be used directly, but rather used as a dependency by other packages in the SDK.
+
+## License
+
+COPYRIGHT © 2024 Esri
+
+All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
+
+This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement. You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
+
+See use restrictions at <http://www.esri.com/legal/pdfs/mla_e204_e300/english>
+
+For additional information, contact: Environmental Systems Research Institute, Inc. Attn: Contracts and Legal Services Department 380 New York Street Redlands, California, USA 92373 USA
+
+email: contracts@esri.com

package/dist/LitElement.d.ts

@@ -0,0 +1,213 @@
+import type { CSSResultGroup, CSSResultOrNative, PropertyValues } from "lit";
+import { LitElement as OriginalLitElement } from "lit";
+import type { LitElementPropertyDeclaration } from "@arcgis/components-controllers";
+import type { Runtime } from "./runtime";
+import type { ProxyComponent } from "./lazyLoad";
+type ComponentLifecycle = {
+    connectedCallback?: () => void;
+    disconnectedCallback?: () => void;
+    load?: () => Promise<void> | void;
+    loaded?: () => void;
+};
+/**
+ * Base Lit class that should be used by all components instead of the original
+ * Lit element.
+ *
+ * This class:
+ * - Handles being used in a lazy-loading build
+ * - Connects to the Controller Manager
+ * - Provides load/loaded lifecycle hooks
+ *   (like componentWillLoad and componentDidLoad in Stencil)
+ * - Provides a .listen() method like Stencil's \@Listen decorator
+ *
+ * @remarks
+ * Even though all components will extend this class, it is not exposed in the
+ * public typings as we do not want to expose internal methods like
+ * addController() and connectedCallback() to the public typings.
+ *
+ * Instead, `@arcgis/lumina-compiler` will make it appear that your component
+ * extends `PublicLitElement`.
+ *
+ * `PublicLitElement` will never be called at runtime - it exists for typings
+ * only.
+ */
+export declare class LitElement extends OriginalLitElement implements ComponentLifecycle {
+    /** @internal */
+    static runtime: Runtime;
+    static tagName: string;
+    static finalizeStyles(styles?: CSSResultGroup): CSSResultOrNative[];
+    static createProperty(name: PropertyKey, 
+    /**
+     * While in vanilla Lit this type is always LitElementPropertyDeclaration,
+     * in Lumina it is always number or
+     * [number,LitElementPropertyDeclaration], so we don't even check for the
+     * LitElementPropertyDeclaration case. LitElementPropertyDeclaration is here
+     * only to satisfy the type checker.
+     */
+    options?: LitElementPropertyDeclaration | number | [number, LitElementPropertyDeclaration]): void;
+    /** @internal */
+    static lazy: ProxyComponent | undefined;
+    static readonly lumina = true;
+    /**
+     * In lazy build, the actual DOM element differs from the class instance:
+     * - "this.el" is a proxy custom element - it's physically present in the DOM
+     *   even before the Lit component is loaded.
+     * - "this" is the actual Lit component - in case of Lazy builds, it's
+     *   never directly attached to the DOM. Instead, all interactions with the
+     *   proxy are forwarded to the actual Lit component. And, when Lit wants to
+     *   render, it renders into the shadow root of the proxy.
+     *
+     * "this.el" should be used instead of "this" for all things involving the
+     * DOM (addEventListener, querySelector, children, setAttribute,
+     * MutationObserver, etc...)
+     *
+     * @example
+     * ```ts
+     * // Generally, you shouldn't have to write logic specific to lazy or non-lazy
+     * // build, but if you have to, you can detect if you are in a lazy build like so:
+     * const isLazy = this.el !== this;
+     * ```
+     *
+     * @remarks
+     * Since we can't pass arguments to web component constructor, we are using
+     * a temporary static property instead
+     */
+    el: HTMLElement;
+    /**
+     * Controller Manager orchestrates all components used by this component,
+     * connecting their lifecycle hooks and providing context information.
+     */
+    manager: import("@arcgis/components-controllers").ControllerManager<never>;
+    /**
+     * 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.
+     */
+    $changes: PropertyValues;
+    /** @internal */
+    _postLoad: ProxyComponent["_postLoad"];
+    /**
+     * Direct offspring that should be awaited before loaded() is emitted.
+     *
+     * `attachToAncestor()` will add elements to this array
+     *
+     * @internal
+     */
+    _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;
+    constructor();
+    connectedCallback(): void;
+    /** Do asynchronous component load */
+    private _load;
+    /**
+     * Overwrite Lit's default behavior of attaching shadow root to the lit
+     * element, and instead use this.el to support lazy builds.
+     *
+     * Also, support the case when component asked to not use shadow root
+     */
+    protected createRenderRoot(): DocumentFragment | HTMLElement;
+    /**
+     * Overwriting default shouldUpdate simply to get access to
+     * "changedProperties" so that we can later provide it to ControllerManager
+     */
+    protected shouldUpdate(_changedProperties: PropertyValues): boolean;
+    /**
+     * A helper for setting event listener on the current component.
+     *
+     * The event listener will be removed automatically when component
+     * disconnects, and added back if component re-comments, thus you don't have
+     * to clean it up manually.
+     *
+     * @remarks
+     * This listens for any event on the component or one of it's children.
+     * If you only want to listen for events originating from the component itself
+     * use `const isSelf = event.target === this.el;` to check.
+     *
+     * @example
+     * ```tsx
+     * constructor() {
+     *   // Handle click will only be called while component is connected
+     *   this.listen('click', this.handleClick);
+     * }
+     * handleClick(event: MouseEvent):void {
+     *   console.log('clicked');
+     * }
+     * ```
+     */
+    listen<K extends keyof HTMLElementEventMap>(type: K, listener: (this: this, event: HTMLElementEventMap[K]) => unknown, options?: AddEventListenerOptions | boolean): void;
+    listen(type: string, listener: (this: this, event: Event) => unknown, options?: AddEventListenerOptions | boolean): void;
+    /**
+     * A helper for setting even listener on any element (or window / document).
+     *
+     * The event listener will be removed automatically when component
+     * disconnects, and added back if component re-comments, thus you don't have
+     * to clean it up manually.
+     *
+     * Use cases:
+     * - Listening for pointer events on the top-most element
+     * - Listening to events that are emitted exclusively on document/window/body
+     * - Imperatively listening for events on children components
+     * - Listening for events on non-Element objects (like Worker, WebSocket, etc)
+     * - Your component could emit a custom event, and then listen for that event
+     *   on the window. This lets consumer of the component handle the event and
+     *   stop propagation - and if they didn't and event reached the window, your
+     *   component can handle the event itself using the default behavior.
+     *
+     * @example
+     * ```tsx
+     * constructor() {
+     *   // Handle click will only be called while component is connected
+     *   this.listenOn(window, 'click', this.handleWindowClick);
+     * }
+     * handleWindowClick(event: MouseEvent):void {
+     *   console.log('clicked');
+     * }
+     * ```
+     */
+    listenOn<Name extends keyof WindowEventMap>(target: Window, name: Name, listener: Listener<this, WindowEventMap[Name] & {
+        currentTarget: Window;
+    }>, options?: AddEventListenerOptions | boolean): void;
+    listenOn<Name extends keyof DocumentEventMap>(target: Document, name: Name, listener: Listener<this, DocumentEventMap[Name] & {
+        currentTarget: Document;
+    }>, options?: AddEventListenerOptions | boolean): void;
+    listenOn<Name extends keyof HTMLElementEventMap>(target: HTMLElement, name: Name, listener: Listener<this, HTMLElementEventMap[Name] & {
+        currentTarget: HTMLElement;
+    }>, options?: AddEventListenerOptions | boolean): void;
+    listenOn<EventType extends Event = CustomEvent<"Provide type like this.listenOn<CustomEvent<MyType>>() to get type-checked payload type">, Target = EventTarget>(target: Target, name: string, listener: Listener<this, EventType & {
+        currentTarget: Target;
+    }>, options?: AddEventListenerOptions | boolean): void;
+    /**
+     * Create a promise that resolves once component is fully loaded.
+     *
+     * @example
+     * const map = document.createElement('arcgis-map');
+     * document.body.append(map);
+     * map.componentOnReady().then(() => {
+     *   console.log('Map is ready to go!');
+     * });
+     */
+    componentOnReady(): Promise<this>;
+}
+type Listener<ThisType, EventType> = ((this: ThisType, event: EventType) => unknown) | {
+    handleEvent(event: EventType): unknown;
+};
+export {};

package/dist/PublicLitElement.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The base public interface for all `@arcgis/lumina` components
+ */
+export declare class PublicLitElement extends HTMLElement {
+    /**
+     * Create a promise that resolves once component is fully loaded.
+     *
+     * @example
+     * const map = document.createElement("arcgis-map");
+     * document.body.append(map);
+     * map.componentOnReady().then(() => {
+     *   console.log("Map is ready to go!");
+     * });
+     */
+    componentOnReady(): Promise<this>;
+}

package/dist/chunk-CH52Q2MB.js

@@ -0,0 +1,27 @@
+// src/config.ts
+var lazyMetaGroupJoiner = ";";
+var lazyMetaItemJoiner = ",";
+var lazyMetaSubItemJoiner = ":";
+var defaultEventBubbles = true;
+var defaultEventCancelable = true;
+var defaultEventComposed = true;
+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 {
+  lazyMetaGroupJoiner,
+  lazyMetaItemJoiner,
+  lazyMetaSubItemJoiner,
+  defaultEventBubbles,
+  defaultEventCancelable,
+  defaultEventComposed,
+  PropertyFlags
+};

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Configuration options that are shared between `@arcgis/lumina` and
+ * `@arcgis/lumina-compiler`. To avoid the need of loading DOM modules in Node.js,
+ * this file is extracted into a separate entrypoint.
+ */
+export declare const lazyMetaGroupJoiner = ";";
+export declare const lazyMetaItemJoiner = ",";
+export declare const lazyMetaSubItemJoiner = ":";
+/**
+ * While these defaults don't match DOM defaults (all false), they match
+ * Stencil and Shoelace defaults. Also, they make more sense for our
+ * usage (i.e why would you want events to not be cancelable by default?)
+ */
+export declare const defaultEventBubbles = true;
+export declare const defaultEventCancelable = true;
+export declare const defaultEventComposed = true;
+/**
+ * By default in Lit, the `@property()` decorator accepts an object. However, to
+ * keep the bundle size smaller, in production builds, instead of passing it an
+ * 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
+}

package/dist/config.js

@@ -0,0 +1,18 @@
+import {
+  PropertyFlags,
+  defaultEventBubbles,
+  defaultEventCancelable,
+  defaultEventComposed,
+  lazyMetaGroupJoiner,
+  lazyMetaItemJoiner,
+  lazyMetaSubItemJoiner
+} from "./chunk-CH52Q2MB.js";
+export {
+  PropertyFlags,
+  defaultEventBubbles,
+  defaultEventCancelable,
+  defaultEventComposed,
+  lazyMetaGroupJoiner,
+  lazyMetaItemJoiner,
+  lazyMetaSubItemJoiner
+};

package/dist/createEvent.d.ts

@@ -0,0 +1,65 @@
+/**
+ * An event emitter object
+ */
+export type EventEmitter<T = undefined> = {
+    emit(payload: T extends undefined ? void : T): CustomEvent<T>;
+};
+export type EventOptions = {
+    /**
+     * A Boolean indicating whether the event bubbles up through the DOM or not.
+     *
+     * @default true
+     */
+    bubbles?: boolean;
+    /**
+     * A Boolean indicating whether the event is cancelable. Defaults to `true`,
+     * unlike the DOM's default of `false`, as that is the desired behavior most
+     * of the time.
+     *
+     * @default true
+     */
+    cancelable?: boolean;
+    /**
+     * A Boolean value indicating whether or not the event can bubble across the
+     * boundary between the shadow DOM and the regular DOM.
+     *
+     * @default true
+     */
+    composed?: boolean;
+};
+/**
+ * While we don't actually return CustomEvent<T>, only EventEmitter<T>, claiming
+ * that we return CustomElement<T> simplifies typing.
+ *
+ * See:
+ * ```ts
+ * handleClick(event: ArcgisCounter['arcgisClick']): void {
+ * }
+ * ```
+ *
+ * Without it, you would have to do:
+ * ```ts
+ * handleClick(event: ReturnType<ArcgisCounter['arcgisClick']['emit']>): void {
+ * }
+ * ```
+ *
+ * It also simplifies the work for Lumina - having property claim to
+ * be an even makes it easy to find event properties to provide JSX type-checking,
+ * and to find events when doing docs generation.
+ */
+export declare const createEventFactory: <T = undefined>(eventName?: string, options?: EventOptions, component?: import("@arcgis/components-controllers").BaseComponent) => CustomEvent<T> & EventEmitter<T>;
+/**
+ * Creates an event emitter.
+ * Events emitted by your component will be included in the documentation.
+ *
+ * @example
+ * Declaring an event whose payload is of type `number`:
+ *
+ * ```ts
+ * class MyComponent extends LitElement {
+ *   arcgisClick = createEvent<number>();
+ * }
+ * ```
+ *
+ */
+export declare const createEvent: <T = undefined>(options?: EventOptions) => CustomEvent<T> & EventEmitter<T>;

package/dist/decorators.d.ts

@@ -0,0 +1,55 @@
+import type { LitElementPropertyDeclaration } from "@arcgis/components-controllers";
+export { state } from "@lit/reactive-element/decorators/state.js";
+/**
+ * A class field or accessor decorator which creates a reactive property that
+ * reflects a corresponding attribute value. When a decorated property is set
+ * the element will update and render.
+ *
+ * This decorator should only be used for public fields. As public fields,
+ * properties should be considered as primarily settable by element users,
+ * either via attribute or the property itself.
+ *
+ * Generally, properties that are changed by the element should be private or
+ * protected fields and should use the `state()` decorator.
+ *
+ * However, sometimes element code does need to set a public property. This
+ * should typically only be done in response to user interaction, and an event
+ * should be fired informing the user; for example, a checkbox sets its
+ * `checked` property when clicked and fires a `changed` event. Mutating public
+ * properties should typically not be done for non-primitive (object or array)
+ * properties. In other cases when an element needs to manage state, a private
+ * property decorated via the `state()` decorator should be used. When
+ * needed, state properties can be initialized via public properties to
+ * facilitate complex interactions.
+ *
+ * @example
+ *
+ * ```ts
+ * class MyElement {
+ *   \@property()
+ *   clicked = false;
+ * }
+ * ```
+ *
+ * @example
+ * Declaring a readOnly property:
+ *
+ * ```ts
+ * class MyElement {
+ *   \@property({ readOnly: true })
+ *   state: State = "loading";
+ * }
+ * ```
+ */
+export declare const property: (options?: Omit<LitElementPropertyDeclaration, "state">) => PropertyDecorator;
+declare type CustomMethodDecorator<T> = (target: unknown, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
+/**
+ * The `@method()` decorator is used to expose methods on the public API.
+ * Class methods decorated with the `@method()` decorator can be called directly
+ * from the element, meaning they are intended to be callable from the outside.
+ *
+ * @remarks
+ * This decorator does not exist at runtime and is only used as a hint for the
+ * compiler to declare certain methods as public.
+ */
+export declare const method: () => CustomMethodDecorator<any>;

package/dist/devOnlyDetectIncorrectLazyUsages.d.ts

@@ -0,0 +1,11 @@
+import type { LitElement } from "./LitElement";
+/**
+ * When in lazy-build, the actual Lit element is never attached to the DOM.
+ * Instead, a proxy element is present and should be used for all DOM actions.
+ *
+ * In practice, this means using this.el.getAttribute() instead of
+ * this.getAttribute() and etc for each DOM method
+ *
+ * This code does not ship in production builds.
+ */
+export declare function devOnlyDetectIncorrectLazyUsages(LitClass: typeof LitElement): void;

package/dist/hmrSupport.d.ts

@@ -0,0 +1,29 @@
+import type { ModuleNamespace } from "vite/types/hot.js";
+/**
+ * Update web component proxies when a module is updated.
+ *
+ * @remarks
+ * You should not need to call this function directly - it will be inserted
+ * automatically when running in serve mode.
+ */
+export declare function handleHmrUpdate(newModules: (ModuleNamespace | undefined)[]): void;
+export type HmrComponentMeta = {
+    readonly tagName: string;
+    /**
+     * 2nd tuple element ("attribute") is missing when attribute name can be
+     * trivially inferred from the property name (using camelToKebab()).
+     * If 2nd tuple element is empty string, it means the property does not have
+     * an attribute.
+     */
+    readonly properties: (readonly [property: string, attribute: string] | readonly [property: string])[];
+    readonly asyncMethods: readonly string[];
+    readonly syncMethods: readonly string[];
+};
+/**
+ * Update lazy component meta
+ *
+ * @remarks
+ * You should not need to call this function directly - it will be inserted
+ * automatically when running in serve mode.
+ */
+export declare function handleComponentMetaUpdate(meta: HmrComponentMeta): void;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type { EventEmitter, EventOptions } from "./createEvent";
+export { createEvent } from "./createEvent";
+export { state, property, method } from "./decorators";
+export type { HmrComponentMeta } from "./hmrSupport";
+export { handleComponentMetaUpdate, handleHmrUpdate } from "./hmrSupport";
+export type { DefineCustomElements, LazyLoadOptions } from "./lazyLoad";
+export { makeDefineCustomElements } from "./lazyLoad";
+export { LitElement } from "./LitElement";
+export { PublicLitElement } from "./PublicLitElement";
+export type { Runtime, RuntimeOptions, DevOnlyGlobalRuntime, DevOnlyGlobalComponentRefCallback } from "./runtime";
+export { makeRuntime } from "./runtime";
+export * from "./jsx/jsx";
+export { safeClassMap, safeStyleMap } from "./jsx/directives";
+export { noShadowRoot } from "./utils";
+export { createPrototypeProxy } from "./wrappersUtils";