@crishellco/vue-spruce NPM

Vue Spruce

A collection of useful Vue 2 renderless components.

Check out the demo

Install

Package

yarn add -D @crishellco/vue-spruce
# or
npm i -D @crishellco/vue-spruce

Vue Plugin

Installs all components globally.

import Vue from 'vue';
import VueSpruce from '@crishellco/vue-spruce';

Vue.use(VueSpruce);
// or with options
Vue.use(VueSpruce, { componentPrefix: 's' });

Nuxt Module

Installs all components globally.

// nuxt.config.js
{
  modules: [['@crishellco/vue-spruce/nuxt', { componentPrefix: 's' }]];
}

Options

Name	Description	Default
`componentPrefix`	The prefix used when installing components globally	`spruce`

Named Imports

Alternatively, use only the components you need.

import {
  SpruceAtLeast,
  SpruceCling,
  SpruceEvent,
  SpruceFetch,
  SpruceFunction,
  SprucePaginate,
  SpruceSearch,
  SpruceSort,
  SpruceState,
  SpruceToggle,
  SpruceWatch,
} from '@crishellco/vue-spruce';

export default {
  components: {
    SpruceAtLeast,
    SpruceCling,
    SpruceEvent,
    SpruceFetch,
    SpruceFunction,
    SprucePaginate,
    SpruceSearch,
    SpruceSort,
    SpruceState,
    SpruceToggle,
    SpruceWatch,
  },
};

The Components

SpruceAtLeast

Ensures a component shows for at least a given amount of time, in milliseconds, before hiding.

<spruce-at-least :ms="5000" :show="shouldShowImage">
  <div slot-scope="{ disabled, show }">
    <img v-if="show" src="https://placebeard.it/g/200/300" alt="" />

    <button :disabled="disabled" @click="shouldShowImage = !shouldShowImage">
      {{ disabled ? 'waiting...' : show ? 'hide' : 'show' }}
    </button>
  </div>
</spruce-at-least>

Props

Name	Description	Type	Required	Default
`ms`	Minimum amount of time to show, in milliseconds	Number	Yes
`show`	Weather or not to show the contents (given enough time has passed)	Boolean	No	`true`

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`disabled`	True if waiting to hide content after `ms` time has passed	Boolean
`default`	`show`	If the contents should be shown	Boolean

SpruceCling

Clings the clinger slot's contents to the anchor slot's contents using popper.js. Great for things like dropdown menus. See the demo for more context.

<spruce-cling placement="bottom">
  <template #anchor>
    <button>
      i'm a button
    </button>
  </template>
  <template #clinger>
    <div>
      <div>i'm a clinger!</div>
    </div>
  </template>
</spruce-cling>

Props

Name	Description	Type	Required	Default
`modifiers`	The popper.js modifiers	Array	No	`[]`
`placement`	The popper.js placement of the `clinger` in relation to the `anchor`	String	No	`auto`

Slots

Name	Required
`anchor`	Yes
`clinger`	Yes

Slot Scope

Slot	Name	Description	Type
`anchor`	`update`	Updates the popper instance	Function
`clinger`	`update`	Updates the popper instance	Function

SpruceEvent

Track any window event occurance inside or outside of SpruceEvent's default slot.

<spruce-event event="mouseover" @mouseover="someMethod">
  <button>Hover over me!</button>
</spruce-event>

Props

Name	Description	Type	Required	Default
`event`	The event to listen to	String	Yes
`immediate`	First event immediately (in `mounted`)	Boolean	No	`false`
`outside`	Listen for the even only outside of the default slot elements	Boolean	No	`false`

Events

Name	Description	Payload
Same as the `event` prop	Fired when the event happens.	--

Slots

Name	Required
`default`	No

SpruceFetch

Make asynchronous API fetch calls.

<spruce-fetch url="https://dog-api.kinduff.com/api/facts" >
  <div slot-scope="{ loading, data, error, fetch }">
    <loading-indicator v-if="loading" />
    <div v-else-if="errors">Errors! {{ error.status }}</div>
    <div v-else>Data: {{ data }}</div>
    <button @click="fetch">Refetch</button>
  <div>
</spruce-fetch>

Props

Name	Description	Type	Required	Default
`url`	The API url (changing this will refetch and rest all data)	String	Yes
`immediate`	Weather to immediate make the request on mount	Boolean	No	`true`

Events

Name	Description	Payload
`success`	Fires when the request is successful	`{data: Object, fetch: Function}`
`error`	Fires when the request fails	`{data: Object, fetch: Function}`

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`calls`	Number of calls made	Number
`default`	`data`	The response on a successful request	Object
`default`	`error`	The response on a failed request	`{ data: Object, status: Number }`
`default`	`loading`	Whether a request is in progress	Boolean
`default`	`fetch`	Makes another request	Function

SpruceFunction

Create reusable functions on the fly (great for lists!).

<div v-for="num in 10">
  <spruce-function :fn="() => alert(num)">
    <button slot-scope="{ fn }" @click="fn">Click me!</button>
  </spruce-function>
</div>

Props

Name	Description	Type	Required	Default
`fn`	The function	Function	Yes

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`fn`	The function	Function

SprucePaginate

Paginate an array and navigate through it's chunks.

<spruce-paginate :list="states" :size="15">
  <div slot-scope="{ page, next, prev, pageNum, totalPages, isFirst, isLast, rangeStart, rangeEnd }">
    <button :disabled="isFirst" @click="prev">
      prev
    </button>
    <div class="px-4 flex flex-col items-center">
      <div>Page: {{ pageNum }}/{{ totalPages }}</div>
      <div>Showing: {{ rangeStart }} - {{ rangeEnd }} of {{ states.length }}</div>
    </div>
    <button :disabled="isLast" @click="next">
      next
    </button>
  </div>
</spruce-paginate>

Props

Name	Description	Type	Required	Default
`size`	Page size	Number	Yes
`list`	The items to paginate	Array	Yes

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`first`	Go to first page	Function
`default`	`go`	Go to specific page	Function
`default`	`isFirst`	If currently on first page	Boolean
`default`	`isLast`	If currently on last page	Boolean
`default`	`last`	Go to last page	Function
`default`	`next`	Go to next page	Function
`default`	`page`	The current page	any
`default`	`pages`	The chunked pages	Array
`default`	`links`	A calculated array of specific page numbers that can be used for links `[1, 2, 3, '...', 40]`	Array
`default`	`pageNum`	The current page number	Number
`default`	`prev`	Go to previous page	Function
`default`	`rangeEnd`	The end of the current page	Number
`default`	`rangeStart`	The start of the current page	Number
`default`	`reset`	Reset the state of pagination	Function
`default`	`totalPages`	Total number of pages	Number

SpruceSearch

Search an array of strings or objects by keys using fuse.js.

<spruce-search :list="states" :term="term" :keys="['name', 'email']">
  <div slot-scope="{ results }">
    <div v-for="(item, index) in results" :key="index">
      {{ item }}
    </div>
  </div>
</spruce-search>

Props

Name	Description	Type	Required	Default
`keys`	The keys to search in	Array	No	If `list` is `Array<Object>` then all of the first object's keys. Otherwise `[]`.
`list`	The list to search	Array	Yes
`term`	The terms to search for	String	No	''
`threshold`	Fuse.js match threshold	Float	No	0.6

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`results`	The searched list	Array

SpruceSort

Sort an array of strings or objects in either direction by specific keys.

Note: string sorting is case insensitive.

<spruce-sort :list="people" :by="by" :direction="direction">
  <div slot-scope="{ results }">
    <div v-for="(item, index) in results" :key="index">
      {{ item }}
    </div>
  </div>
</spruce-sort>

Props

Name	Description	Type	Required	Default
`list`	The list to search	Array	Yes
`direction`	The direction to sort in, 'asc' or 'desc'	String	No	'asc'
`by`	The object property to sort by	String	No	''

Events

Name	Description	Payload
`change`	Fired when `results` change (the list is sorted).	`results`

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`results`	The searched list	Array<String, Object>

SpruceState

Create and manage localized state.

<spruce-state :value="{ count: 0 }">
  <div slot-scope="{ count, set }">
    <button @click="set({count: count + 1})">
      Increment ({{ count }})
    </button>
  </div>
</spruce-state>

Props

Name	Description	Type	Required	Default
`value`	The state object	Object	Yes

Events

Name	Description	Payload
`input`	Fired when state updates	`state`

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`[key]`	Each key in the `state` prop	Any
`default`	`set(newValue)`	Merges `newValue` with the current `state`	Function

SpruceTagInput

Renderless tag input.

<template>
  <spruce-tag-input v-model="colors" :validator="validator">
    <div
      slot-scope="{ events, focusedTagIndex, invalid, remove, state, tags }"
      :class="{ 'border-red-500': invalid }"
    >
      <button
        v-for="(tag, index) in tags"
        :key="index"
        type="button"
        :class="{ 'bg-red-500': focusedTagIndex === index }"
        title="Remove tag"
        @click="remove(tag)"
      >
        <span>{{ tag }}</span>
        <span>&times;</span>
      </button>
      <input v-bind="state" placeholder="Add tag with letters only..." v-on="events" />
    </div>
  </spruce-tag-input>
</template>

<script>
export default {
  data() {
    return { colors: ['red', 'blue'] };
  },

  methods: {
    validator(tag) {
      return /^[a-zA-Z]+$/.test(tag);
    },
  },
};
</script>

Props

Name	Description	Type	Required	Default
`allowDuplicates`	Allows duplicate tags	Boolean	No	`False`
`allowPaste`	Allows pasting to automatically create tags	Boolean	No	`False`
`disabled`	Disables all interactions	Boolean	No	`False`
`keepOnBackspace`	Disables deleting last tab on `keyup.backspace` in the input	Boolean	No	`False`
`maxTags`	Number of allowed tags	Number	No	`Null`
`separator`	Separator used to process pasted tags	String	No	`\t`
`v-model`	The tags	Array	Yes
`validator`	Function that receives the String argument `tag` and returns `true` or `false` to determine the validity of the input's value	Function	No	`() => true`

Slot Scope

Slot	Name	Description	Type
`default`	`events`	Events to listen for on the input. `input` for binding value, `keydown.backspace` for delete last tag, `keydown.enter` for adding new unique tag, and `keydown.escape` for clearing input.	Object
`default`	`focusedTagIndex`	Currently focused tag index (to be removed on next `keydown.backspace`). Used for styling.	String
`default`	`remove()`	Removes a tag	Function
`default`	`state`	State to bind to the input. `value` of the input.	Object
`default`	`tags`	Array of tags	Array

SpruceToggle

Toggle between on (true) and off (false).

<spruce-toggle :value="true">
  <div slot-scope="{ isOn, on, off, toggle }">
    <div>
      <span>Accordion header</span>
      <span @click="toggle">{{ isOn ? '▲' : '▼' }}</span>
    </div>
    <div v-if="isOn">
      Accordion content
    </div>
    <div>
      <button @click="on">Open</button>
      <button @click="off">Close</button>
    </div>
  </div>
</spruce-toggle>

Props

Name	Description	Type	Required	Default
`value`	The state of the toggle	Boolean	No	`False`

Events

Name	Description	Payload
`input`	Fired when `isOn` updates	`isOn`

Slots

Name	Required
`default`	Yes

Slot Scope

Slot	Name	Description	Type
`default`	`isOn`	The state of the toggle	Boolean
`default`	`on()`	Sets `isOn` to `true`	Function
`default`	`off()`	Sets `isOn` to `false`	Function
`default`	`toggle()`	Toggles `isOn`	Function

SpruceWatch

Watches variables for changes and emits events when changes occur.

<spruce-watch :watch="{count}" @changed="handleAnyChange" @changed:count="handleCountChange">
  <button @click="count++">
    count++ ({{ count }})
  </button>
</spruce-watch>

Props

Name	Description	Type	Required	Default
`watch`	Values you wish to watch	Object	Yes

Events

Name	Description	Payload
`changed`	Fired when any value in `watch` changes	`{key: count, oldValue: 0, newValue: 1}`
`changed:[key]`	Fired when a specific value in `watch` changes	`{oldValue: 0, newValue: 1}`