@arcgis/lumina 5.1.0-next.21 → 5.1.0-next.22

package/dist/LitElement.d.ts

@@ -5,6 +5,7 @@ import { ToElement } from './jsx/types.ts';
 import { BaseController, LuminaPropertyDeclaration } from './controllers/types.ts';
 import { ControllerManager } from './controllers/ControllerManager.ts';
 import { Controller } from './controllers/Controller.ts';
+import { FormAssociatedEvents } from './formAssociatedUtils.ts';
 type ComponentLifecycle = {
     connectedCallback?: () => void;
     disconnectedCallback?: () => void;
@@ -117,6 +118,19 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * @private
      */
     __offspringComponents: ProxyComponent["__offspringComponents"];
+    /**
+     * For HMR, if the .elementInternals was created, preserve that element
+     * internals instance across hot reloads. This method lets HMR get a reference
+     * to element internals in a side-effect free way and without adding production
+     * bytes.
+     *
+     * @private
+     */
+    devOnly$PureGetElementInternals?: () => ElementInternals | undefined;
+    /**
+     * @see [MDN ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     */
+    get elementInternals(): ElementInternals;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -157,6 +171,7 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * ```
      */
     listen<K extends keyof HTMLElementEventMap>(name: K, listener: (this: this, event: HTMLElementEventMap[K]) => unknown, options?: AddEventListenerOptions | boolean): void;
+    listen<K extends keyof FormAssociatedEvents>(name: K, listener: (this: this, event: FormAssociatedEvents[K]) => unknown, options?: Omit<AddEventListenerOptions, "capture" | "passive"> | boolean): void;
     listen(name: string, listener: (this: this, event: Event) => unknown, options?: AddEventListenerOptions | boolean): void;
     listen<EventType extends Event = CustomEvent<"Provide type like this.listenOn<ToEvents<ArcgisCounter>['arcgisClick']>() to get type-checked payload type">>(name: string, 
     /**

package/dist/formAssociatedUtils.d.ts

@@ -0,0 +1,49 @@
+import { ProxyComponent } from './lazyLoad.ts';
+import { LitElement } from './LitElement.ts';
+/**
+ * Web platform allows custom elements to define these methods to handle the
+ * corresponding form events. For performance reasons, the engines require that
+ * these methods are present when the customElements.define() is called - it
+ * means that we need to include them in the lazy proxy as well.
+ *
+ * The lazy proxy today only creates the methods proxies the first time a proxy
+ * element of that tag name is created, which is too late.
+ *
+ * We could update the proxy to define the method proxies right away. Some cons
+ * with that:
+ * - In lazy builds, most components are never loaded, so I want to keep the
+ *   per-proxy overhead minimal.
+ * - To handle this form event, the component would need to define a
+ *   corresponding method with a \@method() decorator (to ensure it is present
+ *   on the proxy), and the method needs to be async (so that the lazy proxy
+ *   knows to await component loading before calling the method)
+ *   - If you forget to add \@method(), lazy proxy won't proxy this method. If
+ *     you forget to make it async, lazy proxy will error if the component is
+ *     not loaded yet. These are not obvious constraints from lazy-loading, and
+ *     do not match the examples online/copilot. We may need lint rules about
+ *     this.
+ * - For async methods, the proxy by default will call the method only after this
+ *   component (and all its children) are fully loaded. The component may wish
+ *   to handle these events sooner than that.
+ * - Such API is not composable - if the method needs to be present on the
+ *   component, it is hard for a controller to handle it, creating wiring
+ *   boilerplate.
+ *
+ * To address these concerns, the proxy does the following:
+ * - Always define these methods on the prototype (harmless for
+ *   non-form-associated components). The methods are created once, so no
+ *   per-proxy overhead.
+ * - The proxy methods will wait for component constructor (not load).
+ * - The proxy will emit a corresponding event on itself. The component or any
+ *   controller can choose to listen to these events. The event does not bubble
+ *   and does not compose, so will have minimum visibility outside the component.
+ * - To keep the non-lazy behavior aligned, we also emit such events on itself
+ *   in non-lazy builds.
+ */
+export interface FormAssociatedEvents {
+    luminaFormAssociatedCallback: CustomEvent<readonly [form: HTMLFormElement | null]>;
+    luminaFormDisabledCallback: CustomEvent<readonly [disabled: boolean]>;
+    luminaFormResetCallback: CustomEvent<readonly []>;
+    luminaFormStateRestoreCallback: CustomEvent<readonly [state: unknown, mode: "autocomplete" | "restore"]>;
+}
+export declare function proxyFormMethodsToEvents(constructor: typeof LitElement | typeof ProxyComponent): void;

package/dist/hmrSupport.d.ts

@@ -21,6 +21,7 @@ export type HmrComponentMeta = {
     readonly properties: (readonly [property: string, attribute: string] | readonly [property: string])[];
     readonly asyncMethods: readonly string[];
     readonly syncMethods: readonly string[];
+    readonly formAssociated: boolean;
 };
 /**
  * Update lazy component meta

package/dist/hmrSupport.js

@@ -1,4 +1,4 @@
-import { n as noShadowRoot, P as ProxyComponent } from "./lazyLoad-DJM-hmfq.js";
+import { n as noShadowRoot, P as ProxyComponent } from "./lazyLoad-D1geV6yY.js";
 import { camelToKebab } from "@arcgis/toolkit/string";
 function handleHmrUpdate(newModules) {
   newModules.forEach((newModule) => {
@@ -56,6 +56,8 @@ function reInitialize(instance, newModule) {
     ([propertyName, descriptor]) => typeof propertyName === "string" && (instance.devOnly$hmrSetProps.has(propertyName) || typeof descriptor.attribute === "string" && instance.devOnly$hmrSetAttributes.has(descriptor.attribute))
   ).map(([key]) => [key, instance[key]]);
   instance.devOnly$hmrResetStore(Object.fromEntries(preservedProperties));
+  const elementInternals = instance.$component.devOnly$PureGetElementInternals();
+  instance.devOnly$elementInternals = elementInternals;
   if (instance.isConnected) {
     instance.$component.disconnectedCallback();
   }

package/dist/index.js

@@ -2,8 +2,8 @@ import { p as propertyTrackResolve } from "./Controller-DQnXLHsP.js";
 import { c } from "./Controller-DQnXLHsP.js";
 import { state } from "lit/decorators/state.js";
 import { property as property$1 } from "lit/decorators/property.js";
-import { e as emptyFunction, n as noShadowRoot, a as attachToAncestor } from "./lazyLoad-DJM-hmfq.js";
-import { d, m } from "./lazyLoad-DJM-hmfq.js";
+import { e as emptyFunction, n as noShadowRoot, p as proxyFormMethodsToEvents, a as attachToAncestor } from "./lazyLoad-D1geV6yY.js";
+import { d, m } from "./lazyLoad-D1geV6yY.js";
 import { isEsriInternalEnv, safeAsyncCall, safeCall } from "@arcgis/toolkit/error";
 import { camelToKebab } from "@arcgis/toolkit/string";
 import { Deferred } from "@arcgis/toolkit/promise";
@@ -65,6 +65,10 @@ class LitElement extends LitElement$1 {
             );
           }
         });
+        this.devOnly$PureGetElementInternals = () => this.#elementInternals;
+        if (lazy?.devOnly$elementInternals !== void 0) {
+          this.#elementInternals = lazy.devOnly$elementInternals;
+        }
       }
     }
     if (createObservable) {
@@ -160,6 +164,9 @@ class LitElement extends LitElement$1 {
   static {
     this.lumina = true;
   }
+  static {
+    proxyFormMethodsToEvents(this);
+  }
   /**
    * The JS API's Accessor observables. This is used to integrate with the JS
    * API's reactivity system.
@@ -171,6 +178,14 @@ class LitElement extends LitElement$1 {
   #enableUpdating;
   #postLoadedDeferred;
   #trackingTarget;
+  #elementInternals;
+  /**
+   * @see [MDN ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+   */
+  get elementInternals() {
+    this.#elementInternals ??= this.el.attachInternals();
+    return this.#elementInternals;
+  }
   connectedCallback() {
     if (this.el.hasAttribute("defer-hydration")) {
       return;

package/dist/jsx/types.d.ts

@@ -178,7 +178,7 @@ interface JsxNodeArray extends Array<JsxNode> {
  * Do not exclude "manager" and "componentOnReady" since these properties are
  * available both on lazy and non-lazy instance.
  */
-type ExcludedProperties = "addController" | "attributeChangedCallback" | "connectedCallback" | "disconnectedCallback" | "el" | "hasUpdated" | "isUpdatePending" | "listen" | "load" | "loaded" | "removeController" | "render" | "renderOptions" | "renderRoot" | "requestUpdate" | "updateComplete" | "updated" | "willUpdate";
+type ExcludedProperties = "addController" | "attributeChangedCallback" | "connectedCallback" | "disconnectedCallback" | "el" | "elementInternals" | "hasUpdated" | "isUpdatePending" | "listen" | "load" | "loaded" | "removeController" | "render" | "renderOptions" | "renderRoot" | "requestUpdate" | "updateComplete" | "updated" | "willUpdate";
 /**
  * this.el property on a component only has the public properties of the
  * component. All internal methods, properties, as well as LitElement methods

package/dist/{lazyLoad-DJM-hmfq.js → lazyLoad-D1geV6yY.js}

@@ -106,6 +106,22 @@ const devOnly$getLitElementTagNameAndRuntime = process.env.NODE_ENV !== "product
     runtime: componentClass.K
   };
 } : void 0;
+function proxyFormMethodsToEvents(constructor) {
+  for (const namePart of ["Associated", "Disabled", "Reset", "StateRestore"]) {
+    const callbackNamePart = `orm${namePart}Callback`;
+    constructor.prototype["f" + callbackNamePart] = function(...args) {
+      this.manager === void 0 ? this.constructor.B.then(
+        () => dispatch(this, callbackNamePart, ...args)
+      ) : dispatch(this, callbackNamePart, ...args);
+    };
+  }
+  const dispatch = (component, name, ...args) => (
+    // Always emit on the component, not proxy so that we can listen in a consistent place
+    (component.el ?? component).dispatchEvent(
+      new CustomEvent(`luminaF${name}`, { detail: args })
+    )
+  );
+}
 const makeDefineCustomElements = (runtime, structure) => function defineCustomElements(windowOrOptions, options) {
   if (!globalThis.customElements) {
     return;
@@ -115,7 +131,7 @@ const makeDefineCustomElements = (runtime, structure) => function defineCustomEl
   if (resourcesUrl) {
     runtime.setAssetPath(resourcesUrl);
   }
-  for (const [tagName, [load, compactMeta = ""]] of Object.entries(structure)) {
+  for (const [tagName, [load, compactMeta = "", flags = 0]] of Object.entries(structure)) {
     if (customElements.get(tagName)) {
       continue;
     }
@@ -123,6 +139,9 @@ const makeDefineCustomElements = (runtime, structure) => function defineCustomEl
     const observedProps = compactObservedProps ? compactObservedProps?.split(lazyMetaItemJoiner).map(parseCondensedProp) : void 0;
     const observedProperties = observedProps?.map(([property]) => property);
     const ProxyClass = class extends ProxyComponent {
+      static {
+        this.formAssociated = flags === 1;
+      }
       static {
         this.observedAttributes = observedProps?.map(([, attribute]) => attribute).filter((attribute) => attribute !== "");
       }
@@ -179,6 +198,7 @@ class ProxyComponent extends HtmlElement {
       this.devOnly$hmrResetStore = (newStore) => {
         this.#store = newStore;
       };
+      this.devOnly$elementInternals = void 0;
     }
     const that = this;
     const ProxyClass = that.constructor;
@@ -265,6 +285,9 @@ class ProxyComponent extends HtmlElement {
       });
     }
   }
+  static {
+    proxyFormMethodsToEvents(this);
+  }
   #litElement;
   #store;
   #pendingAttributes;
@@ -410,5 +433,6 @@ export {
   devOnly$getLitElementTagNameAndRuntime as d,
   emptyFunction as e,
   makeDefineCustomElements as m,
-  noShadowRoot as n
+  noShadowRoot as n,
+  proxyFormMethodsToEvents as p
 };

package/dist/lazyLoad.d.ts

@@ -9,6 +9,7 @@ import { ControllerManager } from './controllers/ControllerManager.ts';
  * it will start loading the actual web component source code.
  */
 export interface DefineCustomElements {
+    /** @deprecated Passing the Window argument is not necessary - omit the first argument */
     (_window?: Window, options?: LazyLoadOptions): void;
     (options?: LazyLoadOptions): void;
 }
@@ -24,8 +25,15 @@ export declare const makeDefineCustomElements: (runtime: Runtime, structure: Rea
  * map-components). Also, the meta is a string to speed-up parsing
  * (browsers parse strings much faster).
  * See https://twitter.com/mathias/status/1143551692732030979
+ *
+ * - 1st item - the promise to load the component.
+ * - 2nd item: compact metadata string (lists attributes, properties, async
+ *   methods, and sync methods)
+ * - 3rd item: flags. If present, it will be 1 and indicates that the component
+ *   is formAssociated. We can expand this field to include more information in
+ *   the future using bit flags.
  */
-type CompactMeta = readonly [load: () => Promise<Record<string, typeof LitElement>>, compact?: string];
+type CompactMeta = readonly [load: () => Promise<Record<string, typeof LitElement>>, compact?: string, flags?: 1];
 /**
  * If this file is run from a Node.js environment, HTMLElement won't be defined.
  * Falling back to uselessly extending parseCondensedProp in that case
@@ -75,6 +83,7 @@ export declare abstract class ProxyComponent extends HtmlElement {
     devOnly$hmrSetAttributes: Set<string>;
     devOnly$InitializeComponent?: (module: Record<string, typeof LitElement>) => void;
     devOnly$hmrResetStore?: (newStore: Record<string, unknown>) => void;
+    devOnly$elementInternals?: ElementInternals;
     /**
      * This property is only set in development mode and exists only for usage in
      * tests or during debugging

package/dist/makeRuntime.d.ts

@@ -70,7 +70,7 @@ export type Runtime = RuntimeOptions & {
      */
     o?: () => AccessorObservableLike;
     /**
-     * In CDN build, we can only import @arcgis/core async, so the lazy loader will need
+     * In CDN build, we can only import `@arcgis/core` async, so the lazy loader will need
      * to await this promise before beginning hydration so that the reactiveUtils
      * integration modules had time to load.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/lumina",
-  "version": "5.1.0-next.21",
+  "version": "5.1.0-next.22",
   "sideEffects": false,
   "type": "module",
   "main": "dist/index.cjs",
@@ -28,7 +28,7 @@
   "dependencies": {
     "csstype": "^3.1.3",
     "tslib": "^2.8.1",
-    "@arcgis/toolkit": "~5.1.0-next.21"
+    "@arcgis/toolkit": "~5.1.0-next.22"
   },
   "peerDependencies": {
     "@lit/context": "^1.1.6",