diff --git a/README.md b/README.md index 6c5574e..371c354 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # vue-modal ![](https://img.badgesize.io/kouts/vue-modal/next/dist/vue-modal.umd.js.svg) ![](https://img.badgesize.io/kouts/vue-modal/next/dist/vue-modal.umd.js.svg?compression=gzip) ![](coverage/badge.svg) + A customizable, stackable, and lightweight modal component for Vue.js 3. --- @@ -12,30 +13,28 @@ If you're looking for a Vue.js 2 compatible version of vue-modal, [please check > to the accessibility best practices set in the [WAI-ARIA Dialog (Modal)](https://www.w3.org/TR/wai-aria-practices/#dialog_modal) section > of W3C. - ## Features at a glance - Lightweight, minified gzipped version is < **4kb** -- Opens and closes with a data variable using ```v-model``` +- Opens and closes with a data variable using `v-model` **or** with a `name` prop and `show`/`hide` functions - Includes sensible default styling but it's also highly customizable via user CSS classes and styles - Override modal title and content via slots - Modal intro and outro effects using CSS animation classes - Exposes Component events - before-open, opening, after-open, before-close, closing, after-close, update:modelValue (close) - Scrollable when it's contents exceed screen height -- Closeable by clicking on the upper right "x", the overlay or the ```esc``` key +- Closeable by clicking on the upper right "x", the overlay or the `esc` key - **Stackable** - Multiple modal windows on top of each other - Ability to set initial focus on an element when the modal window opens, just set the **autofocus** attribute on an element inside the modal - **Focus management** traps keyboard focus - tabbed navigation inside the modal window - Ability to have unclosable modal windows - Render on demand or stay always in DOM with "live" mode -- Modals appended to `````` by default, ability to append to a custom element +- Modals appended to `` by default, ability to append to a custom element ## Browsers support | [Edge](http://godban.github.io/browsers-support-badges/)
Edge | [Firefox](http://godban.github.io/browsers-support-badges/)
Firefox | [Chrome](http://godban.github.io/browsers-support-badges/)
Chrome | [Safari](http://godban.github.io/browsers-support-badges/)
Safari | [Opera](http://godban.github.io/browsers-support-badges/)
Opera | -| --------- | --------- | --------- | --------- | --------- | -| Edge| last 2 versions| last 2 versions| last 2 versions| last 2 versions - +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Edge | last 2 versions | last 2 versions | last 2 versions | last 2 versions | Click here for documentation and examples https://next--vue-modal-demo.netlify.app/ diff --git a/docs/.vuepress/client.js b/docs/.vuepress/client.js index 36bcd52..4ccdead 100644 --- a/docs/.vuepress/client.js +++ b/docs/.vuepress/client.js @@ -1,13 +1,16 @@ import Example1 from './components/Example1.vue' +import Example2 from './components/Example2.vue' import Intro from './components/Intro.vue' -import Modal from '@/Modal.vue' +import { Modal, modalPlugin } from '@/index' import { defineClientConfig } from '@vuepress/client' import './styles/styles.scss' export default defineClientConfig({ enhance({ app, router, siteData }) { + app.use(modalPlugin) app.component('Modal', Modal) app.component('Example1', Example1) + app.component('Example2', Example2) app.component('Intro', Intro) }, setup() { diff --git a/docs/.vuepress/components/Example2.vue b/docs/.vuepress/components/Example2.vue new file mode 100644 index 0000000..3291e5c --- /dev/null +++ b/docs/.vuepress/components/Example2.vue @@ -0,0 +1,15 @@ + diff --git a/docs/.vuepress/styles/styles.scss b/docs/.vuepress/styles/styles.scss index d1834cb..d5fcff1 100644 --- a/docs/.vuepress/styles/styles.scss +++ b/docs/.vuepress/styles/styles.scss @@ -175,3 +175,9 @@ h1#vue-modal + p + p { code { font-family: inherit; } + +/* Fix h2 spacing */ +.theme-container .theme-default-content:not(.custom) h2 { + margin-bottom: 1.3rem; + padding-bottom: 1.3rem; +} diff --git a/docs/index.md b/docs/index.md index be2a990..b8fe3bf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,26 +12,27 @@ A customizable, stackable, and lightweight modal component for Vue.js 3. -## Features at a glance -

 

+## Features at a glance + +

 

- Lightweight, minified gzipped version is < **4kb** -- Opens and closes with a data variable using ```v-model``` +- Opens and closes with a data variable using `v-model` **or** with a `name` prop and `show`/`hide` functions - Includes sensible default styling but it's also highly customizable via user CSS classes and styles - Override modal title and content via slots - Modal intro and outro effects using CSS animation classes - Exposes Component events - before-open, opening, after-open, before-close, closing, after-close, update:modelValue (close) - Scrollable when it's contents exceed screen height -- Closeable by clicking on the upper right "x", the overlay or the ```esc``` key +- Closeable by clicking on the upper right "x", the overlay or the `esc` key - **Stackable** - Multiple modal windows on top of each other - Ability to set initial focus on an element when the modal window opens, just set the **autofocus** attribute on an element inside the modal - **Focus management** traps keyboard focus - tabbed navigation inside the modal window - Ability to have unclosable modal windows - Render on demand or stay always in DOM with "live" mode -- Modals appended to `````` by default, ability to append to a custom element +- Modals appended to `` by default, ability to append to a custom element ## Browsers support | [Edge](http://godban.github.io/browsers-support-badges/)
Edge | [Firefox](http://godban.github.io/browsers-support-badges/)
Firefox | [Chrome](http://godban.github.io/browsers-support-badges/)
Chrome | [Safari](http://godban.github.io/browsers-support-badges/)
Safari | [Opera](http://godban.github.io/browsers-support-badges/)
Opera | -| --------- | --------- | --------- | --------- | --------- | -| Edge| last 2 versions| last 2 versions| last 2 versions| last 2 versions +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Edge | last 2 versions | last 2 versions | last 2 versions | last 2 versions | diff --git a/docs/installation/index.md b/docs/installation/index.md index b53163b..8e714de 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,24 +1,34 @@ ## Basic -Download the repo, extract ```vue-modal.umd.js``` and ```vue-modal.css``` out of the ```dist``` folder +Download the repo, extract `vue-modal.umd.js` and `vue-modal.css` out of the `dist` folder and insert them in your page. -``` html +```html ``` -``` html - +```html + ``` ## Module System Install it via npm + ``` npm i @kouts/vue-modal@next --save ``` -Use the ```import``` statement to include it into your js -``` js -import VueModal from '@kouts/vue-modal' + +Use the `import` statement to include it into your `main.js` file. +You may also choose to register `vue-modal` globally, so that you don't need to import it in every component. + +```js +import { createApp } from 'vue' +import { Modal } from '@kouts/vue-modal' import '@kouts/vue-modal/dist/vue-modal.css' -``` \ No newline at end of file + +const app = Vue.createApp({...}) + +// This is optional +app.component('Modal', Modal) +``` diff --git a/docs/options/index.md b/docs/options/index.md index 386a154..f242d3a 100644 --- a/docs/options/index.md +++ b/docs/options/index.md @@ -1,6 +1,19 @@ ## v-model -Pass a Boolean value to the `v-model` directive to open and close the modal window. +Pass a `Boolean` value to the `v-model` directive to show and hide the modal window. + +## Plugin API + +The Plugin API can be called within any component through: + +- `useModal` in Composition API +- `this.$modal` in Options API + +and exposes 3 functions: + +- **`show(name)`** - Shows the modal with the given name +- **`hide(name)`** - Hides the modal with the given name +- **`hideAll()`** - Hides all modals ## Props @@ -14,6 +27,12 @@ Pass a Boolean value to the `v-model` directive to open and close the modal wind + + name + The name of the modal to use with the show / hide functions. + String + Empty + title The title of the modal element @@ -93,7 +112,7 @@ Pass a Boolean value to the `v-model` directive to open and close the modal wind true - basedOn + modelValue Opens and closes the modal window, this is used by v-model internally. Boolean false diff --git a/docs/package.json b/docs/package.json deleted file mode 100644 index 1bad66b..0000000 --- a/docs/package.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "sideEffects": true -} \ No newline at end of file diff --git a/docs/usage/index.md b/docs/usage/index.md index 8099ad8..092fb7c 100644 --- a/docs/usage/index.md +++ b/docs/usage/index.md @@ -1,53 +1,105 @@ -## Register -Register ```vue-modal``` in your application globbaly -``` js -const app = Vue.createApp({...}) +# Usage + +There are two ways in which you can control `vue-modal`'s visibility: + +1. With `v-model` directive +2. Using a `name` prop and `show`/`hide` functions + +## Usage with `v-model` directive + +To control the visibility of the modal with `v-model`, you need to pass a `Boolean` value to the `v-model` directive. + +```vue + + + ``` -## Use -### Template -with `v-model` -``` vue - - - -

Modal content goes here...

- + +**Example:** + + + +## Usage with `name` prop and `show`/`hide` functions + +`vue-modal` comes with a `modalPlugin` that you need to import and register, +in order to be able to use `vue-modal` with a `name` prop. + +```js +import { createApp } from 'vue' +import { modalPlugin } from '@kouts/vue-modal' + +const app = Vue.createApp({...}) + +app.use(modalPlugin) ``` -or -with `modelValue` value and `update:modelValue` event -``` vue - -

Modal content goes here...

- + +To control the visibility of the modal with the mane `prop` you use the and `show`/`hide` functions. + +**Composition API** + +```vue + + + ``` +**Options API** -### Script -``` js -import VueModal from '@kouts/vue-modal' +```vue + + + ``` -### Result - \ No newline at end of file + +**Example:** + + diff --git a/package.json b/package.json index 3570f72..c48e369 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,6 @@ "main": "./dist/vue-modal.umd.js", "module": "./dist/vue-modal.es.js", "unpkg": "dist/vue-modal.umd.js", - "sideEffects": false, "scripts": { "dev": "vite", "serve": "vite preview",