Birdseye
This project is under work in progress. Some features may not be implemented or have bugs. APIs would be changed near the future
Next generation component catalog.
Concept
- No need to write source code for each component guide.
- Essentially both build tool and view library agnostic.
- Use Web Components instead of iframe to encapsulate styles for better dev experience.
Getting Started
Birdseye currently supports the following view libraries. Please refer the guide for a lib that you are using.
- Vue.js
Vue.js with Vue CLI v3
Install @birdseye/app and @birdseye/vue in your Vue CLI project:
$ npm i -D @birdseye/app @birdseye/vueWriting catalog by code
Create catalog file:
// birdseye/catalogs/MyButton.catalog.js
import { catalogFor } from '@birdseye/vue'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, 'MyButton')
.add('primary', {
props: {
primary: true
},
slots: {
default: 'Button Text'
}
})
.add('hovered state', {
data: {
hover: true
},
slots: {
default: 'Hovered'
}
})Make birdseye/preview.js and bootstrap component catalog:
// birdseye/preview.js
import birdseye from '@birdseye/app'
// Load all your catalogs
const load = ctx => ctx.keys().map(x => ctx(x).default)
const catalogs = load(require.context('./catalogs/', true, /\.catalog\.js$/))
// Mount component catalog
birdseye('#app', catalogs)Serve the component catalog by running vue-cli-service:
$ npm run serve -- birdseye/preview.jsTweaking preview container style
When you want to modify preview container style (such as padding, background-color etc.), specify containerStyle option in your catalog:
import { catalogFor } from '@birdseye/vue'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, 'MyButton').add('white button', {
props: {
white: true
},
slots: {
default: 'Button Text'
},
// Make background color black
containerStyle: {
backgroundColor: 'black'
}
})The above example makes the preview background color black. You can specify any CSS properties in containerStyle option.
Injecting slots and scoped slots
You can inject slots and scoped slots by using slots option of add function. Pass a template string for a slot:
import { catalogFor } from '@birdseye/vue'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, 'MyButton')
.add('primary', {
props: {
primary: true
},
slots: {
// Directly pass template string for the slot
default: '<span>Button Text</span>'
}
})Pass a function for a scoped slot. The first argument is injected scoped slot props. You can get $createElement helper via this context:
import { catalogFor } from '@birdseye/vue'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, 'MyButton')
.add('primary', {
props: {
primary: true
},
slots: {
// Pass scoped slot function
default(props) {
const h = this.$createElement
return h('span', ['Button Text ', props.message])
}
}
})Wrapping catalog component with another element
You can use mapRender option to modify rendered element structure. mapRender should be a function that receives createElement function and original VNode object as arguments respectively.
The following example maps the catalog component with VApp component of Vuetify.
import { catalogFor } from '@birdseye/vue'
import { VApp } from 'vuetify/lib'
import MyButton from '@/components/MyButton.vue'
export default catalogFor(MyButton, {
name: 'MyButton',
// Define map function to render
mapRender: (h, vnode) => {
return h(VApp, [vnode])
}
}).add('white button', {
props: {
white: true
},
slots: {
default: 'Button Text'
}
})Writing catalog in SFC
Update the webpack config in vue.config.js:
module.exports = {
chainWebpack: config => {
if (process.env.NODE_ENV !== 'production') {
// Process <birdseye> custom block with @birdseye/vue/webpack-loader
// prettier-ignore
config.module
.rule('birdseye-vue')
.resourceQuery(/blockType=birdseye/)
.use('birdseye-vue-loader')
.loader('@birdseye/vue/webpack-loader')
}
}
}You write rendering patterns of a component in <birdseye> custom block. In each patterns item, you can specify props and data value which will be passed to the component. For example, in the following code, component guide will have two patterns for this component (named Test Component). The first pattern (Pattern Name 1) shows the component having "First pattern" as foo value and 123 as bar value.
<template>
<div>
<p>This is Vue.js component</p>
<p>foo value: {{ foo }}</p>
<p>bar value: {{ bar }}</p>
</div>
</template>
<script>
export default {
props: {
foo: {
type: String,
default: ''
}
},
data() {
return {
bar: 0
}
}
}
</script>
<birdseye>
{
"name": "Test Component",
"patterns": [
{
"name": "Pattern Name 1",
"props": {
"foo": "First pattern"
},
"data": {
"bar": 123
}
},
{
"name": "Pattern Name 2",
"props": {
"foo": "Second pattern"
},
"data": {
"bar": 456
}
}
]
}
</birdseye>Finally, make birdseye/preview.js and bootstrap component catalog:
import birdseye from '@birdseye/app'
import { instrument } from '@birdseye/vue'
// Load all your component
const load = ctx => ctx.keys().map(x => ctx(x).default)
const components = load(require.context('../src/components', true, /\.vue$/))
// Mount component catalog
birdseye('#app', instrument(components))You can serve the component catalog by running vue-cli-service:
$ npm run serve -- birdseye/preview.jsVisual Regression Testing
If you want to visual regression test your component catalog, use @birdseye/snapshot package. See docs of @birdseye/snapshot
License
MIT