@excom/neutron 0.1.0

package/src/types/element.types.ts

@@ -0,0 +1,263 @@
+import type { CommandArgs, TCommandEvent } from "../command";
+import type { NeutronInternal as TNeutronInternal } from "../neutron-internal";
+import { Effector } from "./effect.types";
+import { AnyFunction, PickGlobalElement } from "./shared.types";
+import type { TokenList } from "@excom/kit-utils";
+
+/** Neutron `emit` defaults. Intersect with `{ type; detail }` for element events. */
+export type TEvent = CustomEvent & {
+  bubbles: true;
+  cancelable: true;
+  composed: true;
+};
+
+export interface NativeNElement extends HTMLElement {
+  // stub `_n_` for native / non-Neutron hosts
+  _n_: {
+    element: NativeNElement;
+    ctr?: typeof TNeutronInternal;
+    debug?: TNeutronInternal["debug"];
+    eventListeners: TNeutronInternal["eventListeners"];
+    disconnectedEventListeners: TNeutronInternal["disconnectedEventListeners"];
+    broadcastListeners: TNeutronInternal["broadcastListeners"];
+    disconnectedBroadcastListeners: TNeutronInternal["disconnectedBroadcastListeners"];
+  };
+}
+
+export type NEvent<CT, T, E extends Event = CustomEvent> = Omit<
+  E,
+  "currentTarget" | "target"
+> & {
+  currentTarget: CT;
+  target: T;
+};
+
+export interface SuperAddEventListenerOptions extends AddEventListenerOptions {
+  target?: EventTarget;
+}
+
+export type EventListenerArgs<Fn = EventListener> = [
+  string,
+  Fn,
+  SuperAddEventListenerOptions?,
+];
+
+export type NCustomEventInit = CustomEventInit & {
+  target?: HTMLElement;
+};
+
+export type EmitArgs = [string, NCustomEventInit?];
+
+export type GlobalEventMap = GlobalEventHandlersEventMap &
+  WindowEventHandlersEventMap &
+  ElementEventMap;
+
+export type PickGlobalEvent<EventName> = EventName extends keyof GlobalEventMap
+  ? GlobalEventMap[EventName]
+  : CustomEvent;
+
+export interface TCommonElementListeners {
+  addListener<EventName extends keyof GlobalEventMap | string>(
+    name: EventName,
+    listener: (event: PickGlobalEvent<EventName>) => any,
+    opts?: SuperAddEventListenerOptions
+  ): void;
+  addBroadcastListener<EventName extends keyof GlobalEventMap | string>(
+    name: EventName,
+    listener: (event: PickGlobalEvent<EventName>) => any,
+    opts?: AddEventListenerOptions
+  ): void;
+  removeListener(
+    /* `Function` is enough here; a tighter listener type does not help. */
+    ...args: [string, Function, SuperAddEventListenerOptions?]
+  ): void;
+  removeBroadcastListener(
+    ...args: [string, Function, AddEventListenerOptions?]
+  ): void;
+  addListeners<EventName extends keyof GlobalEventMap | string>(
+    ...args: [
+      EventName,
+      (event: PickGlobalEvent<EventName>) => any,
+      SuperAddEventListenerOptions?,
+    ][]
+  ): void;
+  addBroadcastListeners<EventName extends keyof GlobalEventMap | string>(
+    ...args: [
+      EventName,
+      (event: PickGlobalEvent<EventName>) => any,
+      AddEventListenerOptions?,
+    ][]
+  ): void;
+  removeListeners(
+    ...args: [string, Function, SuperAddEventListenerOptions?][]
+  ): void;
+  removeBroadcastListeners(
+    ...args: [string, Function, AddEventListenerOptions?][]
+  ): void;
+  toggleListeners<EventName extends keyof GlobalEventMap | string>(
+    ...args: [
+      EventName,
+      (event: PickGlobalEvent<EventName>) => any,
+      boolean,
+      SuperAddEventListenerOptions?,
+    ][]
+  ): void;
+  toggleBroadcastListeners<EventName extends keyof GlobalEventMap | string>(
+    ...args: [
+      EventName,
+      (event: PickGlobalEvent<EventName>) => any,
+      boolean,
+      AddEventListenerOptions?,
+    ][]
+  ): void;
+}
+
+export interface TCommonElementOther {
+  removeAllListeners(): void;
+  removeAllBroadcastListeners(): void;
+  internal_disconnectEventListeners(): void;
+  internal_reconnectEventListeners(): void;
+  emit(...args: EmitArgs): CustomEvent;
+  emits(...args: EmitArgs[]): CustomEvent;
+  broadcast(...args: EmitArgs): CustomEvent;
+  broadcasts(...args: EmitArgs[]): CustomEvent;
+  command(...args: CommandArgs): TCommandEvent | null;
+  commands(...args: CommandArgs[]): (TCommandEvent | null)[];
+}
+
+export type PickRenderRootTag<Conf extends OptsConfig> =
+  Conf["renderRoot"] extends ConfigRenderRoot
+    ? PickGlobalElement<Conf["renderRoot"]["tag"]>
+    : never;
+
+export type MapPropType<
+  T extends abstract new (...args: any) => any,
+  DefaultValue extends (...args: any) => any = () => null,
+> = T extends typeof String
+  ? string | ReturnType<DefaultValue>
+  : T extends typeof Number
+    ? number | ReturnType<DefaultValue>
+    : T extends typeof Boolean
+      ? boolean
+      : T extends typeof TokenList
+        ? string[] | ReturnType<DefaultValue>
+        : InstanceType<T> | ReturnType<DefaultValue>;
+
+export type PropTypeKey =
+  | typeof String
+  | typeof Number
+  | typeof Boolean
+  | typeof TokenList;
+
+export interface OptsPropConfig {
+  type: PropTypeKey | Function;
+  notify?: "attr" | "prop" | false;
+  attr?: false | string;
+  prop?: string;
+  defaultValue?: () => any;
+  isValid?: null | ((value: any) => boolean);
+  get?: (
+    element: HTMLElement,
+    propStore: Record<string, unknown>,
+    propConfig: PropConfig
+  ) => unknown;
+  set?: (
+    element: HTMLElement,
+    propStore: Record<string, unknown>,
+    propConfig: PropConfig,
+    value: unknown
+  ) => void;
+  serialize?: (value?: unknown) => unknown;
+  deserialize?: (value?: unknown) => unknown;
+  store?: "default" | "weak";
+  /* TODO
+   * https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+   * When `element.matches()` understands custom state, add
+   * `{ as: "attr" | "state" }` so a prop can toggle `internals`
+   * (e.g. `super-input:state(invalid)`).
+   */
+}
+
+export type PropConfig = Required<OptsPropConfig>;
+
+export type DefaultProps = {
+  isMounted: boolean;
+  isMoving: boolean;
+  isAdopted: boolean;
+  wasMounted: boolean;
+};
+export type DefaultPropName =
+  | "isMounted"
+  | "isAdopted"
+  | "wasMounted"
+  | "isMoving"
+  | "renderRoot";
+export type DefaultPropsConfig = Record<DefaultPropName, OptsPropConfig>;
+export interface DefaultConfig {
+  props: DefaultPropsConfig;
+}
+
+// Author-facing `Neutron({ ... })` options
+export interface OptsConfig {
+  tag: string;
+  props: Record<string, PropTypeKey | OptsPropConfig | Function>;
+  reflectDefaultProps?: DefaultPropName[];
+  renderRoot?: ConfigRenderRoot;
+  events?: EventsConfig;
+  broadcasts?: EventsConfig;
+  definitionOpts?: ElementDefinitionOptions;
+  methods?: [string, AnyFunction][];
+  lifecycles?: Lifecycles<[string[], AnyFunction]>;
+}
+export type BuiltConfig = {
+  tag: string;
+  props: Record<string, PropConfig>;
+  reflectDefaultProps: DefaultPropName[];
+  renderRoot?: ConfigRenderRoot;
+  events: EventsConfig;
+  broadcasts: EventsConfig;
+  definitionOpts?: ElementDefinitionOptions;
+  methods: [string, AnyFunction][];
+  lifecycles: Lifecycles<[string[], AnyFunction]>;
+};
+export interface RuntimeConfig {
+  tag: string;
+  props: Record<string, PropConfig>;
+  reflectDefaultProps: DefaultPropName[];
+  renderRoot?: ConfigRenderRoot;
+  events: EventsConfig;
+  broadcasts: EventsConfig;
+  definitionOpts?: ElementDefinitionOptions;
+  methods: [string, Effector<any, any>][];
+  lifecycles: Lifecycles<[string[], Effector<any, any>]>;
+}
+
+export interface Lifecycles<T> {
+  constructed: T[];
+  connected: T[];
+  adopted: T[];
+  disconnected: T[];
+  error: T[];
+  promiseResolved: T[];
+  promiseRejected: T[];
+  broadcast: T[];
+  event: T[];
+  eventDefault: T[];
+  command: T[];
+  effect: T[];
+  propUnset: T[];
+  propSet: T[];
+  propChanged: T[];
+}
+
+export type ConfigRenderRoot = {
+  tag: keyof HTMLElementTagNameMap;
+  shadow?: ShadowRootMode;
+  defaultSlots?: boolean;
+};
+
+export interface EventsConfig {
+  [eventType: string]: {
+    prefixWithTag?: boolean;
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from "./effect.types";
+export * from "./element.types";
+export * from "./new.types";
+export * from "./shared.types";

package/src/types/new.types.ts

@@ -0,0 +1,159 @@
+import type { TCommandEvent } from "../command";
+import type { BROADCAST_CHANNEL } from "../common-element";
+import type { NeutronElement as TNeutronElement } from "../neutron-element";
+import type { NeutronInternal as TNeutronInternal } from "../neutron-internal";
+import { Effect, Effector } from "./effect.types";
+import type {
+  BuiltConfig,
+  MapPropType,
+  NEvent,
+  OptsConfig,
+  OptsPropConfig,
+  PropTypeKey,
+} from "./element.types";
+import {
+  AnyFunction,
+  Constructor,
+  GuaranteedField,
+  NullField,
+} from "./shared.types";
+
+export type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+
+export type PropsConfigObj = Record<
+  string,
+  PropTypeKey | OptsPropConfig | Function
+>;
+
+export type ElementProps<P extends PropsConfigObj> = {
+  [Name in keyof P]: P[Name] extends OptsPropConfig
+    ? P[Name]["type"] extends Constructor
+      ? P[Name]["defaultValue"] extends Function
+        ? MapPropType<P[Name]["type"], P[Name]["defaultValue"]>
+        : MapPropType<P[Name]["type"]>
+      : never
+    : P[Name] extends Constructor
+      ? MapPropType<P[Name]>
+      : never;
+};
+
+export type BuildProps<P extends PropsConfigObj, CT> = CT extends {}
+  ? Omit<ElementProps<P>, keyof CT> & CT
+  : ElementProps<P>;
+
+declare const __customElement: unique symbol;
+
+export type CustomElement<Props> = TNeutronElement &
+  Props & { readonly [__customElement]?: Props };
+
+export interface ElementBuilder<
+  Conf extends OptsConfig,
+  CT,
+  Props = BuildProps<Conf["props"], CT>,
+  CE = CustomElement<Props>,
+> {
+  CustomElement: CE;
+  Props: Props;
+  Config: Conf;
+  CustomTypes: CT;
+  builtConfig: BuiltConfig;
+  /**
+   * Type-only: merge `T` into the element type up front, so methods in a
+   * single `defineMethods({...})` can reference each other through
+   * `element`. Runtime no-op.
+   */
+  withTypes<T>(): ElementBuilder<Conf, CT & T>;
+  defineMethods: <
+    FnObj extends Record<string, Effector<CE, Effect<Props>>>,
+    MethodSignatures = {
+      [Name in keyof FnObj]: <
+        RestArgs extends any[] = Parameters<FnObj[Name]> extends [
+          any,
+          ...infer Rest,
+        ]
+          ? Rest
+          : never,
+      >(
+        ...args: RestArgs
+      ) => ReturnType<FnObj[Name]> extends { returns: infer T } ? T : never;
+    },
+  >(
+    methods: FnObj
+  ) => ElementBuilder<Conf, CT & MethodSignatures>;
+  onConstructed(fn: Effector<CE, Effect<Props>>): this;
+  offConstructed(fn: AnyFunction): this;
+  onConnected(fn: Effector<CE, Effect<Props>>): this;
+  offConnected(fn: AnyFunction): this;
+  onDisconnected(fn: Effector<CE, Effect<Props>>): this;
+  offDisconnected(fn: AnyFunction): this;
+  onAdopted(fn: Effector<CE, Effect<Props>>): this;
+  offAdopted(fn: AnyFunction): this;
+  onError(fn: Effector<CE, Effect<Props>, [Error]>): this;
+  offError(fn: AnyFunction): this;
+  onPropSet<Name extends keyof Props & keyof CE>(
+    name: Name,
+    fn: Effector<GuaranteedField<CE, Name>, Effect<Props>, [Partial<Props>]>
+  ): this;
+  offPropSet(name: keyof Props, fn: AnyFunction): this;
+  onPropUnset<Name extends keyof Props & keyof CE>(
+    name: Name,
+    fn: Effector<NullField<CE, Name>, Effect<Props>, [Partial<Props>]>
+  ): this;
+  offPropUnset(name: keyof Props, fn: AnyFunction): this;
+  onPropChanged(
+    name: keyof Props | (keyof Props)[],
+    fn: Effector<CE, Effect<Props>, [Partial<Props>]>
+  ): this;
+  offPropChanged(name: keyof Props, fn: AnyFunction): this;
+  onEffect(
+    name: (keyof Props)[],
+    fn: Effector<CE, Effect<Props>, [Partial<Props>]>
+  ): this;
+  offEffect(name: (keyof Props)[], fn: AnyFunction): this;
+  onPromiseResolved<Name extends keyof Props>(
+    name: Name,
+    fn: Effector<CE, Effect<Props>, [Record<Name, UnwrapPromise<Props[Name]>>]>
+  ): this;
+  offPromiseResolved(name: keyof Props, fn: AnyFunction): this;
+  onPromiseRejected<Name extends keyof Props>(
+    name: Name,
+    fn: Effector<CE, Effect<Props>, [Record<Name, Error>]>
+  ): this;
+  offPromiseRejected(name: keyof Props, fn: AnyFunction): this;
+  onBroadcast(
+    name: string,
+    fn: Effector<
+      CE,
+      Effect<Props>,
+      [
+        NEvent<
+          typeof BROADCAST_CHANNEL | null,
+          typeof BROADCAST_CHANNEL,
+          CustomEvent
+        >,
+      ]
+    >
+  ): this;
+  offBroadcast(name: string, fn: AnyFunction): this;
+  onEvent(
+    name: string,
+    fn: Effector<CE, Effect<Props>, [NEvent<CE, Element | null, CustomEvent>]>
+  ): this;
+  offEvent(name: string, fn: AnyFunction): this;
+  onEventDefault(
+    name: string,
+    fn: Effector<CE, Effect<Props>, [NEvent<Element | null, CE, CustomEvent>]>
+  ): this;
+  offEventDefault(name: string, fn: AnyFunction): this;
+  /**
+   * Handle a `command` event whose `command` is one of `name` (custom
+   * commands only: `--verb`). Runs after the dispatch, in a microtask,
+   * unless a listener called `preventDefault()`.
+   */
+  onCommand(
+    name: string | string[],
+    fn: Effector<CE, Effect<Props>, [NEvent<CE, CE, TCommandEvent>]>
+  ): this;
+  offCommand(name: string | string[], fn: AnyFunction): this;
+  define: typeof TNeutronInternal.define;
+}

package/src/types/shared.types.ts

@@ -0,0 +1,25 @@
+export type GuaranteedFields<T> = {
+  [P in keyof T]: NonNullable<T[P]>;
+};
+
+export type GuaranteedField<T, K extends keyof T> = T &
+  GuaranteedFields<Pick<T, K>>;
+
+export type NullFields<T> = {
+  [P in keyof T]: null;
+};
+export type NullField<T, K extends keyof T> = T & NullFields<Pick<T, K>>;
+
+export type AnyFunction<Args extends any[] = any[], R = any> = (
+  ...args: Args
+) => R;
+
+export type Obj<U = {}> = Record<string, any> & U;
+
+export type PickGlobalElement<Tag> = Tag extends keyof HTMLElementTagNameMap
+  ? HTMLElementTagNameMap[Tag]
+  : HTMLElement;
+
+export type Constructor = abstract new (...args: any) => any;
+
+export type ConstructorType<T> = new (...args: any) => T;