README.md

@@ -1,11 +1,12 @@
 ## Why another modal/dialog plugin
 
-- ✅ Accessibility first — Focus trap + keyboard navigation + aria-attributes
+- ✅ Universal: works in `vue@2` and `vue@3` 🚧
+- ✅ Renderless/headless: no assumptions about styles or markup. You have full control.
+- ✅ Accessibility first — Focus trap<sup>[1]</sup> + keyboard navigation + aria-attributes
 - ✅ Fully controlled component
 - ✅ Pure vue, no wrapping.
 - ✅ Simplicity + size
-- 🕸 Nested dialogs ([questionable pattern](https://github.com/edenspiekermann/a11y-dialog#nested-dialogs), not recommended, but possible because [it happens](https://cl.ly/be43f69393f7))
-- 🚧 _renderless version_
+- 🕸 Nested dialogs ([questionable pattern](https://github.com/edenspiekermann/a11y-dialog#nested-dialogs), not recommended, but possible because [it happens](https://cl.ly/be43f69393f7)) and it's actually in WAI-ARIA [examples](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html) so...
 
 Detailed documentation and additional info is available [at documentation site](https://renatodeleao.github.io/a11y-vue-dialog/)
 
@@ -16,136 +17,86 @@ npm i a11y-vue-dialog
 
 # or
 
-yarn add a11y-vue-dialog
-```
-
-```js
-// portal vue is binstalled as dependency, and it's required
-import PortalVue from "portal-vue";
-Vue.use(PortalVue);
-
-// add the component
-import A11yVueDialog from "a11y-vue-dialog";
-// if you want to register globally
-Vue.use(A11yVueDialog);
+yarn add a11y-dialog 
 ```
 
 ## Usage
 
-```html
-<a11y-vue-dialog :open="true">
-  <p>This slot content will be rendered wherever the <portal-target name="a11y-vue-dialogs">
-    is located. (we adivse at the bottom of your root component)</p>
-</a11y-vue-dialog>
-```
-
-```html
-<portal-target name="a11y-vue-dialogs" multiple />
-```
-
-## Renderless version
-A renderless version provides all the functionality required to build a proper `Dialog`, but gives zero f*cks about your markup and styles. The default `scopedSlot` props help you bind the accessibility attributes and event listeners to your markup elements, but semantics and styling layer it's now the consumer full responsibility.
-
-> Each `ref` suffixed slotProp is an object that contains a "props" and "listeners" keys to be attached to elements via `v-bind` and `v-on` respectively
-
-| slotProp    | type     | desc
-| ------------| -------- | ---- |
-| open        | Boolean  | prop forwarding for portal v-if   
-| close       | Function | method forwarding for closing the dialog   
-| backdropRef | Object   | for the backdrop element
-| dialogRef   | Object   | for the main dialog element
-| closeRef    | Object   | for attaching close buttons/actions
-| titleRef    | Object   | For attaching dialog title, accessibility 
-| focusRef    | Object   | For cherry-picking the first focusable element on open
+A renderless/headless component provides all the functionality required to build a proper `Dialog`, but gives zero f*cks about your styles. As such you have full control over it and have to DYI. Here's a basic example on how to do it:
 
-### Example
-```html
-<!-- compose into you own markup, MyDialog.vue -->
+```vue
+<!-- AppBaseDialog.vue -->
 <template>
-  <a11y-vue-dialog-renderless 
-    v-bind="$props"
-    @close="$emit('close')"
-    #default="{ open, closeFn, backdropRef, dialogRef, titleRef, closeRef, focusRef }"
-  >
-    <portal to="a11y-vue-dialogs" v-if="open">
-      <div class="youclasses" 
-        v-bind="backdropRef.props" 
-        v-on="backdropRef.listeners"
-      >
-        <div 
-          class="youclasses__element" 
-          v-bind="dialogRef.props" 
-          v-on="dialogRef.listeners"
-        >
-          <h1 v-bind="titleRef.props">Title</h1> 
-          <button 
-            v-bind="closeRef.props" 
-            v-on="closeRef.listeners"
-          >
-            x
-          </button>
-          <section>
-            <!-- autofocus would also work on this case, but not every focusable element supports it -->
-            <input 
-              type="text" 
-              placeholder="I will get focused first because i'm the focus ref" 
-              v-bind="focusRef.props"
-            />
-            <slot />
-          </section>
-          <footer>
-            <button @click="closeFn">Cancel</button>
-            <button @click="emit('confirm')">Confirm</button>
-          </footer>
-        </div>
+  <a11y-dialog 
+    v-bind="$attrs" 
+    v-on="$listeners"
+    v-slot:default="{ rootRef, dialogRef, titleRef, closeRef }"
+  > 
+    <div v-bind="rootRef.prop">
+      <!-- Bindings do the accessibility attributes for you -->
+      <div v-bind="dialogRef.props" v-on="dialogRef.listeners">
+        <h1 v-bind="titleRef.props">{{ title }}</h1>
+        <button v-bind="closeRef.props" v-on="closeRef.listeners">
       </div>
-    </portal>
-  </a11y-vue-dialog-renderless>
+    </div>
+    ...
+    <slot />
+  </a11y-dialog>
 </template>
 
 <script>
-import { A11yVueDialogRenderless } from "a11y-vue-dialog";
-import { Portal } from "portal-vue";
+import { A11yDialog } from 'a11y-dialog'
 
 export default {
-  name: 'MyDialog',
-  components: {
-    A11yVueDialogRenderless,
-    Portal
-  },
-  extends: { A11yVueDialogRenderless },
-  props: ['open', 'role'],
+  name: 'AppBaseDialog',
+  components: { A11yDialog },
+  props: {
+    title: {
+      type: String,
+      required: true
+    }
+  }
 }
 </script>
 ```
-
-### Then re-use and conquer
-
-```html
-<!-- page.vue -->
+```vue
+<!-- At any View.vue, after import AppBaseDialog -->
 <template>
   <div id="page">
-
-    <button @click="openMyModal = true">
-    <my-dialog
-      open="openMyModal" 
+    <button @click="isDialogOpen = true">
+    <app-base-dialog
+      title="Hello world"
+      :open="isDialogOpen" 
       @close="openMyModal = false" 
       @confirm="handSubmit"
-    />
+    >
       My markup, my rules.
-    </my-dialog>
+    </app-base-dialog>
   </div>
 </template>
 ```
 
-- Here's a [codesandbox to play with](https://codesandbox.io/s/renderless-a11y-vue-dialog-q5lqk?file=/src/components/DialogConfirm.vue)
-- Checkout [this example](https://github.com/edenspiekermann/a11y-dialog#expected-dom-structure) for what's the minimum expected markup for an accessible dialog
+Voilá, checkout a [working example on CodeSandbox](https://codesandbox.io/s/renderless-a11y-vue-dialog-demo-0-8-0-beta-1-3igsm9).
+
+
+## Docs
+
+Detailed documentation and additional info is available [at documentation site](https://renatodeleao.github.io/a11y-vue-dialog/)
 
 ## Play
 
 A playground is used to test the component locally. It uses [`vue/cli` instant prototyping feature](https://cli.vuejs.org/guide/prototyping.html), so the downside is that you have to install it globally. 
 
+- Clone this repo
+- `yarn install`
 - Then, just run `yarn play` 
 
+## Colophon
+Thanks to all this packages for inspiration and guidance.
+
+- `portal-vue|vue-simple-portal` from [@LinusBorg](https://github.com/LinusBorg) which makes escaping overflow traps easy peasy
+- `a11y-dialog` (vanilla) from `@KittyGiraudel` to lead the path that ended here
+- `vue-a11y-dialog` (wrapper around ^) from `@morkro` for the motivation to build a pure vue alternative to it.
+- All build tools used to make this a reality!
 ## License
-MITq
+MIT © Renato de Leão

docs/.vuepress/config.js

@@ -23,13 +23,12 @@ module.exports = {
     sidebarDepth: 2,
     sidebar: [
       '/guide/',
-      ['/guide/installation-and-usage', "Getting Started"],
-      ['/guide/advanced-usage', "Advanced Usage"],
-      ['/guide/renderless-usage', "Renderless Usage (new)"],
+      ['/guide/basic-usage', "Getting Started"],
+      ['/guide/advanced-usage', "Full Example"],
       ['/guide/props', "Props"],
-      ['/guide/slots', "Slots"],
+      ['/guide/slot-scope', "Slot scope"],
       ['/guide/events', "Events"],
-      ['/guide/portal-vue', "Why portal-vue?"],
+      ['/guide/advanced-tips', "Advanced tips"],
       ['/guide/thanks', "Thanks"],
     ]
   }

docs/guide/README.md

@@ -3,16 +3,18 @@ title: Introduction
 ---
 ## Why another modal/dialog plugin
 
-- ✅ Accessibility first — Focus trap + keyboard navigation + aria-attributes
+- ✅ Universal: works in `vue@2` and `vue@3` 🚧
+- ✅ Renderless/headless: no assumptions about styles or markup. You have full control.
+- ✅ Accessibility first — Focus trap<sup>[1]</sup> keyboard navigation + aria-attributes
 - ✅ Fully controlled component
 - ✅ Pure vue, no wrapping.
 - ✅ Simplicity + size
-- 🕸 Nested dialogs ([questionable pattern](https://github.com/edenspiekermann/a11y-dialog#nested-dialogs), not recommended, but possible because [it happens](https://cl.ly/be43f69393f7))
-- 🚧 _renderless version_
+- 🕸 Nested dialogs ([questionable pattern](https://github.com/edenspiekermann/a11y-dialog#nested-dialogs), not recommended, but possible because [it happens](https://cl.ly/be43f69393f7)) and it's actually in WAI-ARIA [examples](https://www.w3.org/TR/wai-aria-practices-1.1/examples/dialog-modal/dialog.html) so...
 
+#### Footnotes
+1. Since `v0.5.0` focus trap is powered by the awesome [`focus-trap`](https://github.com/focus-trap/focus-trap) — go and give them some ✨
 
-## Why Not ...?
 
-My inspiration for this package was accessibility-first. There are a lot of vue dialog/modals out there that treat accessibility as sideeffect not a feature. A11y-vue-dialog provides you an out-of-the-box accessible dialog, with just enought functionallity to get you running in seconds, and just enough props and events to make it adaptable to any usecase.
+## Why Not ...?
 
-There are a lot of dialog/modal plugins out there, if your looking for a fully fledged plugin, theres a list in the thanks you section that might help :)
+Because there are a lot of vue dialog/modals out there that treat accessibility as side-effect not a feature. Also most of them ship with preset markup/styles and you can't use your own components markup with them: this makes this package a little bit more verbose to setup, but way more flexible to adapt to almost any scenario.

docs/guide/advanced-tips.md

@@ -0,0 +1,106 @@
+## Teleporting 
+This component should work with any `portal|teleport` solution. We don't ship one as a dependency because it's not a requirement from a wai-aria guidelines standpoint. That being said, I could not recommend enough the usage of one, to escape common rendering gotchas with dialogs — the overflow trap.
+
+| Package | When |
+|---------|------|
+| [vue-simple-portal](https://github.com/LinusBorg/vue-simple-portal) | The lightweight (`3kb`) portal package for vue 2. If don't have any other portal solution on your app, this is the way to go |
+| [vue-portal](https://github.com/LinusBorg/portal-vue) | From the same creator, more robust than the previous and intended for more advanced usecases than simple dialogs. |
+
+if you already have any of the packages mentioned above or are using a custom solution, see the "usage with portal" chapter for instructions.
+
+### Usage with `vue-simple-portal`
+
+This demo uses [vue-simple-portal](https://github.com/LinusBorg/vue-simple-portal#transitions), but it would be more or less the same with any `portal` solution
+
+```vue
+<template>
+  <portal v-if="open">
+    <a11y-dialog>
+      <!-- your implementation like above -->
+    </a11y-dialog>
+  </portal>
+</template>
+
+<script>
+import { Portal } from '@linusborg/vue-simple-portal'
+
+export default {
+  components: { Portal, A11yDialog }
+}
+</script>
+```
+
+### Combine with `<transition>`
+
+
+>When you use a `<transition>` as the root element of the portal and then remove the portal (i.e. with v-if) or set its disabled prop to true, no leave transition will happen.
+>While this is to expected, as the same thing would happen if you removed a div that contains a `<transition>`, it often trips people up, which is why it's mentioned here.
+> — [vue-simple-portal](https://github.com/LinusBorg/vue-simple-portal#transitions)
+
+_if you really need to apply the `v-if` to portal, check the example in the link above_
+
+But based on the info above, this also works fine: 
+
+```vue
+<template>
+  <portal>
+    <!-- 
+      [1] note the v-if is applied to transition not portal.
+          could also be applied to the component itself
+    -->
+    <transition name="fade" appear v-if="open">
+      <a11y-dialog 
+        :open="open"
+        v-bind="$attrs"
+        v-on="$listeners"
+        #default="slotProps"
+      >
+        <!-- your implementation -->
+      </a11y-dialog>
+    </transition>
+  </portal>
+</template>
+```
+
+## Prevent background scrolling
+Before `v0.6.x` the plugin exposed a `preventBackgroundScrolling` boolean prop that basically toggled `overflow:hidden` on body when open/close. It sounds like a reasonable default but: 
+- it's very very opinionated. Can actually break custom layouts that don't use `body` as their default scroller element. 
+- also it's fairly known that iOS safari doesn't respond to `overflow:hidden` on body so a more powerful js solution is usually required to make it work.
+
+By these reasons i decided to deprecate this default implementation (which are just a few lines that you can add to your custom wrapper anyways), and replaced it with event emits: 
+
+``` vue
+<template>
+  <a11y-dialog 
+    :open="dialogOpen" 
+    @close="dialogOpen = false"
+    @show="preventScroll(true, $event)"
+    @hide="preventScroll(false, $event)"
+  >
+    <p>This slot content will be rendered wherever the <portal-target> with name 'a11y-dialogs'
+      is  located.</p>
+  </a11y-dialog>
+</template>
+```
+```js
+export default {
+  data(){
+    return {
+      dialogOpen: false
+    }
+  },
+  /**
+   * Similar to legacy preventBackgroundScrolling implementation
+   * @param {Boolean} prevent - add/remove style body
+   * @param {Boolean} hasSiblings - if it's not the only dialog open
+   */
+  preventScroll(prevent, hasSiblings) {
+    if (hasSiblings) return    
+
+    if (prevent) document.body.setProperty('overflow', 'hidden')
+    else document.body.removeProperty('overflow')
+  }
+}
+```
+
+So when creating your custom wrapper you can add your own `preventBackgroundScrolling` prop and apply your own custom implementation using events.