v-eye

v-eye

The v-eye package provides a set of compound components to create groups of selectable items out of any component. You can see it as the baseline functionality for components like tabs, button-groups, accordions, carousels and possibily others.

It's heavily inspired in Vuetify's v-item-group without all the vuetify wiring attached.

Installation

Using a package package manager

yarn add v-eye

Usage

By default, all components render an un-styled root node div with all bindings attached. If you want to bind the logic to your own custom components, use as-template prop and turn them into renderless/headless providers and all bindings are exposed via default slot-scope. Remember that, due to Vue2 limitation, a single root node must be provided.

Basic: a Disclosure component.

Basically it's an equivalent of <details><summary> native implementation, but state-driven.

<!-- your disclosure.vue -->
<template>
  <v-eye v-model="active">
    <v-eye-switch>Summary toggler</v-eye-switch>
    <v-eye-content>Details</v-eye-content>
  </v-eye>
</template>

<script>
import { VEye, VEyeSwitch, VEyeContent } from 'v-eye'

export default {
  name: 'Disclosure',
  components: { VEye, VEyeSwitch, VEyeContent },
  data: () => ({
    active: false
  })
}

Basic: A password input visibility toggler

<!-- your-password-input.vue -->
<template>
  <div class="your-app-input">
    <input :type="inputType">
    <v-eye v-model="isPasswordVisible">
      <v-eye-switch>
        <your-app-icon :icon="isPasswordVisible ? '🙈 ': '🙉' " />
      </v-eye-switch>   
    </v-eye>   
  </v-eye>
</template>

<script>
export default {
  data: () => ({ isPasswordVisible: false })
  computed: {
    inputType() {
      return this.isPasswordVisible ? 'text' : 'password'
    }
  }
}
</script>

Using a your own custom component

Picking up on the previous example, just use the headless version via as="template prop.

<!-- your-password-input.vue -->
<template>
  <div class="your-app-input">
    <input :type="inputType">
    <v-eye v-model="isPasswordVisible" as-template #default="{ toggle }">
      <your-app-button
        :icon="isPasswordVisible ? '🙈 ': '🙉' " 
        @click="toggle"
      />
    </v-eye>   
  </v-eye>
</template>

Group Usage

Till now, you might be wondering that every example can be easily achievable without any library. Why the heck would you want another package?

The usefulness of this package really shows off when you want each v-eye to be aware its siblings state. For example an accordion, where only one panel can be open at the time: clicking one panel should close the current open sibling. That's when VEyeManager comes handy.

<!-- your disclosure.vue -->
<template>
  <v-eye-manager v-model="active" :multiple="false" :mandatory="true">
    <v-eye :uid="1">
      <v-eye-switch>Summary toggler</v-eye-switch>
      <v-eye-content>Details</v-eye-content>
    </v-eye>
    <v-eye :uid="2">
      <v-eye-switch>Summary toggler</v-eye-switch>
      <v-eye-content>Details</v-eye-content>
    </v-eye>
  </v-eye-manager>
</template>

<script>
import { VEyeManager, VEye, VEyeSwitch, VEyeContent } from 'v-eye'

export default {
  name: 'Disclosure',
  components: { VEyeManager, VEye, VEyeSwitch, VEyeContent },
  data: () => ({
    active: 1
  })
}

1. You might have noticed the multiple prop is set to false, meaning only one eye can be active at a time.
2. The mandatory prop, by default is set to false, but setting it to true states that at least one v-eye must be active all the time.
3. A uid prop was added to each v-eye, so they can be easy to identify at the model property.

Advanced usage

TODO: explain slots, props and all possibilities.

Props

This is a 0.X.Y version this means that the api is subject to changes. Props marked with BETA on the description are most likely candidates to those changes.

VEye

name	default value	description
as	template	Template means that only the a default scope slot will be rendered (headless) not actual html element. So you need to provide it yourself
active	false
uid	null	unique identifier for each item. Omitting will assign a vue generated _uid

VEyeManager

name	default value	description
as	template	Template means that only the a default scope slot will be rendered (headless) not actual html element. So you need to provide it yourself
active	`{String	Array}/null`
defaultActive	`{String	Array}/null`
mandatory	{Boolean} / false	At least one eye must be active all the time. Good for accordions, tabs.
multiple	{Boolean} / false	Allows multiple eyes to be active at the same time. Turns v-model into an array of uid
watchPropsWithModelSideEffects	{Boolean} / false	BETA — if v-model data should react immediately to prop some prop changes. Ex, a multiple instance with 2 items selected. If multiple prop changes to false, the model is updated to keep only one value.

slot-scope

All components expose two props vis default slot-scope:

1. isActive matches current instance active state.
2. toggle the method to toggle that state.

Project setup

yarn install

Compiles and hot-reloads for development

yarn serve

Compiles and minifies for production

yarn build

Run your unit tests

yarn test:unit

Lints and fixes files

yarn lint

Customize configuration

See Configuration Reference.