Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More

api-viewer-element

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

api-viewer-element

Web Components API viewer element


Version published
Maintainers
1
Created

<api-viewer>

API documentation and live playground for Web Components. Based on web-component-analyzer JSON format.

<api-viewer src="./custom-elements.json"></api-viewer>

Live Demo ↗

Screenshot of api-viewer docs

Screenshot of api-viewer demo

Features

  • API docs viewer
    • Properties - JS properties publicly exposed by the component
    • Attributes - HTML attributes (except those that match properties)
    • Events - DOM events dispatched by the component
    • Slots - default <slot> and / or named slots, if any
    • CSS Custom Properties - styling API of the component
    • CSS Shadow Parts - elements that can be styled using ::part
  • Live playground
    • Source - code snippet matching the rendered component
    • Knobs - change properties and slotted content dynamically
    • Styles - change values of the custom CSS properties
    • Event log - output the events fired by the component
    • Templates - configure complex slotted content

Install

$ npm install api-viewer-element

Or grab from unpkg.com CDN:

<script src="https://unpkg.com/api-viewer-element?module" type="module"></script>

Usage

  1. Install web-component-analyzer:
$ npm install -g web-component-analyzer
  1. Analyze your components using --format json:
$ wca analyze my-element.js --outFile custom-elements.json --format json
  1. Create an HTML file and import the component:
<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import 'api-viewer-element';
    </script>
  </head>

  <body>
    <api-viewer src="./custom-elements.json"></api-viewer>
  </body>
</html>
  1. Use es-dev-server to serve your HTML page.

Usage options

Starting from 0.4.0 release, the following components are available:

<api-viewer> element

A custom element that provides both API docs and live playground.

import 'api-viewer-element';

<api-docs> element

A custom element that only provides API docs (no live playground).

import 'api-viewer-element/lib/api-docs.js';

<api-demo> element

A custom element that only provides live playground (no API docs).

import 'api-viewer-element/lib/api-demo.js';

Playground

Import the components documented in JSON file to enable demos:

<script type="module">
  import 'my-element';
</script>
<api-viewer src="./custom-elements.json"></api-viewer>

In order to ensure that all the playground features work properly and knobs for properties and CSS custom properties are in sync, please read the following sections and update the code of your custom elements accordingly if needed.

Knobs

The playground listens to all the events dispatched by the rendered component. This can be used to sync knobs with the property changes caused by the user. In order to make it work, dispatch and document [property]-changed events:

/**
 * A custom element that fires event on value change.
 *
 * @element my-element
 *
 * @prop {String} value - Value of the component
 * @fires value-changed - Event fired when value is changed
 */

Styles

The playground collects the default values for the documented CSS custom properties on the rendered component using getComputedStyle(element).getPropertyValue(). In order to make it work, use the following CSS structure:

:host {
  --button-color: red;
}

button {
  color: var(--button-color);
}

Configuration

Properties

The following properties can be set on the <api-viewer> element:

section

Use section property to toggle between demo and API docs:

<api-viewer src="./custom-elements.json" section="demo"></api-viewer>
selected

Use selected property to configure the displayed element:

<api-viewer src="./custom-elements.json" selected="my-element"></api-viewer>
exclude-knobs

Use exclude-knobs attribute to exclude properties from demo:

<api-viewer src="./custom-elements.json" exclude-knobs="autofocus,items"></api-viewer>
elements

Use elements property instead of src to pass data directly:

<api-viewer></api-viewer>
<script>
  fetch('./custom-elements.json')
    .then(res => res.json())
    .then(data => {
      document.querySelector('api-viewer').elements = data.tags;
    });
</script>

Methods

setTemplates

Use setTemplates method to override <template> elements:

// gather the template elements placed in the DOM
const templates = document.querySelectorAll('template[data-target]');

// configure the api-viewer to use the templates
document.querySelector('api-viewer').setTemplates(templates);

Note: the method is available on api-viewer and api-demo elements only. Corresponding base classes do not have it. When extending a base class, you have to re-implement it yourself if you need to preserve the existing behavior.

Templates

The following templates can be passed to <api-viewer> element:

<template data-target="host">

Use "host" template to configure property values:

<api-viewer src="./custom-elements.json">
  <template data-element="progress-bar" data-target="host">
    <progress-bar max="100" min="1" value="50"></progress-bar>
  </template>
</api-viewer>
<template data-target="slot">

Use "slot" template to configure complex content:

<api-viewer src="./custom-elements.json">
  <template data-element="fancy-accordion" data-target="slot">
    <expansion-panel>
      <div slot="header">Panel 1</div>
      <div>Content 1</div>
    </expansion-panel>
    <expansion-panel>
      <div slot="header">Panel 2</div>
      <div>Content 2</div>
    </expansion-panel>
  </template>
</api-viewer>

Note: do not minify HTML to keep proper indentation.

Styling

Custom CSS properties

The following custom CSS properties are available:

PropertyDescription
--ave-accent-colorAccent color, used for property names
--ave-border-colorColor used for borders and dividers
--ave-border-radiusBorder radius used for the outer border
--ave-button-active-backgroundColor of the :focus and :hover button
--ave-button-backgroundBackground of the button (code snippet, events)
--ave-button-colorColor of the button (code snippet, events)
--ave-header-colorHeader text color used for tag name
--ave-item-colorAPI items content color (main text)
--ave-label-colorAPI items labels color
--ave-link-colorAPI description links default color
--ave-link-hover-colorAPI description links hover color
--ave-monospace-fontMonospace font stack for the API items
--ave-primary-colorPrimary color, used for header and active tab
--ave-tab-colorInactive tabs color
--ave-tab-indicator-sizeSize of the selected tab indicator

CSS shadow parts

The following CSS shadow parts are available:

Common UI parts

PartDescription
headerHeader containing element name and navigation controls
header-titleTitle element placed in the header (element tag name)
tab<api-viewer-tab> component used in docs and demo
tab-panel<api-viewer-panel> component used in docs and demo
warningMessage shown when no elements or API docs are found
API docs
PartDescription
docs-descriptionCustom element description
docs-columnColumn, child of a docs-row part
docs-itemItem representing a single entry (property, event etc)
docs-labelLabel (name, attribute, type, description)
docs-markdownIem description with parsed markdown content
docs-rowRow containing columns. Child of a docs-item part
docs-valueSibling of a docs-label part (name, attribute, type)
md-h1Markdown <h1> elements
md-h2Markdown <h2> elements
md-h3Markdown <h3> elements
md-h4Markdown <h4> elements
md-h5Markdown <h5> elements
md-h6Markdown <h6> elements
md-aMarkdown <a> elements
md-pMarkdown <p> elements
md-ulMarkdown <ul> elements
md-olMarkdown <ol> elements
md-liMarkdown <li> elements
md-preMarkdown <pre> elements
md-codeMarkdown <code> elements
md-strongMarkdown <strong> elements
md-emMarkdown <em> elements
md-blockquoteMarkdown <blockquote> elements
md-delMarkdown <del> elements
Live demo
PartDescription
demo-outputWrapper of the rendered component in the live demo
demo-tabsTabs component used to switch panels in the live demo
event-logWrapper of the event log tab content
event-record<p> used as a record in the event log
knobsWrapper of in the properties / styles knobs panel
knobs-columnColumn in the properties / styles knobs panel
knobs-headerHeader of the properties / styles knobs column
knob-labelLabel associated with an input in the knobs panel
Interactive elements
PartDescription
button<button> used to copy code / clear events log
checkbox<input type="checkbox"> used by boolean knobs
input<input type="text"> used by knobs
radio-button<input type="radio"> used to toggle docs / demo
radio-label<label> associated with the radio button element
select<select> used to choose displayed component
select-label<label> associated with the select element

Read more about using ::part() at MDN Web Docs.

Contributing

Install dependencies

$ yarn

Run demo in browser

$ yarn dev

Open http://127.0.0.1:8081/demo/

Create dist folder

$ yarn dist

Serve dist folder

$ yarn serve:dist

Acknowledgements

FAQs

Package last updated on 27 Mar 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts