@arcgis/lumina 6.0.0-next.44 → 6.0.0-next.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,35 @@
1
+ import type { ToJsxProps, RegisteredElements } from "./types.js";
2
+
3
+
4
+
5
+ /** @public */
6
+ declare global {
7
+ namespace preact {
8
+ namespace JSX {
9
+ interface IntrinsicElements extends PreactElements {}
10
+ }
11
+ }
12
+ }
13
+
14
+ export type PreactOwnProps<Component> = Omit<ToJsxProps<Component>, "key" | "ref">;
15
+
16
+ /**
17
+ * Given a Lumina web component type, infer Preact JSX props type.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * import type { ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
22
+ * import type { ToPreactProps } from "@arcgis/map-components/types/preact";
23
+ * function MapWrapper(props: ToPreactProps<ArcgisMap>) {
24
+ * // Custom hooks or props here
25
+ * return <arcgis-map {...props} />;
26
+ * }
27
+ * ```
28
+ */
29
+ export type ToPreactProps<Component extends EventTarget> = Omit<globalThis.preact.HTMLAttributes<Component>, keyof PreactOwnProps<Component>>
30
+ & PreactOwnProps<Component>;
31
+
32
+ /** @internal */
33
+ export type PreactElements = {
34
+ [Tag in keyof RegisteredElements]: ToPreactProps<RegisteredElements[Tag]>;
35
+ };
@@ -0,0 +1,35 @@
1
+ import type { ToJsxProps, RegisteredElements } from "./types.js";
2
+
3
+
4
+
5
+ /** @public */
6
+ declare global {
7
+ namespace React {
8
+ namespace JSX {
9
+ interface IntrinsicElements extends ReactElements {}
10
+ }
11
+ }
12
+ }
13
+
14
+ export type ReactOwnProps<Component> = Omit<ToJsxProps<Component>, "key" | "ref">;
15
+
16
+ /**
17
+ * Given a Lumina web component type, infer React JSX props type.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * import type { ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
22
+ * import type { ToReactProps } from "@arcgis/map-components/types/react";
23
+ * function MapWrapper(props: ToReactProps<ArcgisMap>) {
24
+ * // Custom hooks or props here
25
+ * return <arcgis-map {...props} />;
26
+ * }
27
+ * ```
28
+ */
29
+ export type ToReactProps<Component> = Omit<globalThis.React.HTMLProps<Component>, keyof ReactOwnProps<Component>>
30
+ & ReactOwnProps<Component>;
31
+
32
+ /** @internal */
33
+ export type ReactElements = {
34
+ [Tag in keyof RegisteredElements]: ToReactProps<RegisteredElements[Tag]>;
35
+ };
@@ -0,0 +1,30 @@
1
+ import type { JSXBase as StencilJsx } from "@stencil/core/internal";
2
+ import type { ToStencilJsxProps, RegisteredElements } from "./types.js";
3
+
4
+
5
+
6
+ /**
7
+ * Stencil JSX types shared by component packages without direct Stencil dependencies.
8
+ *
9
+ * @public
10
+ */
11
+ export declare namespace JSX {
12
+ interface IntrinsicElements extends StencilElements {}
13
+ }
14
+
15
+ /** @internal */
16
+ export type StencilOwnProps<Component> = Omit<ToStencilJsxProps<Component>, "key" | "ref">;
17
+
18
+ /** Stencil JSX attributes of a published component, retaining Stencil's key and ref semantics. */
19
+ export type ToStencilProps<Component> = Omit<StencilJsx.HTMLAttributes<Component>, keyof StencilOwnProps<Component>>
20
+ & StencilOwnProps<Component>;
21
+
22
+ /** @internal */
23
+ export type StencilElements = {
24
+ [Tag in keyof RegisteredElements]: ToStencilProps<RegisteredElements[Tag]>;
25
+ };
26
+ declare module "@stencil/core" {
27
+ namespace JSX {
28
+ interface IntrinsicElements extends StencilElements {}
29
+ }
30
+ }
@@ -21,6 +21,14 @@ export declare namespace h {
21
21
 
22
22
 
23
23
 
24
+ /** @public */
25
+ declare global {
26
+ /** Provide vanilla DOM typing for registered custom elements */
27
+ interface HTMLElementTagNameMap extends RegisteredElements {}
28
+ }
29
+
30
+
31
+
24
32
  /**
25
33
  * These types are based on dom-expressions typed (used by Solid and Preact):
26
34
  * https://github.com/ryansolid/dom-expressions/blob/main/packages/dom-expressions/src/jsx.d.ts
@@ -74,6 +82,7 @@ export declare namespace LuminaJsx {
74
82
  HTMLElementTags,
75
83
  SvgElementTags,
76
84
  ReMappedComponents<DeclareElements>,
85
+ RegisteredLuminaComponents,
77
86
  ReMapStencilComponents<ImportStencilElements> {}
78
87
 
79
88
  /** @deprecated import type { CustomAttributes } from "@arcgis/lumina/jsx/baseTypes"; instead */
@@ -262,27 +271,29 @@ export type ExcludedProperties = "addController" | "attributeChangedCallback" |
262
271
  *
263
272
  * @example
264
273
  * Usually, you don't need to use this type directly. If you have an
265
- * `ArcgisCounter` element, you can get its el type by using
274
+ * source `ArcgisCounter` custom element, you can get its `el` type by using
266
275
  * `ArcgisCounter["el"]`
267
276
  */
268
277
  export type ToElement<Component> = Omit<Component, ExcludedProperties>;
269
278
 
270
279
  /**
271
- * Utility type for getting the JSX prop types for a given component. In particular:
280
+ * Derive Lumina JSX prop type for your own custom elements. This provides type
281
+ * checking without a built step.
272
282
  *
273
- * - Excludes LitElement properties that should not be exposed to the end-user
274
- * - Converts event .emit() properties into event callbacks
275
- * - Replaces original HTMLElement property typings with the ones we provide for
276
- * greater type-safety and control
277
- * - For native events listeners, makes currentTarget equal to the component's
278
- * HTML instance
283
+ * Implementation details:
284
+ *
285
+ * - Excludes methods and other APIs that are available on the component
286
+ * instance but don't constitute the public JSX API.
287
+ * - Converts event emitters into event callbacks
288
+ * - Replaces vanilla DOM HTMLElement typing with a more JSX-specific one.
289
+ * - For native event listeners, sets `Component["el"]` as `currentTarget`
279
290
  *
280
291
  * We mark all component properties as optional because there is no easy
281
292
  * way for us to differentiate between public component properties and just
282
293
  * regular members that don't have `@property()` decorator (presence or
283
294
  * absence of decorator does not change the type). Thus, if we don't mark all
284
295
  * properties as optional, TypeScript will force us to provide a value for all
285
- * methods, and regular properties component may have.
296
+ * methods and regular properties a source custom element may have
286
297
  *
287
298
  * @internal
288
299
  */
@@ -291,12 +302,12 @@ export type ToJsx<Component extends { el: unknown; }> = HTMLAttributesAlias<Comp
291
302
  & RemapEvents<Component>;
292
303
 
293
304
  /**
294
- * From event emitters create event listener callbacks
305
+ * Convert source custom element event emitters into JSX callbacks targeting `el`.
295
306
  *
296
307
  * @internal
297
308
  */
298
309
  export type RemapEvents<Component extends { el: unknown; }> = {
299
- [Key in keyof Component as `on${Key & string}`]?: unknown extends Component[Key] ? never : Component[Key] extends { emit: (...rest: never[]) => infer PayloadType; } ? (event: PayloadType & {
310
+ [Key in keyof Component as `on${Key & string}`]?: unknown extends Component[Key] ? never : Component[Key] extends { emit: (...rest: never[]) => infer EventType; } ? (event: EventType & {
300
311
  currentTarget: Component["el"];
301
312
  target: Component["el"];
302
313
  }) => void : never;
@@ -332,8 +343,16 @@ export type NormalizedDeclaredCssProperties = {
332
343
  };
333
344
 
334
345
  /**
335
- * Get the type of all events for a given component. Includes native DOM events
336
- * and custom events.
346
+ * Derive native DOM and custom event types from a source or published custom
347
+ * element instance type.
348
+ *
349
+ * Source instances have event emitters. Published instances have type-only
350
+ * event type properties.
351
+ *
352
+ * This helper is intended to be used on components defined within the same
353
+ * package. For external components, you can use
354
+ * `HTMLArcgisMapElement["arcgisViewClick"]` directly, without need for
355
+ * `ToEvents<>`.
337
356
  *
338
357
  * @example
339
358
  * ```tsx
@@ -348,12 +367,13 @@ export type NormalizedDeclaredCssProperties = {
348
367
  */
349
368
  export type ToEvents<Component> = GlobalEventTypes<MaybeEl<Component>>
350
369
  & {
351
- [Key in keyof Component as ListenerToPayloadType<Component[Key]> extends BaseEvent ? Key : never]-?: ListenerToPayloadType<Component[Key]> & {
370
+ [Key in keyof Component as ListenerToEventType<Component[Key]> extends BaseEvent ? Key : never]-?: ListenerToEventType<Component[Key]> & {
352
371
  currentTarget: MaybeEl<Component>;
353
372
  target: MaybeEl<Component>;
354
373
  };
355
374
  };
356
375
 
376
+ /** Resolve Element type from a Component type if given a Component type. */
357
377
  export type MaybeEl<Component> = Component extends { el: unknown; } ? Component["el"] : Component;
358
378
 
359
379
  export interface TargetedEvent<Target = EventTarget | null, Payload = void> extends BaseEvent {
@@ -390,8 +410,7 @@ export interface BaseEvent extends Omit<Event, "currentTarget" | "target"> {
390
410
  }
391
411
 
392
412
  /**
393
- * From "GlobalEventHandlersCamelCase" extract event names and their payloads.
394
- * Not using "HTMLElementEventMap" because that map has all events in lowercase.
413
+ * Derive full native DOM event types for a target, whether source or published.
395
414
  *
396
415
  * @internal
397
416
  */
@@ -399,15 +418,67 @@ export type GlobalEventTypes<Target = HTMLElement> = {
399
418
  [Key in keyof GlobalEventHandlersCamelCase<Target> as Key extends `on${infer EventName}` ? Uncapitalize<EventName> : never]-?: Parameters<NonNullable<GlobalEventHandlersCamelCase<Target>[Key]>>[0];
400
419
  };
401
420
 
402
- /** @internal */
403
- export type ListenerToPayloadType<Listener> = unknown extends Listener ? void : Listener extends { emit: (...rest: never[]) => infer PayloadType; } ? PayloadType : Listener extends BaseEvent ? Listener : void;
421
+ /**
422
+ * Extract the full event type from a createEvent() event emitter or a type-only
423
+ * event type property in the build output.
424
+ *
425
+ * @internal
426
+ */
427
+ export type ListenerToEventType<Listener> = unknown extends Listener ? void : Listener extends { emit: (...rest: never[]) => infer EventType; } ? EventType : Listener extends BaseEvent ? Listener : void;
404
428
 
405
429
  /**
406
- * Defined Lumina custom elements. This interface is used only for internal
407
- * type-checking.
430
+ * Source custom element instance types keyed by tag name. Populated by the
431
+ * source JSX type generator for custom elements authored in the current package.
432
+ * Published instance types are registered in `RegisteredElements` instead.
408
433
  */
409
434
  export interface DeclareElements {}
410
435
 
436
+ /**
437
+ * Custom elements consummed in the current TypeScript program.
438
+ * This powers type checking. Import the custom elements to have them added
439
+ * to this interface.
440
+ */
441
+ export interface RegisteredElements {}
442
+
443
+ /** Pick from the component type properties appropriate for the JSX type. */
444
+ export type PickJsxProps<Component, OptionalProps extends keyof Component, RequiredProps extends keyof Component = never, SetterOverrides = object> = {
445
+ [Key in OptionalProps]?: Key extends keyof SetterOverrides ? SetterOverrides[Key] : Component[Key];
446
+ } &
447
+ {
448
+ [Key in RequiredProps]-?: Key extends keyof SetterOverrides ? SetterOverrides[Key] : Component[Key];
449
+ };
450
+
451
+ /** Derive JSX property inputs from a published custom element instance type. */
452
+ export type ToJsxProperties<Component> = Component extends { readonly "@jsxProps": infer Props; } ? Props : never;
453
+
454
+ /**
455
+ * Derive JSX property inputs and lowercase event handlers from a published
456
+ * custom element instance type.
457
+ */
458
+ export type ToJsxProps<Component> = ToJsxProperties<Component>
459
+ & (Component extends { readonly "@jsxEvents": infer Events; } ? Events : never);
460
+
461
+ /** Like [ToJsxProps](https://developers.arcgis.com/javascript/latest/references/lumina/jsx/types/#ToJsxProps), but with capitalized events. */
462
+ export type ToStencilJsxProps<Component> = ToJsxProperties<Component>
463
+ & (Component extends { readonly "@jsxStencilEvents": infer Events; } ? Events : never);
464
+
465
+ /**
466
+ * Lumina JSX attributes of a published component. Component inputs take
467
+ * precedence over native attributes with the same name.
468
+ */
469
+ export type ToLuminaProps<Component> = Omit<HTMLAttributesAlias<Component>, keyof ToJsxProps<Component>>
470
+ & ToJsxProps<Component>;
471
+
472
+ /** @internal */
473
+ export type RegisteredLuminaComponents = {
474
+ [Tag in keyof RegisteredElements]: ToLuminaProps<RegisteredElements[Tag]>;
475
+ };
476
+
477
+ /** From `Record<string, CustomEvent>` get `Record<string, CustomEvent['detail']>` */
478
+ export type EventPayloads<Events> = {
479
+ [Name in keyof Events]: Events[Name] extends { readonly detail: infer Payload; } ? Payload : never;
480
+ };
481
+
411
482
  /** @internal */
412
483
  export type ReMappedComponents<Components> = {
413
484
  [Key in keyof Components]: Components[Key] extends { el: unknown; } ? ToJsx<Components[Key]> : never;
@@ -442,5 +513,6 @@ export type _TypeHelper<_ extends [
442
513
  HTMLAttributesAlias,
443
514
  HTMLElementTagsAlias,
444
515
  SvgElementTagsAlias,
445
- AriaAttributesAlias
516
+ AriaAttributesAlias,
517
+ RegisteredLuminaComponents
446
518
  ]> = void;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcgis/lumina",
3
- "version": "6.0.0-next.44",
3
+ "version": "6.0.0-next.45",
4
4
  "description": "Runtime for WebGIS SDK web components",
5
5
  "sideEffects": false,
6
6
  "type": "module",
@@ -21,6 +21,15 @@
21
21
  "./jsx/generatedTypes": {
22
22
  "types": "./dist/jsx/generatedTypes.d.ts"
23
23
  },
24
+ "./jsx/react": {
25
+ "types": "./dist/jsx/react.d.ts"
26
+ },
27
+ "./jsx/preact": {
28
+ "types": "./dist/jsx/preact.d.ts"
29
+ },
30
+ "./jsx/stencil": {
31
+ "types": "./dist/jsx/stencil.d.ts"
32
+ },
24
33
  "./PublicLitElement": {
25
34
  "types": "./dist/PublicLitElement.d.ts"
26
35
  },
@@ -36,7 +45,7 @@
36
45
  ],
37
46
  "license": "SEE LICENSE IN LICENSE.md",
38
47
  "dependencies": {
39
- "@arcgis/toolkit": "~6.0.0-next.44",
48
+ "@arcgis/toolkit": "~6.0.0-next.45",
40
49
  "csstype": "^3.1.3",
41
50
  "tslib": "^2.8.1"
42
51
  },