@gorse/shards-vue 1.0.8

package/src/components/dropdown/Dropdown.vue

@@ -0,0 +1,442 @@
+<template>
+    <component :is="computedTag" :id="computedID"
+        v-on-clickaway="away"
+        :class="[
+            'dropdown',
+            'd-dropdown',
+            !isNav ? 'btn-group' : '',
+            isNav ? 'nav-item' : '',
+            dropup ? 'dropup' : '',
+            visible ? 'show' : '',
+            (boundary !== 'scrollParent' || !boundary) ? 'position-static' : ''
+        ]">
+
+        <!-- Dropdown Split -->
+        <d-button v-if="split && !isNav"
+            ref="button"
+            :disabled="disabled"
+            :theme="theme"
+            :size="size"
+            :id="computedSplitID"
+            @click="click">
+            <slot name="button-content">{{ text }}</slot>
+        </d-button>
+
+        <!-- Dropdown Toggle -->
+        <component :is="computedToggleTag" ref="toggle"
+            :id="computedToggleID"
+            :class="[
+                isNav ? 'nav-link' : '',
+                !noCaret || split ? 'dropdown-toggle' : '',
+                split && !isNav ? 'dropdown-toggle-split' : '',
+                toggleClass
+            ]"
+            :theme="theme"
+            :size="size"
+            :disabled="disabled"
+            :aria-expanded="visible ? 'true' : 'false'"
+            aria-haspopup="true"
+            @click="toggle"
+            @keydown="toggle">
+            <span v-if="split" class="sr-only">{{ toggleText }}</span>
+            <slot v-else name="button-content">{{ text }}</slot>
+        </component>
+
+        <!-- Dropdown Menu -->
+        <div ref="menu"
+            role="menu"
+            :class="[
+                'dropdown-menu',
+                right ? 'dropdown-menu-right' : '',
+                visible ? 'show' : '',
+                menuClass
+            ]"
+            :id="computedMenuID"
+            :aria-labeledby="computedMenuID"
+            @mouseover="onMouseOver">
+            <slot />
+        </div>
+    </component>
+</template>
+
+<script>
+import Popper from 'popper.js'
+import { guid, closest } from '../../utils'
+import { THEMECOLORS, DROPDOWN_EVENTS, KEYCODES, LINK_EVENTS } from '../../utils/constants'
+import { CancelableEvent } from '../../utils/events'
+import { mixin as clickAwayMixin } from 'vue-clickaway';
+import rootListenerMixin from '../../mixins/root-listener.mixin'
+
+export default {
+    name: 'd-dropdown',
+    mixins: [
+        rootListenerMixin,
+        clickAwayMixin
+    ],
+    data() {
+        return {
+            visible: false,
+            isNavbar: null,
+            visibleChangePrevented: false
+        }
+    },
+    props: {
+        /**
+         * The element ID.
+         */
+        id: {
+            type: String,
+            default: null
+        },
+        /**
+         * The dropdown menu ID.
+         */
+        menuId: {
+            type: String,
+            default: null
+        },
+        /**
+         * The toggle ID.
+         */
+        toggleId: {
+            type: String,
+            default: null
+        },
+        /**
+         * The dropdown menu class(es).
+         */
+        menuClass: {
+            type: [String, Array],
+            default: null
+        },
+        /**
+         * The dropdown toggle class(es).
+         */
+        toggleClass: {
+            type: [String, Array],
+            default: null
+        },
+        /**
+         * Align the menu to the right.
+         */
+        right: {
+            type: Boolean,
+            default: false
+        },
+        /**
+         * Whether to display the caret, or not.
+         */
+        noCaret: {
+            type: Boolean,
+            default: false
+        },
+        /**
+         * Whether to split the dropdown, or not.
+         */
+        split: {
+            type: Boolean,
+            default: false
+        },
+        /**
+         * The color theme.
+         */
+        theme: {
+            type: String,
+            default: 'primary',
+            validator: v => THEMECOLORS.includes(v)
+        },
+        /**
+         * The dropdown toggle's size.
+         */
+        size: {
+            type: String,
+            default: null
+        },
+        /**
+         * The dropdown's disabled state.
+         */
+        disabled: {
+            type: Boolean,
+            default: false
+        },
+        /**
+         * The dropdown toggle's text.
+         */
+        toggleText: {
+            type: String,
+            default: 'Toggle Dropdown'
+        },
+        /**
+         * The button label's text.
+         */
+        text: {
+            type: String,
+            default: ''
+        },
+        /**
+         * The dropdown's boundary.
+         */
+        boundary: {
+            type: String,
+            default: 'scrollParent',
+            validator: v => ['scrollParent', 'window', 'viewport'].includes(v)
+        },
+        /**
+         * The offset value.
+         */
+        offset: {
+            type: [Number, String],
+            default: null
+        },
+        /**
+         * Display on top.
+         */
+        dropup: {
+            type: Boolean,
+            default: false
+        },
+        /**
+         * The Popper options.
+         */
+        popperOptions: {
+            type: Object,
+            default() {
+                return {}
+            }
+        },
+        /**
+         * Disable autoflipping.
+         */
+        noFlip: {
+            type: Boolean,
+            default: false
+        },
+        /**
+         * Whether the dropdown is displayed inside a nav, or not.
+         */
+        isNav: {
+            type: Boolean,
+            default: false
+        }
+    },
+    watch: {
+        visible(newVal, oldVal) {
+            if (this.visibleChangePrevented) {
+                this.visibleChangePrevented = false
+                return
+            }
+
+            if (newVal === oldVal) {
+                return
+            }
+
+            const eventName = newVal ? 'show' : 'hide'
+            let _visibleChangeEvent = new CancelableEvent(eventName, {
+                cancelable: true,
+                vueTarget: this,
+                target: this.$refs.menu,
+                relatedTarget: null
+            })
+
+            this.$emit(_visibleChangeEvent.type, _visibleChangeEvent)
+            this.emitOnRoot(DROPDOWN_EVENTS[_visibleChangeEvent.type.toUpperCase()])
+
+            if (_visibleChangeEvent.defaultPrevented) {
+                this.visibleChangePrevented = true
+                this.visible = oldVal
+                return
+            }
+
+            if (eventName === 'show') {
+                this.showMenu()
+                return
+            }
+
+            this.hideMenu()
+        },
+        disabled(newVal, oldVal) {
+            if (newVal !== oldVal && newVal && this.visible) {
+                this.visible = false
+            }
+        }
+    },
+    computed: {
+        computedTag() {
+            return this.isNav ? 'li' : 'div'
+        },
+        computedToggleTag() {
+            return this.isNav ? 'a' : 'd-button'
+        },
+        computedID() {
+            return this.id || `d-dropdown-${guid()}`
+        },
+        computedMenuID() {
+            return this.menuId || `d-dropdown-menu-${guid()}`
+        },
+        computedToggleID() {
+            return this.toggleId || `d-dropdown-toggle-${guid()}`
+        },
+        computedSplitID() {
+            return this.splitId || `d-dropdown-split-${guid()}`
+        },
+        toggler() {
+            return this.$refs.toggle.$el || this.$refs.toggle
+        }
+    },
+    methods: {
+        onMouseOver(event) {
+            const item = event.target
+            if (
+                item.classList.contains('dropdown-item')
+                && !item.disabled
+                && !item.classList.contains('disabled')
+                && item.focus
+            ) {
+                item.focus()
+            }
+        },
+        toggle(event) {
+            event = event || {}
+
+            // Enter, Space or Down
+            const KEY_ESD = event.keyCode === KEYCODES.ENTER
+                            || event.keyCode === KEYCODES.SPACE
+                            || event.keyCode === KEYCODES.DOWN
+
+            if (event.type !== 'click' && !(event.type === 'keydown' && KEY_ESD)) {
+                return
+            }
+
+            if (this.disabled) {
+                this.visible = false
+                return
+            }
+
+            this.$emit('toggle', event)
+
+            if (event.defaultPrevented) {
+                return
+            }
+
+            event.preventDefault()
+            event.stopPropagation()
+
+            this.visible = !this.visible
+        },
+        click(event) {
+            if (this.disabled) {
+                this.visible = false
+                return
+            }
+            this.$emit('click', event)
+        },
+        createPopper(element) {
+            this.removePopper()
+
+            // Define placement
+            let placement = 'bottom-start'
+
+            if (this.dropup && this.right) {
+                placement = 'top-end'
+            } else if (this.dropup) {
+                placement = 'top-start'
+            } else if (this.right) {
+                placement = 'bottom-end'
+            }
+
+            // Build Popper config
+            const popperConfig = {
+                placement,
+                modifiers: {
+                    offset: {
+                        offset: this.offset || 0
+                    },
+                    flip: {
+                        enabled: !this.noFlip
+                    },
+                    computeStyle: {
+                        enabled: true
+                    }
+                }
+            }
+
+            // Define Popper boundaries
+            if (this.boundary) {
+                popperConfig.modifiers.preventOverflow = {
+                    boundariesElement: this.boundary
+                }
+            }
+
+            // Create Popper instance
+            this._popperInstance = new Popper(
+                element,
+                this.$refs.menu,
+                {
+                    ...popperConfig,
+                    ...this.popperOptions
+                }
+            )
+        },
+        removePopper() {
+            if (this._popper) {
+                this._popper.destroy()
+            }
+            this._popperInstance = null
+        },
+        showMenu() {
+            if (this.disabled) {
+                return
+            }
+
+            this.emitOnRoot(DROPDOWN_EVENTS.SHOWN, this)
+
+            if (this.inNavbar === null && this.isNav) {
+                this.inNavbar = Boolean(closest('.navbar', this.$el))
+            }
+
+            if (!this.inNavbar) {
+                let _element = ((this.dropup && this.right) || this.split) ? this.$el : this.$refs.toggle
+                _element = _element.$el || _element
+                this.createPopper(_element)
+            }
+
+            this.$emit('shown')
+            this.$nextTick(this.focusFirstItem)
+        },
+        hideMenu() {
+            this.emitOnRoot(DROPDOWN_EVENTS.HIDDEN, this)
+            this.$emit('hidden')
+            this.removePopper()
+        },
+        away() {
+            this.visible = false
+        }
+    },
+    created() {
+        this._popperInstance = null
+    },
+    mounted() {
+        this.listenOnRoot(DROPDOWN_EVENTS.SHOWN, function(vm) {
+            if (vm !== this) {
+                this.visible = false
+            }
+        })
+
+        this.listenOnRoot(LINK_EVENTS.CLICKED, this.away)
+    },
+    deactivated() {
+        this.visible = false
+        this.removePopper()
+    },
+    beforeDestroy() {
+        this.visible = false
+        this.removePopper()
+    }
+}
+</script>
+
+<style scoped>
+.nav-link:hover {
+    cursor: pointer;
+}
+</style>

package/src/components/dropdown/DropdownDivider.vue

@@ -0,0 +1,22 @@
+<template>
+    <component role="separator"
+        class="dropdown-divier"
+        :is="tag">
+        <slot />
+    </component>
+</template>
+
+<script>
+export default {
+    name: 'd-dropdown-divider',
+    props: {
+        /**
+         * The component tag.
+         */
+        tag: {
+            type: String,
+            default: 'div'
+        }
+    }
+}
+</script>

package/src/components/dropdown/DropdownHeader.vue

@@ -0,0 +1,29 @@
+<template>
+    <component :is="tag"
+        class="dropdown-header"
+        :id="id">
+        <slot />
+    </component>
+</template>
+
+<script>
+export default {
+    name: 'd-dropdown-header',
+    props: {
+        /**
+         * The component tag.
+         */
+        tag: {
+            type: String,
+            default: 'h6'
+        },
+        /**
+         * The component ID.
+         */
+        id: {
+            type: String,
+            default: null
+        }
+    }
+}
+</script>

package/src/components/dropdown/DropdownItem.vue

@@ -0,0 +1,25 @@
+<template>
+    <d-link class="dropdown-item" role="menuitem" v-bind="$props">
+        <slot />
+    </d-link>
+</template>
+
+<script>
+import createLinkProps from '../link/create-link-props'
+
+/**
+ * This subcomponent is inheriting <a href="/docs/components/link">Link</a> component's props.
+ */
+export default {
+    name: 'd-dropdown-item',
+    props: {
+        ...createLinkProps()
+    }
+}
+</script>
+
+<style scoped>
+.dropdown-item:focus {
+    outline: 0;
+}
+</style>

package/src/components/dropdown/README.md

@@ -0,0 +1,177 @@
+# Dropdowns
+
+You can use dropdowns to display accessible contextual overlays for displaying lists of links and more.
+
+
+## Basic Example
+
+You can create dropdowns using the `<d-dropdown>` component.
+
+:::demo
+```html
+<d-dropdown text="Dropdown">
+    <d-dropdown-item>Action</d-dropdown-item>
+    <d-dropdown-item>Another action</d-dropdown-item>
+    <d-dropdown-item>Something else here</d-dropdown-item>
+    <d-dropdown-divider />
+    <d-dropdown-item>Separated link</d-dropdown-item>
+</d-dropdown>
+
+<!-- dropdown-1.vue -->
+```
+:::
+
+
+## Theme Color
+
+Changing the theme color can be easily achieved using the `theme` prop.
+
+:::demo
+```html
+<d-dropdown text="Dropdown" theme="success">
+    <d-dropdown-item>Action</d-dropdown-item>
+    <d-dropdown-item>Another action</d-dropdown-item>
+    <d-dropdown-item>Something else here</d-dropdown-item>
+    <d-dropdown-divider />
+    <d-dropdown-item>Separated link</d-dropdown-item>
+</d-dropdown>
+
+<!-- dropdown-2.vue -->
+```
+:::
+
+
+## Positioning
+
+By default dropdown menus are left aligned. However, you can change this by applying a right alignment using the `right` prop.
+
+:::demo
+```html
+
+<div>
+    <d-dropdown text="Left Align" class="mr-2">
+        <d-dropdown-item>Action</d-dropdown-item>
+        <d-dropdown-item>Another action</d-dropdown-item>
+        <d-dropdown-item>Something else here</d-dropdown-item>
+        <d-dropdown-divider />
+        <d-dropdown-item>Separated link</d-dropdown-item>
+    </d-dropdown>
+
+    <d-dropdown text="Right Align" right>
+        <d-dropdown-item>Action</d-dropdown-item>
+        <d-dropdown-item>Another action</d-dropdown-item>
+        <d-dropdown-item>Something else here</d-dropdown-item>
+        <d-dropdown-divider />
+        <d-dropdown-item>Separated link</d-dropdown-item>
+    </d-dropdown>
+</div>
+
+<!-- dropdown-3.vue -->
+```
+:::
+
+
+## Drop-up
+
+Turning dropdown menus into drop-up menus can be easily achieved using the `dropup` prop.
+
+:::demo
+```html
+<d-dropdown text="Dropdown" dropup>
+    <d-dropdown-item>Action</d-dropdown-item>
+    <d-dropdown-item>Another action</d-dropdown-item>
+    <d-dropdown-item>Something else here</d-dropdown-item>
+    <d-dropdown-divider />
+    <d-dropdown-item>Separated link</d-dropdown-item>
+</d-dropdown>
+
+<!-- dropdown-4.vue -->
+```
+:::
+
+
+## Split Buttons
+
+Using the `split` prop you can create split-type dropdowns. You can hook into the `click` event for the left-side button.
+
+:::demo
+```html
+<template>
+    <d-dropdown text="Dropdown" split @click="handleClick">
+        <d-dropdown-item>Action</d-dropdown-item>
+        <d-dropdown-item>Another action</d-dropdown-item>
+        <d-dropdown-item>Something else here</d-dropdown-item>
+        <d-dropdown-divider />
+        <d-dropdown-item>Separated link</d-dropdown-item>
+    </d-dropdown>
+</template>
+
+<script>
+    export default {
+        methods: {
+            handleClick() {
+                alert('Split button was clicked!')
+            }
+        }
+    }
+</script>
+
+<!-- dropdown-5.vue -->
+```
+:::
+
+
+## Sizing
+
+Using the `size` prop you can control the dropdown button's size.
+
+:::demo
+```html
+<div>
+    <d-dropdown text="Large" size="lg">
+        <d-dropdown-item>Action</d-dropdown-item>
+        <d-dropdown-item>Another action</d-dropdown-item>
+        <d-dropdown-item>Something else here</d-dropdown-item>
+        <d-dropdown-divider />
+        <d-dropdown-item>Separated link</d-dropdown-item>
+    </d-dropdown>
+
+    <d-dropdown text="Normal">
+        <d-dropdown-item>Action</d-dropdown-item>
+        <d-dropdown-item>Another action</d-dropdown-item>
+        <d-dropdown-item>Something else here</d-dropdown-item>
+        <d-dropdown-divider />
+        <d-dropdown-item>Separated link</d-dropdown-item>
+    </d-dropdown>
+
+    <d-dropdown text="Small" size="sm">
+        <d-dropdown-item>Action</d-dropdown-item>
+        <d-dropdown-item>Another action</d-dropdown-item>
+        <d-dropdown-item>Something else here</d-dropdown-item>
+        <d-dropdown-divider />
+        <d-dropdown-item>Separated link</d-dropdown-item>
+    </d-dropdown>
+</div>
+
+<!-- dropdown-6.vue -->
+```
+:::
+
+
+## Offsets
+
+If you'd like to offset your dropdown menu, you can use the `offset` propto specify the number of pixels you would like to push the menu to either left or right depending on the value you are using *(positive for pushing, negative for pulling)*.
+
+:::demo
+```html
+<d-dropdown text="Dropdown" offset="30">
+    <d-dropdown-item>Action</d-dropdown-item>
+    <d-dropdown-item>Another action</d-dropdown-item>
+    <d-dropdown-item>Something else here</d-dropdown-item>
+    <d-dropdown-divider />
+    <d-dropdown-item>Separated link</d-dropdown-item>
+</d-dropdown>
+
+<!-- dropdown-7.vue -->
+```
+:::