@arcmantle/lit-jsx 1.0.33 → 1.0.34

package/src/shared/jsx-core.ts

@@ -0,0 +1,123 @@
+import type { TemplateResult } from 'lit-html';
+import type { DirectiveResult } from 'lit-html/async-directive.js';
+import type { RefOrCallback } from 'lit-html/directives/ref.js';
+
+
+declare global {
+	namespace LitJSX {
+		type HTMLElementAssignableProps<T extends object & Record<string, any>> =
+			Partial<TrimReadonly<T>>;
+
+		type HTMLElementProps = HTMLElementAssignableProps<HTMLElement>;
+
+		type JSXElementProps<T extends object> = HTMLElementAssignableProps<T> & {
+			children?:  LitJSX.Child;
+			ref?:       RefOrCallback<HTMLElementAssignableProps<T>>;
+			classList?: { [k: string]: boolean | undefined; };
+			styleList?: CSSProperties;
+
+			/**
+			 * This property takes in one or more element directives.
+			 * This is akin to applying a directive through `<div ${myDirective()}></div>`.
+			 */
+			directive?: DirectiveResult<any> | DirectiveResult<any>[];
+		} & {
+			[key: `data-${ string }`]: string | undefined;
+		};
+
+		type ElementMapToJSXElements<T extends object & Record<string, any>> = {
+			[K in keyof T]: JSXElementProps<T[K]>;
+		};
+
+		type IfEquals<X, Y, A = X> =
+			(<T>() => T extends X ? 1 : 2) extends
+			(<T>() => T extends Y ? 1 : 2) ? A : never;
+
+		type WritableKeys<T> = {
+			[P in keyof T]-?: IfEquals<
+				{ [Q in P]: T[P] },
+				{ -readonly [Q in P]: T[P] },
+				P
+			>
+		}[keyof T];
+
+		type TrimReadonly<T> = Pick<T, WritableKeys<T>>;
+
+		type TrimHTMLElement<T extends object> = TrimReadonly<Omit<T, keyof HTMLElement | 'constructor'>>;
+
+		type JSXProps<T extends object> =
+			& TrimHTMLElement<T>
+			& Omit<HTMLElementProps, keyof TrimHTMLElement<T>>;
+
+		type Child = unknown;
+
+		type Element = TemplateResult<any>;
+
+		type AnyTagName = string & Record<never, never>;
+
+		interface IntrinsicElements extends
+			NativeHTMLElements,
+			NativeSVGElements,
+			NativeMathMLElements,
+			SemanticTags {}
+
+		type TagName = keyof IntrinsicElements | AnyTagName;
+
+		type DynamicTagProps<Tag extends string> = Tag extends keyof IntrinsicElements
+			? IntrinsicElements[Tag]
+			: (Tag extends keyof HTMLElementTagNameMap
+				? JSXElementProps<HTMLElementTagNameMap[Tag]>
+				: JSXElementProps<HTMLElement>);
+
+		type IntrinsicElementProps<Tag extends keyof IntrinsicElements> = IntrinsicElements[Tag];
+
+		type DynamicTag<Tag extends TagName> = ((props: DynamicTagProps<Tag> & StaticMarker) => Element);
+
+		interface StaticMarker {
+			/**
+			 * Opt into the lit-jsx custom-element transform. \
+			 * Example: `<MyElement static />`
+			 */
+			static: true;
+		}
+
+		type Component<P extends object = {}> = (props: P) => Element;
+		type ClassComponent<Instance extends object = any> = abstract new (...args: any[]) => Instance;
+
+		type ComponentLike<P extends object = object> =
+			| Component<P>
+			| ClassComponent<any>;
+
+		type ComponentProps<T> =
+			T extends Component<infer P> ? P :
+				T extends ClassComponent<infer I> ? JSXProps<Extract<I, object>> :
+					T extends abstract new (...args: any[]) => infer I ? JSXProps<Extract<I, object>> :
+						{};
+	}
+
+	// eslint-disable-next-line no-var
+	var as: {
+		/**
+		 * Informs the compiler that the value should be bound as a property value.\
+		 * This binds the expression value as a property, using the `.` syntax e.g `.key=${value}`\
+		 * This function call is removed during compilation, therefore it has no runtime effect.
+		 */
+		prop: <T>(value: T) => T;
+		/**
+		 * Informs the compiler that the value should be bound as a boolean attribute.\
+		 * This allows the template to bind the value using the `?` syntax, e.g. `?disabled=${true}`\
+		 * This function call is removed during compilation, therefore it has no runtime effect.
+		 */
+		bool: (value: boolean) => boolean;
+		/**
+		 * Creates a component-like value for an intrinsic tag, so it can be used in
+		 * JSX as a dynamic tag identifier.
+		 *
+		 * The returned component requires `static`.
+		 * Example:
+		 *   const Tag = as.tag('a');
+		 *   <Tag static href="..." />
+		 */
+		tag:  <Tag extends LitJSX.TagName>(tag: Tag) => LitJSX.DynamicTag<Tag>;
+	};
+}

package/src/shared/jsx-dom.ts

@@ -0,0 +1,29 @@
+import type * as csstype from 'csstype';
+
+
+declare global {
+	namespace LitJSX {
+
+		interface CSSProperties extends csstype.Properties { }
+
+		/**
+		 * Interface for native HTML elements
+		 */
+		type NativeHTMLElements = ElementMapToJSXElements<HTMLElementTagNameMap>;
+
+		/**
+		 * Interface for native SVG elements
+		 */
+		type NativeSVGElements = ElementMapToJSXElements<Omit<SVGElementTagNameMap, keyof HTMLElementTagNameMap>>;
+
+		/**
+		 * Interface for native MathML elements
+		 */
+		type NativeMathMLElements = ElementMapToJSXElements<Omit<MathMLElementTagNameMap, keyof HTMLElementTagNameMap>>;
+
+		/**
+		 * Interface for semantic tags that start with "s-".
+		 */
+		interface SemanticTags { [key: `s-${ string }`]: JSXElementProps<HTMLElement>; }
+	}
+}

package/src/shared/jsx-hooks.ts

@@ -0,0 +1,86 @@
+export {};
+
+
+/**
+ * TSX hook declarations for lit-jsx.
+ */
+
+declare global {
+	//#region JSX hooks (TypeScript special names)
+	// These names are *looked up by TypeScript* when type-checking TSX.
+	namespace JSX {
+		/**
+		 * TSX hook: the type produced by any JSX expression.
+		 *
+		 * In lit-jsx we return a lit `TemplateResult`, so `<div />` has this type.
+		 */
+		type Element = LitJSX.Element;
+
+		/**
+		 * TSX hook: what values are allowed as JSX tags.
+		 *
+		 * Note: this intentionally references tag/component helper types declared in
+		 * `jsx-core.ts`.
+		 */
+		type ElementType
+			= keyof LitJSX.IntrinsicElements
+			| (string & {})
+			| LitJSX.ComponentLike<any>;
+
+		/**
+		 * TSX hook: computes the attribute (props) type for a JSX tag.
+		 *
+		 * lit-jsx uses this to:
+		 * - require `static: true` for class-based component tags
+		 * - preserve TSX generic arguments on class instances (avoid `unknown` props)
+		 */
+		type LibraryManagedAttributes<C, P>
+			= C extends abstract new (...args: any[]) => infer I
+				? (P extends I
+					? LitJSX.JSXProps<Extract<P, object>> & LitJSX.StaticMarker
+					: LitJSX.ComponentProps<C> & LitJSX.StaticMarker)
+				: (C extends keyof LitJSX.IntrinsicElements
+					? LitJSX.IntrinsicElementProps<C>
+					: LitJSX.ComponentProps<C>);
+
+		/**
+		 * TSX hook: controls the instance type used for class components.
+		 *
+		 * We keep this empty because we don’t require any particular base class.
+		 */
+		interface ElementClass {}
+
+		/**
+		 * TSX hook: which property name TypeScript should read for “props”.
+		 *
+		 * Leaving it empty means TS uses its default behavior.
+		 */
+		interface ElementAttributesProperty {}
+
+		/**
+		 * TSX hook: which property name represents “children”.
+		 */
+		interface ElementChildrenAttribute { children: {}; }
+
+		/** TSX hook: attributes allowed on *all* JSX elements (e.g. React's `key`). */
+		interface IntrinsicAttributes {}
+
+		/** TSX hook: attributes allowed on class components specifically (often `ref`-like). */
+		interface IntrinsicClassAttributes<_T> {}
+
+		/** TSX hook: base attribute bag TypeScript may intersect into component props. */
+		interface Attributes {}
+
+		/** TSX hook: fragment typing for `<>...</>` */
+		type Fragment = Element;
+
+		/**
+		 * TSX hook: mapping of intrinsic tag names to their attribute types.
+		 *
+		 * Note: this intentionally depends on DOM typings declared in `jsx-dom.ts`
+		 * (e.g. `HTMLElementTags`, `SVGElementTags`, ...).
+		 */
+		interface IntrinsicElements extends LitJSX.IntrinsicElements {}
+	}
+	//#endregion
+}