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

api-viewer-element

Package Overview
Dependencies
Maintainers
1
Versions
47
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

api-viewer-element

Web Components API viewer element

  • 0.2.8
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
3.2K
increased by8.09%
Maintainers
1
Weekly downloads
 
Created
Source

<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

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.

Examples

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>

Section

By default, the API documentation is shown. If you want to show the playground instead, set the section property to demo:

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

Selected tag

By default, the first element found in JSON file is shown. Set the selected property to configure it to a different tag name:

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

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);
}

Templates

Use <template data-element="my-element"> for configuring complex content:

<api-viewer src="./custom-elements.json">
  <template data-element="fancy-accordion">
    <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

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

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 25 Nov 2019

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

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc