vue-elucidate

Elucidate

A library that makes it a breeze to "shed light" on your Vue component.

Demo: https://mattrothenberg.github.io/vue-elucidate-example

Demo Video: https://streamable.com/eir1u

Installation (Yarn)

yarn add vue-elucidate

Installation (in a Vue project)

import Elucidate from 'vue-elucidate'
Vue.use(Elucidate)

Usage

<elucidate :component="button" :example="example"></elucidate>

The <elucidate> component takes two props, component and example.

The former is, quite literally, a single Vue component (either imported into your current app, or defined inline), or an array of Vue components.

The latter is either a single example object shaped thusly, or an array of example objects shaped thusly:

Key	Value
markup	An HTML code snippet that you would like to document
props	An object defining the props referenced by your HTML code snippet
methods	An object defining the methods referenced by your HTML code snippet
name	(OPTIONAL) A display name for the given component if part of an array of examples

How does it work?

Let's assume you have a component named custom-button. It's defined in custom-button.vue thusly:

<template>
  <button :class="classList">
    <slot></slot>
  </button>
</template>
 
<script>
  export default {
    name: 'custom-button',
    props: {
      variant: {
        type: String,
        default: 'primary'
      },
      size: {
        type: String,
        default: 'medium'
      }
    },
    computed: {
      classList () {
        return `btn-${this.variant} btn-${this.size}`
      }
    }
  }
</script>
 
<style>
  .btn-primary {
    background: blue;
    color: white;
  }
 
  .btn-small {
    font-size: 12px;
  }
</style>

Elucidate works by:

• Rendering an example code snippet, e.g., <custom-button size="small">Hello</custom-button>
• Documenting that snippet, as well as any props/functions that were passed to it
• Documenting all of the props exposed by <custom-button>, in this case variant and size.

So, the following code:

<elucidate :component="button" :example="example"></elucidate>

import CustomButton from '@/components/CustomButton'
import '@/darcula.css'
 
export default {
  data () {
    return {
      button: CustomButton,
      example: {
        markup: `<custom-button size="small">Hello</custom-button>`
      }
    }
  }
}

...would produce the following result:

Customization

Elucidate is very customizable. I've included some light CSS here and there to make things look half-way decent. Here are a few guidelines for customization.

BYOCSS

Elucidate uses Prism JS for syntax highlighting. Elucidate doesn't ship out-of-the-box with a particular syntax highlighting theme, so feel free to pick one from Prism Themes

Default CSS

Include Elucidate's default styles by including the following line of code in your project:

import 'vue-elucidate/dist/style.css'

Elucidate maintains a light footprint, and affords you the following classes for purposes of customization:

.elucidate-example-picker {}
 
.elucidate-example-picker label {}
 
.elucidate-select {}
 
.elucidate-select select {}
 
.elucidate-select::after {}
 
@supports (-webkit-appearance: none) or (appearance: none) or ((-moz-appearance: none) and (mask-type: alpha)) {
  .elucidate-select::after {
  }
 
  .elucidate-select select {}
 
  .elucidate-select select:focus {}
}
 
.elucidate-preview {}
 
.elucidate-tabs {}
 
.elucidate-tabs .nav-tabs {}
 
.elucidate-tabs .tab {}
 
.elucidate-tabs .tab:hover {}
 
.elucidate-tabs .tab.active {}
 
.elucidate-tabs .tab:not(:last-of-type) {}
 
.elucidate-tabs .tab a {}
 
.elucidate-table-wrap {}
 
.elucidate-table {}
 
.elucidate-table th {}
 
.elucidate-table td {}

To-Do

• Test Coverage
• Accommodate multiple components in a single example
• Accommodate multiple examples
• Investigate slot-based API for further customization of sub-components