Custom-elements-manifest-deprecator NPM

Custom Elements Manifest Deprecator

This package is designed to provide a mechanism to deprecate items in your the Custom Elements Manifest.

The standard approach is to use the @deprecated tag in the JSDoc descriptions.

/**
 * @deprecated This deprecates the class
 *
 */
class MyElement extends HTMLElement {
  /** @deprecated This deprecates the property */
  deprecatedProperty = "some value";
}

The problem is that you can't add it to other elements with JSDoc tags.

/**
 * @attr {boolean} disabled - disables the element
 *
 * @csspart bar - Styles the color of bar
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 *
 * @prop {boolean} prop1 - some description
 *
 * @fires custom-event - some description for custom-event
 * @event {MyEventDetail} typed-custom-event - some description for typed-custom-event
 */
class MyElement extends HTMLElement {}

This plugin allows you to deprecate these JSDoc elements using the (@deprecated) string (or one of your choosing). Without wrapping it in the parenthesis, it will deprecate the class instead of the JSDoc element.

/**
 * @attr {boolean} disabled - (@deprecated) disables the element
 *
 * @csspart bar - (@deprecated) Styles the color of bar
 *
 * @slot - (@deprecated) This is a default/unnamed slot
 * @slot container - (@deprecated) You can put some elements here
 *
 * @cssprop --text-color - (@deprecated) Controls the color of foo
 *
 * @prop {boolean} prop1 - (@deprecated) some description
 *
 * @fires custom-event - (@deprecated) some description for custom-event
 * @event {MyEventDetail} typed-custom-event - (@deprecated) some description for typed-custom-event
 */
class MyElement extends HTMLElement {}

Feel free to test it out in this demo environment.

Usage

This package includes two ways to generate an updated Custom Elements Manifest:

calling a function in your build pipeline
as a plugin for the Custom Element Manifest Analyzer.

Install

npm i -D custom-elements-manifest-deprecator

Build Pipeline

import { updateCemDeprecations } from "custom-elements-manifest-deprecator";
import manifest from "./path/to/custom-elements.json";

const options = {...};

updateCemDeprecations(manifest, options);

CEM Analyzer

Set-up

Ensure the following steps have been taken in your component library prior to using this plugin:

Install and set up the Custom Elements Manifest Analyzer
Create a config file

Import

// custom-elements-manifest.config.js

import { cemInheritancePlugin } from "custom-elements-manifest-deprecator";

const options = {
  /* add options here */
};

export default {
  plugins: [cemDeprecatorPlugin(options)],
};

Configuration

There are a number of configurations you can apply to customize the output for your components.

interface Options {
  /** The value used to indicate an element is deprecated - default is "(@deprecated)" */
  indicator?: string;
  /** When `true` the indicator will be included in the final description - default is `false` */
  preserveIndicator?: boolean;
  /** Name of the updated CEM file - default is "custom-elements.json" */
  fileName?: string;
  /** Path to output directory */
  outdir?: string;
  /** Class names of any components you would like to exclude from inheritance */
  exclude?: string[];
}

Indicator

This value is used to indicate whether the tag element is deprecated. The default value is "(@deprecated)", but you can set this to whatever value you would like - "retired", '@legacy', etc.

Preserve Indicator

When the indicator is found in a description, it will remove the value from the string (similar to the default @deprecated tag behavior). If you would like to keep the indicator in the description, you can se the preserveIndicator property to true.

`fileName` and `outdir`

If you would like to add your updated Custom Elements Manifest to a specific location in your project, you can use the fileName and outdir setting for that. Otherwise, the updated manifest will be default location - ./custom-elements.json.

NOTE: If you are using the CEM Analyzer, you do not need to set these options. It will allow the analyzer to handle it based on your configuration.