CEM Utility Functions

The following is a list of utility functions that are designed to help you work with the Custom Elements Manifest (CEM) and make it easier to use the documentation for your web components.

Note

Many of these methods use the Custom CEM Types, so please take a look at those documentation for more detailed information about how to use them.

Installation

npm install -D @wc-toolkit/cem-utilities

Get All Components

The getAllComponents function returns an array of all the components in the CEM.

import { getAllComponents } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const components = getAllComponents(manifest);

This is a generic function, so if you have defined custom fields that you would like to strongly type, you can pass in a type parameter.

const components = getAllComponents<MyCustomComponentType>(manifest);

Get Component By Tag

The getComponentByTag function returns a single component from the CEM by its tag name.

import { getComponentByTag } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const component = getComponentByTag(manifest, 'my-component');

This is a generic function, so if you have defined custom fields that you would like to strongly type, you can pass in a type parameter.

const component = getComponentByTag<MyCustomComponentType>(manifest, 'my-component');

Get Component By Class Name

The getComponentByClassName function returns a single component from the CEM by its class name.

import { getComponentByClassName } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const component = getComponentByClassName(manifest, 'MyComponent');

This is a generic function, so if you have defined custom fields that you would like to strongly type, you can pass in a type parameter.

const component = getComponentByClassName<MyCustomComponentType>(manifest, 'MyComponent');

Get Component Public Properties

The getComponentPublicProperties function returns an array of all the public properties for a component.

import { getComponentPublicProperties } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const component = getComponentByTag(manifest, 'my-component');
const properties = getComponentPublicProperties(component);

This is a generic function, so if you have defined custom fields that you would like to strongly type, you can pass in a type parameter.

const properties = getComponentPublicProperties<MyCustomPropertyType>(component);

Get Component Public Methods

The getComponentPublicMethods function returns an array of all the public methods for a component.

import { getComponentPublicMethods } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const component = getComponentByTag(manifest, 'my-component');
const methods = getComponentPublicMethods(component);

This is a generic function, so if you have defined custom fields that you would like to strongly type, you can pass in a type parameter.

...
const methods = getComponentPublicMethods<MyCustomMethods>(component);

This function adds a type to the standard CEM ClassMethod type. This reconstructs the parameters, default values, and return type properties to create a complete TypeScript type.

Before:

{
  "kind": "method",
  "name": "setCustomValidity",
  "parameters": [
    {
      "name": "message",
      "type": {
        "text": "string"
      }
    }
  ],
  "description": "Sets a custom validation message. Pass an empty string to restore validity."
}

After:

{
  "kind": "method",
  "name": "setCustomValidity",
  "parameters": [
    {
      "name": "message",
      "type": {
        "text": "string"
      }
    }
  ],
  "description": "Sets a custom validation message. Pass an empty string to restore validity.",
  "type": {
    "text": "setCustomValidity(message: string) => void"
  }
}

Get Component Events

The getComponentEventsWithType function returns an array of all the events for a component.

import { getComponentEventsWithType } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const component = getComponentByTag(manifest, 'my-component');
const events = getComponentEventsWithType(component);

This is a generic function, so if you have defined custom fields that you would like to strongly type, you can pass in a type parameter.

const events = getComponentEventsWithType<MyComponentEventType>(component);

This function updates the type value to be more complete and accurate. For example, if you are defining a type in your event’s JSDoc, that is typically the type for the event’s detail property.

/**
 *
 * @tag my-component
 * @event {MyEventDetailType} my-event - This is a custom event
 */
class MyComponent extends HTMLElement {
  ...
}

This function will update the type to include the CustomEvent type and the type from the JSDoc. The type.text property will be updated CustomEvent<MyEventDetailType>.

If the event does not have a custom detail type, the type.text property will be updated to CustomEvent.

If the event is emitting a native DOM event like one from the list below, the type.text property will use that event name.

/**
 *
 * @tag my-component
 * @event {InputEvent} input - Documenting input event
 */
class MyComponent extends HTMLElement {
  ...
}

The type.text property will be updated to InputEvent.

const NATIVE_DOM_EVENTS = [
  "AnimationEvent",
  "BeforeUnloadEvent",
  "ClipboardEvent",
  "DragEvent",
  "Event",
  "FocusEvent",
  "HashChangeEvent",
  "InputEvent",
  "KeyboardEvent",
  "MessageEvent",
  "MouseEvent",
  "MutationObserver",
  "PageTransitionEvent",
  "PointerEvent",
  "PopStateEvent",
  "ProgressEvent",
  "StorageEvent",
  "TouchEvent",
  "TransitionEvent",
  "UIEvent",
  "WebGLContextEvent",
  "WheelEvent",
];

Event Options

There are a few options that can be passed in the options parameter to control the behavior of the getComponentEventsWithType function.

/** The type used to define the configuration options for the `getComponentEventsWithType` function */
type EventOptions = {
  /** The name of the property where custom detail type is stored */
  customEventDetailTypePropName?: string;
  /** Overrides the event type from `CustomEvent` to the type specified in the event type in the CEM */
  overrideCustomEventType?: boolean;
};

Custom Event Detail Type

If you have a custom event detail type, you use the customEventDetailTypePropName property in the functions options parameter to specify the property name where the custom detail type is stored.

const events = getComponentEventsWithType(component, { customEventDetailTypePropName: 'parsedType' });

Override Custom Event Type

If you want to override the event type from CustomEvent to the type specified in the event type in the CEM, you can use the overrideCustomEventType property in the functions options parameter.

const events = getComponentEventsWithType(component, { overrideCustomEventType: true });

/**
 *
 * @tag my-component
 * @event {MyComponentEvent} my-event - Documenting input event
 */
class MyComponent extends HTMLElement {
  ...
}

The type.text property will be updated to MyComponentEvent instead of CustomEvent<MyComponentEvent>.

Get Custom Event Detail Types

The getCustomEventDetailTypes function returns an array of all the custom event detail types for a component. This is often used for generating a list of event names for an import in a type definition file. If the event detail type is not a named type, custom type, or a generic, it will not be included in the list.

import { getCustomEventDetailTypes } from '@wc-toolkit/cem-utilities';
import manifest from './path/to/your/manifest.json' with { type: 'json' };

const component = getComponentByTag(manifest, 'my-component');
const customEventDetailTypes = getCustomEventDetailTypes(component);

A list of excluded types can also be passed in as a parameter.

const customEventDetailTypes = getCustomEventDetailTypes(component, ['Type1', 'Type2']);