vue-showroom v0.1.3
Vue Showroom
Vue Styleguide is an interactive living component styleguide that you embed directly into your application, instead of running a separate styleguide project and server.
Installation
npm install vue-showroom
or
yarn add vue-showroom
Here is an example page that displays Showroom:
<template>
<showroom-main id="showroom" :components="components" />
</template>
<script>
import ShowroomMain from 'vue-showroom'
import allComponents from /* some file that exports all your components in an array... */
export default {
name: 'showroom-page',
components: {
ShowroomMain
},
created() {
this.components = allComponents
}
}
</script>
<style>
@import '../../dist/vue-showroom.min.css';
#showroom {
height: 100%;
width: 100%;
margin: 0;
}
</style>
Note that you must provide an array of every component that you want to appear in Showroom. Consider maintaining this
list in a dedicated file (e.g. showroom-components.js
).
Configuring Examples
By default Showroom will display your component with no prop data and no slot content, will not capture any events, and
will leave your components uncategorized in the menu. To control how a components appears in Showroom the component must
have styleguide
field. For example:
export default {
name: 'my-button',
styleguide: {
category: 'Buttons',
}
}
This example puts the my-button
component into the "Buttons" category in to the Showroom menu. See below for all
options supported by the styleguide property.
Category
Example: category: 'Dialogs'
Names the grouping category that this component will appear under in the Showroom menu. If no category is provided then the component will be listed at the top of the menu without a category.
Events
Example: events: {dom: ['click'], vue: ['sign-in']}
Provides the names of events that Showroom should capture. This field must be an object with 2 optional keys: dom
and/or vue
. The dom
key is a list of DOM event names that should be captured. The vue
key is a list of custom
Vue events that should be captured.
Trigger
Example: trigger: { cancelEvent: 'cancel' }
Sometimes you may not want to show a component right away. In these cases you can provide a trigger
property. This
will cause Showroom to instead render trigger button instead of your actual component. When the button is clicked your
component will be shown.
You can also specify a cancelEvent
here to name a Vue event that, when triggered, will remove your component again.
Note that you must be capturing the cancel event for this to work (see "Events" above).
Examples
Example: examples: [ { props: { ... }, slots: { ... } ]
Provide a list of examples for your component.
Note: Only 1 example is supported today. Even though this property must be a list, only the first example will be used in Showroom.
Each example provides the prop data and/or slot content to use when rendering the example.
Props
Example: examples: [ { props: { value: 123, content: 'abc' } } ]
The values of prop data that will be passed to the component when rendering this example.
Slots
Example: examples: [ { slots: { title: 'A <em>good</em> title', button: ['a', 'b', 'c'] } } ]
The HTML to render in each slot. The values given here are passed as v-html
to each slot, so you can embed HTML here.
If a list of values is given for a slot name then that slot will be rendered once for each value.
Developing Showroom
- Run
yarn build
to build the releasable package - After building, go into the
test-site
directory and runyarn dev
to launch an example site that demonstrates Showroom's features