vue-book

Tree view for your demo components. Demo.

Install

• npm: npm install -D vue-book
• yarn: yarn add -D vue-book

Versions

• Lastest build is a bit outdated and is not recommended (the one you get by npm install -D vue-book).
• Recent vue 2 version is 0.1.0-alpha.42.
• Recent vue 3 version is 0.2.0-alpha.0.

You shouldn't worry about sitting on alpha version as vue-book doesn't have dependencies and will work for a very long time without issues.

Features

• Display your components as a tree or flat list.
• Preview components on the page.
• Text search.
• Routing support.
• Saves on page reload.

The gist

I'll talk a bit about demo based workflow I employ in my projects.

Before doing any work on component I create a demo. Demo allows me to define an interface, like this:

<my-new-component v-model="dataItem" :some-prop="prop"/>

Only then I start to work on component.

You can think of demo as of semi-manual unit tests. But why not use actual unit tests, you'll ask. Let me explain.

• Demos are cheap. And you don't have to be a senior unit tester to create them.
• Demos are visual. In many cases you can see if something goes wrong. But unit tests won't show any of your styling mistakes.
• Demos are developer friendly. You can instantly find usage examples or just glance over existing components. Which is crucial for teamwork.

Of course, this doesn't mean that you have to dump unit tests. Just keep them for appropriate tasks. Like logic heavy classes.

So, back to the library. The main intent behind is simplifying demo workflow as much as possible. Just toss your demos into folder and enjoy tree generation.

Config

Attach VueComponentTree to your router. And yes, vue-router is required.

import Router from 'vue-router'
import { createRoute } from 'vue-book'

const router = new Router({
  routes: [
    createRoute({
      requireContext: require.context('./..', true, /.demo.vue$/), 
      path: '/demo',
      hideFileExtensions: true, // optional, hides file extensions in list.
      hideNavigation: true, // optional, hides navigation panel. Intended to be used with visual recognition library.
    }),
  ]
})

So, about arguments.

require.context('./../tree', true, /.vue$/), '/demo'

• ./../tree is path to your demo folder. Works the same as require/import.
• /demo is root route for vue-router.

Here's the vue-cli3 demo project if something doesn't work for you.

Production

You don't have to keep demos in production. Use webpack define-plugin and exclude them from bundle.

if (process.env.NODE_ENV !== 'production') {
  const createRoute = require('vue-book').createRoute
  
  routes.push([
    createRoute({
      requireContext: require.context('./..', true, /.demo.vue$/), 
      path: '/demo',
    }),
  ])
}

Deploy

• yarn serve - run dev server;
• yarn demo - compile assets;
• yarn dist - compile assets;
• npm publish - publish to npm.

Use as component

You can use vue-book without router if you don't need it.

const getComponent = require('vue-book').getComponent

const DemoView = getComponent({
  requireContext: require.context('./..', true, /.demo.vue$/),
})

You can handle resulting DemoView the same as any other vue component.

Feedback | Support

Leave an issue if something doesn't work for you.

Also remember: Stars fuel package development!

Hooks

In component you can use beforeRouteUpdate. Common case is to reset some global service.

Helper components [WIP]

Vue book provides a bunch of helper components to simplify demo-building.

VbDemo

Root level container.

VbCard

You can consider this component as both 'card' and 'test-case'.

Props

• title - string. Title of the card.
• noPadding - boolean. Removes padding of VbCard content
• dashed - boolean. Makes card border dashed, which makes it easier to see in some cases.
• refresh - boolean. Shows on card header a refresh button that redraws card content. Useful for testing reactivity.
• width - string. Card width.
• height - string. Card height.
• color - string. Card color.
• dark - boolean. Dark color theme.
• state - any. Allows to pass a state which will be accessible in a scoped slot. For details - see below.
• focus - boolean. If any VbCard is focused - only focused cards will be shown in demo. This is useful when you want to work on specific case and hide unneeded ones.
• error - boolean. Shows red border for card. Intended purpose is to help PR reviewer to mark buggy cases. In merged codebase better idea is to create issues.

State

state prop creates a scoped state for single card. That means you can create multiple cards, that use the same values, but they won't conflict. Intended as a substitute for declaring every prop in data.

<VbCard
  title="state example"
  :state="{value: false}"
  #default="{state}"
>
  <input type="checkbox" v-model="state.value">
</VbCard>

Install

import { VueBookComponents } from '../src/app'

Vue.use(VueBookComponents)

Component helpers

<VbDemo>
  <VbCard title="is active">
    <YourComponent is-active/>
  </VbCard>
</VbDemo>

Functional helpers:

<button @click="$vb.log('log', 'value')">Trigger log</button>
<button @click="$vb.alert('alert')">Trigger alert</button>
<div>Lorem text: {{ $vb.lorem() }}</div> 
<div>Lorem text of length: {{ $vb.lorem(5) }}</div>

Licence

MIT