@arcgis/lumina 4.31.0-next.90 → 4.31.0-next.91

package/dist/LitElement.d.ts

@@ -1,8 +1,9 @@
 import type { CSSResultGroup, CSSResultOrNative, PropertyValues } from "lit";
 import { LitElement as OriginalLitElement } from "lit";
-import type { LitElementPropertyDeclaration } from "@arcgis/components-controllers";
+import type { LuminaPropertyDeclaration } from "@arcgis/components-controllers";
 import type { Runtime } from "./runtime";
 import type { ProxyComponent } from "./lazyLoad";
+import type { ToElement } from "./jsx/jsx";
 type ComponentLifecycle = {
     connectedCallback?: () => void;
     disconnectedCallback?: () => void;
@@ -38,13 +39,13 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
     static finalizeStyles(styles?: CSSResultGroup): CSSResultOrNative[];
     static createProperty(name: PropertyKey, 
     /**
-     * While in vanilla Lit this type is always LitElementPropertyDeclaration,
+     * While in vanilla Lit this type is always LuminaPropertyDeclaration,
      * in Lumina it is always number or
-     * [number,LitElementPropertyDeclaration], so we don't even check for the
-     * LitElementPropertyDeclaration case. LitElementPropertyDeclaration is here
+     * [number,LuminaPropertyDeclaration], so we don't even check for the
+     * LuminaPropertyDeclaration case. LuminaPropertyDeclaration is here
      * only to satisfy the type checker.
      */
-    options?: LitElementPropertyDeclaration | number | [number, LitElementPropertyDeclaration]): void;
+    options?: LuminaPropertyDeclaration | number | [number, LuminaPropertyDeclaration]): void;
     /**
      * Since we can't pass arguments to web component constructor, before lazy
      * loading logic calls document.createElement(), it temporary sets this static
@@ -74,7 +75,7 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
      * const isLazy = this.el !== this;
      * ```
      */
-    el: HTMLElement;
+    el: ToElement<this>;
     /**
      * Controller Manager orchestrates all components used by this component,
      * connecting their lifecycle hooks and providing context information.
@@ -194,7 +195,7 @@ export declare class LitElement extends OriginalLitElement implements ComponentL
     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 & {
+    listenOn<EventType extends Event = CustomEvent<"Provide type like this.listenOn<ToEvents<ArcgisCounter>['arcgisClick']>() to get type-checked payload type">, Target = EventTarget>(target: Target, name: string, listener: Listener<this, EventType & {
         currentTarget: Target;
     }>, options?: AddEventListenerOptions | boolean): void;
     /**

package/dist/createEvent.d.ts

@@ -1,9 +1,4 @@
-/**
- * An event emitter object
- */
-export type EventEmitter<T = undefined> = {
-    emit(payload: T extends undefined ? void : T): CustomEvent<T>;
-};
+import type { EventEmitter } from "@arcgis/components-controllers";
 export type EventOptions = {
     /**
      * A Boolean indicating whether the event bubbles up through the DOM or not.
@@ -27,27 +22,7 @@ export type EventOptions = {
      */
     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>;
+export declare const createEventFactory: <T = undefined>(eventName?: string, options?: EventOptions, component?: import("@arcgis/components-controllers").BaseComponent) => EventEmitter<T>;
 /**
  * Creates an event emitter.
  * Events emitted by your component will be included in the documentation.
@@ -62,4 +37,4 @@ export declare const createEventFactory: <T = undefined>(eventName?: string, opt
  * ```
  *
  */
-export declare const createEvent: <T = undefined>(options?: EventOptions) => CustomEvent<T> & EventEmitter<T>;
+export declare const createEvent: <T = undefined>(options?: EventOptions) => EventEmitter<T>;

package/dist/decorators.d.ts

@@ -1,4 +1,4 @@
-import type { LitElementPropertyDeclaration } from "@arcgis/components-controllers";
+import type { LuminaPropertyDeclaration } 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
@@ -41,7 +41,7 @@ export { state } from "@lit/reactive-element/decorators/state.js";
  * }
  * ```
  */
-export declare const property: (options?: Omit<LitElementPropertyDeclaration, "state">) => PropertyDecorator;
+export declare const property: (options?: Omit<LuminaPropertyDeclaration, "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.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { EventEmitter, EventOptions } from "./createEvent";
+export type { EventOptions } from "./createEvent";
 export { createEvent } from "./createEvent";
 export { state, property, method } from "./decorators";
 export type { HmrComponentMeta } from "./hmrSupport";

package/dist/index.js

@@ -707,7 +707,7 @@ var LitElement = class _LitElement extends OriginalLitElement {
     return this;
   }
 };
-LitElement.createEvent = createEventFactory;
+LitElement.$createEvent = createEventFactory;
 if (process.env.NODE_ENV !== "production") {
   const globalWithLit = globalThis;
   globalWithLit.litIssuedWarnings ??= /* @__PURE__ */ new Set();

package/dist/jsx/jsx.d.ts

@@ -21,7 +21,7 @@ import type { DirectiveClass } from "lit/directive.js";
  */
 export declare namespace h {
     export function h(sel: any, data?: any, text?: any): TemplateResult;
-    export type { LitJsx as JSX };
+    export type { LuminaJsx as JSX };
 }
 /**
  * Fragment
@@ -175,6 +175,8 @@ export declare const bindEvent: <T>(descriptor: T | (AddEventListenerOptions & {
     handleEvent: T;
 })) => T;
 export type JsxNode = DirectiveResult<any> | JsxNodeArray | Node | TemplateResult | boolean | number | (NonNullable<unknown> & string) | null | undefined;
+interface JsxNodeArray extends Array<JsxNode> {
+}
 /**
  * Equivalent to Lit's "nothing", but has type "never" to allow it to be set as a
  * value for any JSX attribute.
@@ -213,8 +215,93 @@ export declare const noChange: never;
  * "never" to allow it be set as a value for any JSX attribute.
  */
 export declare const directive: <C extends DirectiveClass>(c: C) => (...values: Parameters<InstanceType<C>["render"]>) => never;
-interface JsxNodeArray extends Array<JsxNode> {
-}
+/**
+ * this.el property on a component only has the public properties of the
+ * component. All internal methods, properties, as well as LitElement methods
+ * are excluded. This type approximates what the public API of the component
+ * looks like.
+ *
+ * @example
+ * Usually, you don't need to use this type directly. If you have an
+ * `ArcgisCounter` element, you can get it's el type by using
+ * `ArcgisCounter["el"]`
+ *
+ * @remarks
+ * By using Omit<>, TypeScript also "forgets" all private members of the
+ * passed in type, which is convenient for us.
+ */
+export type ToElement<Component> = Omit<Component, LuminaJsx.ExcludedProperties>;
+/**
+ * Utility type for getting the JSX prop types for a given component. In particular:
+ *
+ * - Excludes LitElement properties that should not be exposed to the end-user
+ * - Converts event .emit() properties into event callbacks
+ * - Replaces original HTMLElement property typings with the ones we provide for
+ *   greater type-safety and control
+ * - For native events listeners, makes currentTarget equal to the component's
+ *   HTML instance
+ *
+ * We mark all component properties as optional because there is no easy
+ * way for us to differentiate between public component properties and just
+ * regular members that don't have `@property()` decorator (presence or
+ * absence of decorator does not change the type). Thus, if we don't mark all
+ * properties as optional, TypeScript will force us to provide a value for all
+ * methods, and regular properties component may have.
+ */
+export type ToJsx<Component extends {
+    el: unknown;
+}> = LuminaJsx.HTMLAttributes<Component["el"]> & LuminaJsx.RemapEvents<Component> & Partial<Omit<Component, LuminaJsx.ExcludedProperties | keyof HTMLElement | keyof LuminaJsx.RemapEvents<Component>>>;
+/**
+ * Get the type of all events for a given component. Includes native DOM events
+ * and custom events.
+ *
+ * @example
+ * ```tsx
+ * render() {
+ *   return <arcgis-counter onArcgisOverflow={this._handleOverflow} />
+ * }
+ * _handleOverflow(event: ToEvents<ArcgisCounter>["arcgisOverflow"]) {
+ *   // event.detail
+ *   // event.currentTarget
+ * }
+ * ```
+ *
+ * @remarks
+ * Alternative implementation of this type that is simpler, and potentially
+ * more performant, but looses "go to definition" information.
+ *
+ * ```tsx
+ * export type ToEvents<Component extends { el: unknown }> = {
+ *   [Key in keyof ToJsx<Component> as Key extends `on${infer EventName}`
+ *     ? Uncapitalize<EventName>
+ *     : never]-?: ListenerToPayloadType<ToJsx<Component>[Key]>;
+ * };
+ *
+ * type ListenerToPayloadType<Listener> = Listener extends (event: infer EventType) => unknown ? EventType : never;
+ * ```
+ *
+ * TypeScript issues that may fix this:
+ * - https://github.com/microsoft/TypeScript/issues/49909
+ * - https://github.com/microsoft/TypeScript/issues/50715
+ */
+export type ToEvents<Component> = GlobalEventTypes<MaybeEl<Component>> & {
+    [Key in keyof Component as ListenerToPayloadType<Component[Key]> extends CustomEvent ? Key : never]-?: ListenerToPayloadType<Component[Key]> & {
+        currentTarget: MaybeEl<Component>;
+    };
+};
+type MaybeEl<Component> = Component extends {
+    el: unknown;
+} ? Component["el"] : Component;
+/**
+ * From "GlobalEventHandlersCamelCase" extract event names and their payloads.
+ * Not using "HTMLElementEventMap" because that map has all events in lowercase.
+ */
+type GlobalEventTypes<Target = HTMLElement> = {
+    [Key in keyof LuminaJsx.GlobalEventHandlersCamelCase<Target> as Key extends `on${infer EventName}` ? Uncapitalize<EventName> : never]-?: Parameters<NonNullable<LuminaJsx.GlobalEventHandlersCamelCase<Target>[Key]>>[0];
+};
+type ListenerToPayloadType<Listener> = unknown extends Listener ? void : Listener extends {
+    emit: (...rest: never[]) => infer PayloadType;
+} ? PayloadType : Listener extends CustomEvent ? Listener : void;
 /**
  * These typings are based on dom-expressions typings:
  * https://github.com/ryansolid/dom-expressions/blob/main/packages/dom-expressions/src/jsx.d.ts
@@ -227,7 +314,7 @@ interface JsxNodeArray extends Array<JsxNode> {
  * https://www.typescriptlang.org/docs/handbook/jsx.html
  */
 type DOMElement = Element;
-export declare namespace LitJsx {
+export declare namespace LuminaJsx {
     /**
      * Whether to pick TemplateResult or JsxNode here is a compromise.
      *
@@ -292,35 +379,24 @@ export declare namespace LitJsx {
      * information and can generate the typings that expose only the actual
      * properties component declared.
      */
-    type ExcludedProperties = "renderRoot" | "isUpdatePending" | "hasUpdated" | "addController" | "removeController" | "connectedCallback" | "disconnectedCallback" | "attributeChangedCallback" | "requestUpdate" | "updateComplete" | "el" | "manager" | "componentOnReady" | "listen" | "load" | "loaded" | "willUpdate" | "updated" | "render" | "renderOptions";
+    type ExcludedProperties = "renderRoot" | "isUpdatePending" | "hasUpdated" | "addController" | "removeController" | "connectedCallback" | "disconnectedCallback" | "attributeChangedCallback" | "requestUpdate" | "updateComplete" | "el" | "componentOnReady" | "listen" | "load" | "loaded" | "willUpdate" | "updated" | "render" | "renderOptions";
     type ReMappedComponents<Components> = {
-        [Key in keyof Components]: ComponentProps<Components[Key]>;
+        [Key in keyof Components]: Components[Key] extends {
+            el: unknown;
+        } ? ToJsx<Components[Key]> : never;
     };
     /**
-     *  * A utility type for getting the JSX prop types for a given component
-     *
-     * - Exclude LitElement properties that should not be exposed to the end-user
-     * - Convert event .emit() properties into event callbacks
-     * - Replace original HTMLElement property typings with the ones we provide for
-     *   greater type-safety and control
-     * - For native events listeners, make currentTarget equal to the component's
-     *   HTML instance
-     *
-     * We mark all component properties as optional because there is no easy
-     * way for us to differentiate between public component properties and just
-     * regular members that don't have `@property()` decorator (presence or
-     * absence of decorator does not change the type). Thus, if we don't mark all
-     * properties as optional, TypeScript will force us to provide a value for all
-     * methods, and regular properties component may have.
+     * From event emitters create event listener callbacks
      */
-    type ComponentProps<Component> = Partial<Omit<Component, FindEventProperties<Component> | ExcludedProperties | keyof HTMLElement>> & {
-        [Key in FindEventProperties<Component> as `on${Key & string}`]?: (event: Omit<Component[Key], "emit"> & {
-            currentTarget: Component;
-        }) => void;
-    } & HTMLAttributes<Component>;
-    type FindEventProperties<Component> = {
-        [Key in keyof Component]: Component[Key] extends CustomEvent ? unknown extends Component[Key] ? never : Key : never;
-    }[keyof Component];
+    type RemapEvents<Component extends {
+        el: unknown;
+    }> = {
+        [Key in keyof Component as `on${Key & string}`]?: unknown extends Component[Key] ? never : Component[Key] extends {
+            emit: (...rest: never[]) => infer PayloadType;
+        } ? (event: PayloadType & {
+            currentTarget: Component["el"];
+        }) => void : never;
+    };
     /**
      * - Make ref prop return HTMLElement rather than Stencil element type
      * - Uncapitalize the event properties to match the syntax of React 19,
@@ -656,6 +732,11 @@ export declare namespace LitJsx {
         ariaControlsElements?: HTMLElement[];
         /** Indicates the element that represents the current item within a container or set of related elements. */
         ariaCurrent?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time";
+        /**
+         * Defines a string value that describes or annotates the current element.
+         * @see aria-describedby
+         */
+        ariaDescription?: string;
         /**
          * Identifies the element (or elements) that describes the object.
          * @see aria-labelledby

package/dist/typings/jsxGlobals.d.ts

@@ -14,7 +14,10 @@ declare global {
      */
     export interface DeclareElements {
     }
-    interface HTMLElementTagNameMap extends DeclareElements {
+    type ReMappedDeclareElements = {
+        [TagName in keyof DeclareElements]: DeclareElements[TagName]["el"];
+    };
+    interface HTMLElementTagNameMap extends ReMappedDeclareElements {
     }
     /**
      * Extend this interface with Stencil web components that you wish to use

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/lumina",
-  "version": "4.31.0-next.90",
+  "version": "4.31.0-next.91",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -29,8 +29,8 @@
     "clean": "rimraf ./dist ./build ./turbo ./node_modules"
   },
   "dependencies": {
-    "@arcgis/components-controllers": "4.31.0-next.90",
-    "@arcgis/components-utils": "4.31.0-next.90",
+    "@arcgis/components-controllers": "4.31.0-next.91",
+    "@arcgis/components-utils": "4.31.0-next.91",
     "@lit-labs/ssr": "^3.2.2",
     "@lit-labs/ssr-client": "^1.1.7",
     "csstype": "^3.1.3",
@@ -38,12 +38,12 @@
     "tslib": "^2.7.0"
   },
   "devDependencies": {
-    "@arcgis/typescript-config": "4.31.0-next.90",
+    "@arcgis/typescript-config": "4.31.0-next.91",
     "@types/node": "^20.2.5",
     "eslint": "^8.55.0",
     "rimraf": "^5.0.0",
     "tsup": "^8.1.0",
     "typescript": "~5.4.0"
   },
-  "gitHead": "a9a0d57b58ffabca05a7c03a2d0516b7174cf939"
+  "gitHead": "c06a24c15d739911e39eb09ff59eeb895c478e7a"
 }