├── .eslintrc.cjs ├── .gitignore ├── .npmrc ├── .nvmrc ├── .prettierrc.json ├── .storybook ├── main.ts └── preview.ts ├── LICENSE ├── README.md ├── env.d.ts ├── package.json ├── src ├── FocusLock.vue ├── index.ts └── stories │ ├── GroupStory.stories.ts │ ├── GroupStory.vue │ ├── LockStory.stories.ts │ ├── LockStory.vue │ ├── NoFocusGuardsStory.stories.ts │ ├── NoFocusGuardsStory.vue │ ├── NoTailingGuardStory.stories.ts │ └── NoTailingGuardStory.vue ├── tsconfig.json ├── vite.config.ts └── yarn.lock /.eslintrc.cjs: -------------------------------------------------------------------------------- 1 | /* eslint-env node */ 2 | require('@rushstack/eslint-patch/modern-module-resolution') 3 | 4 | module.exports = { 5 | root: true, 6 | extends: [ 7 | 'plugin:vue/vue3-essential', 8 | 'eslint:recommended', 9 | '@vue/eslint-config-typescript', 10 | '@vue/eslint-config-prettier/skip-formatting', 11 | 'plugin:storybook/recommended', 12 | 'plugin:prettier-vue/recommended' 13 | ], 14 | parserOptions: { 15 | ecmaVersion: 'latest' 16 | } 17 | } 18 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | pnpm-debug.log* 8 | lerna-debug.log* 9 | 10 | node_modules 11 | .DS_Store 12 | dist 13 | dist-ssr 14 | coverage 15 | *.local 16 | 17 | /cypress/videos/ 18 | /cypress/screenshots/ 19 | 20 | # Editor directories and files 21 | .vscode/* 22 | .idea 23 | *.suo 24 | *.ntvs* 25 | *.njsproj 26 | *.sln 27 | *.sw? 28 | 29 | *.tsbuildinfo 30 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | registry=https://registry.npmjs.org -------------------------------------------------------------------------------- /.nvmrc: -------------------------------------------------------------------------------- 1 | 18 -------------------------------------------------------------------------------- /.prettierrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://json.schemastore.org/prettierrc", 3 | "semi": false, 4 | "tabWidth": 2, 5 | "singleQuote": true, 6 | "printWidth": 100, 7 | "trailingComma": "none" 8 | } -------------------------------------------------------------------------------- /.storybook/main.ts: -------------------------------------------------------------------------------- 1 | import type { StorybookConfig } from '@storybook/vue3-vite' 2 | 3 | const config: StorybookConfig = { 4 | stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], 5 | addons: [ 6 | '@storybook/addon-links', 7 | '@storybook/addon-essentials', 8 | '@storybook/addon-interactions' 9 | ], 10 | framework: { 11 | name: '@storybook/vue3-vite', 12 | options: {} 13 | }, 14 | docs: { 15 | autodocs: 'tag' 16 | } 17 | } 18 | export default config 19 | -------------------------------------------------------------------------------- /.storybook/preview.ts: -------------------------------------------------------------------------------- 1 | import type { Preview } from '@storybook/vue3' 2 | 3 | const preview: Preview = { 4 | parameters: { 5 | actions: { argTypesRegex: '^on[A-Z].*' }, 6 | controls: { 7 | matchers: { 8 | color: /(background|color)$/i, 9 | date: /Date$/i 10 | } 11 | } 12 | } 13 | } 14 | 15 | export default preview 16 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Anton 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # vue-focus-lock 2 | It is a trap! We got your focus and will not let him out! 3 | 4 | [](https://nodei.co/npm/vue-focus-lock/) 5 | 6 | ---- 7 | 8 | - __Vue3 users__ - use v3+ `vue-focus-lock@3` 9 | - __Vue2 users__ - use v2+ `vue-focus-lock@2` 10 | 11 | ---- 12 | 13 | This is a small, but very useful for: 14 | - Modal dialogs. You can not leave it with "Tab", ie tab-out. 15 | - Focused tasks. It will always brings you back. 16 | 17 | You have to use it in _every_ modal dialog, or you `a11y` will be shitty. 18 | 19 | # How to use 20 | Just wrap something with focus lock, and focus will be `moved inside` on mount. 21 | ```html 22 | 23 | You can not leave this form 24 | 25 | 26 | ``` 27 | Demo - https://codesandbox.io/s/l5qlpxqvnq 28 | 29 | # WHY? 30 | From [MDN Article about accessible dialogs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_dialog_role): 31 | - The dialog must be properly labeled 32 | - Keyboard __focus must be managed__ correctly 33 | 34 | This one is about managing the focus. 35 | 36 | I'v got a good [article about focus management, dialogs and WAI-ARIA](https://medium.com/@antonkorzunov/its-a-focus-trap-699a04d66fb5). 37 | 38 | 39 | # Behavior 40 | 0. It will always keep focus inside Lock. 41 | 1. It will cycle forward then you press Tab. 42 | 2. It will cycle in reverse direction on Shift+Tab. 43 | 3. It will do it using _browser_ tools, not emulation. 44 | 4. It will handle positive tabIndex inside form. 45 | 5. It will prevent any jump outside, returning focus to the last element. 46 | 47 | !! this realisation will not return focus to the original place on Unlock !! 48 | 49 | You can use nested Locks or have more than one Lock on the page. 50 | Only `last`, or `deepest` one will work. No fighting. 51 | 52 | # API 53 | FocusLock has few props to tune behavior, all props are optional: 54 | - `disabled`, to disable(enable) behavior without altering the tree. 55 | - `group=''`, named focus group for focus scattering aka [combined lock targets](https://github.com/theKashey/vue-focus-lock/issues/2). 56 | - `noFocusGuards=false`, disable focus guards - virtual inputs which secure tab index. 57 | 58 | #### Removing Tailing Guard 59 | FocusLock is adding `Focus Guards` before and after lock to remove some side effects, like page scrolling. 60 | If you want to allow user _tab_ into address bar (only if your modal is the last tabbable element on the body), 61 | you might remove the Tailing Guard. To do this, set `noFocusGuards` prop to `tail`. 62 | ```html 63 | 64 | ... 65 | 66 | ``` 67 | 68 | # How it works 69 | Everything thing is simple - vue-focus-lock just dont left focus left boundaries of component, and 70 | do something only if escape attempt was succeeded. 71 | 72 | It is not altering tabbing behavior at all. We are good citizens. 73 | 74 | # Licence 75 | MIT 76 | 77 | 78 | -------------------------------------------------------------------------------- /env.d.ts: -------------------------------------------------------------------------------- 1 | /// 2 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "vue-focus-lock", 3 | "version": "3.0.1", 4 | "description": "It is a trap! (for a focus)", 5 | "type": "module", 6 | "main": "./dist/vue-focus-lock.umd.cjs", 7 | "module": "./dist/vue-focus-lock.js", 8 | "types": "./dist/vue-focus-lock.d.ts", 9 | "exports": { 10 | ".": { 11 | "import": "./dist/vue-focus-lock.js", 12 | "require": "./dist/vue-focus-lock.umd.cjs", 13 | "types": "./dist/vue-focus-lock.d.ts" 14 | } 15 | }, 16 | "files": [ 17 | "dist" 18 | ], 19 | "scripts": { 20 | "build": "run-p type-check \"build-only {@}\" --", 21 | "build-only": "vite build", 22 | "prepublish": "npm run build", 23 | "type-check": "vue-tsc --build --force", 24 | "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --ignore-path .gitignore", 25 | "lint:fix": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore", 26 | "storybook": "storybook dev -p 6006", 27 | "build-storybook": "storybook build" 28 | }, 29 | "repository": { 30 | "type": "git", 31 | "url": "git+https://github.com/theKashey/vue-focus-lock.git" 32 | }, 33 | "keywords": [ 34 | "vue", 35 | "focus", 36 | "lock", 37 | "trap", 38 | "tabbable" 39 | ], 40 | "author": "theKashey ", 41 | "license": "ISC", 42 | "bugs": { 43 | "url": "https://github.com/theKashey/vue-focus-lock/issues" 44 | }, 45 | "dependencies": { 46 | "focus-lock": "^1.3.6" 47 | }, 48 | "devDependencies": { 49 | "@rushstack/eslint-patch": "^1.3.3", 50 | "@storybook/addon-essentials": "^7.6.16", 51 | "@storybook/addon-interactions": "^7.6.16", 52 | "@storybook/addon-links": "^7.6.16", 53 | "@storybook/blocks": "^7.6.16", 54 | "@storybook/test": "^7.6.16", 55 | "@storybook/vue3": "^7.6.16", 56 | "@storybook/vue3-vite": "^7.6.16", 57 | "@tsconfig/node20": "^20.1.2", 58 | "@types/node": "^20.11.19", 59 | "@vitejs/plugin-vue": "^5.0.3", 60 | "@vue/eslint-config-prettier": "^8.0.0", 61 | "@vue/eslint-config-typescript": "^12.0.0", 62 | "@vue/tsconfig": "^0.5.1", 63 | "eslint": "^8.49.0", 64 | "eslint-plugin-prettier-vue": "^5.0.0", 65 | "eslint-plugin-storybook": "^0.8.0", 66 | "eslint-plugin-vue": "^9.17.0", 67 | "npm-run-all2": "^6.1.1", 68 | "prettier": "^3.0.3", 69 | "react": "^18.2.0", 70 | "react-dom": "^18.2.0", 71 | "storybook": "^7.6.16", 72 | "vite": "^5.0.11", 73 | "vite-plugin-dts": "^3.7.2", 74 | "vue": "^3.0.0", 75 | "vue-tsc": "^1.8.27" 76 | }, 77 | "peerDependencies": { 78 | "vue": "^3.0.0" 79 | }, 80 | "resolutions": { 81 | "jackspeak": "2.1.1" 82 | } 83 | } 84 | -------------------------------------------------------------------------------- /src/FocusLock.vue: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 207 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import FocusLock from './FocusLock.vue' 2 | 3 | export default FocusLock 4 | -------------------------------------------------------------------------------- /src/stories/GroupStory.stories.ts: -------------------------------------------------------------------------------- 1 | import GroupStory from './GroupStory.vue' 2 | 3 | import type { Meta, StoryObj } from '@storybook/vue3' 4 | 5 | const meta = { 6 | title: 'GroupStory', 7 | component: GroupStory 8 | } satisfies Meta 9 | 10 | export default meta 11 | type Story = StoryObj 12 | 13 | export const FocusGroup: Story = {} 14 | -------------------------------------------------------------------------------- /src/stories/GroupStory.vue: -------------------------------------------------------------------------------- 1 | 2 | 3 | Button 4 | 5 | !ACTIVATE THE TRAP! 6 | 7 | 8 | 9 | 10 | BUTTON 11 | link somewhere 12 | DEACTIVATE 13 | 14 | 15 | 16 | some text outside 17 | 18 | 19 | Button 20 | 21 | 22 | some text outside 23 | 24 | 25 | 26 | BUTTON 27 | link somewhere 28 | DEACTIVATE 29 | 30 | 31 | 32 | 33 | 34 | 53 | 54 | 55 | -------------------------------------------------------------------------------- /src/stories/LockStory.stories.ts: -------------------------------------------------------------------------------- 1 | import LockStory from './LockStory.vue' 2 | 3 | import type { Meta, StoryObj } from '@storybook/vue3' 4 | 5 | const meta = { 6 | title: 'LockStory', 7 | component: LockStory 8 | } satisfies Meta 9 | 10 | export default meta 11 | type Story = StoryObj 12 | 13 | export const Simple: Story = {} 14 | -------------------------------------------------------------------------------- /src/stories/LockStory.vue: -------------------------------------------------------------------------------- 1 | 2 | 3 | {{ msg }} 4 | Essential Links 5 | ENABLE TRAP 6 | 7 | you will be trapped here 8 | 9 | 10 | 11 | Core Docs 12 | 13 | 14 | Forum 15 | 16 | 17 | Gitter Chat 18 | 19 | 20 | Twitter 21 | 22 | 23 | 24 | Docs for This Template 27 | 28 | 29 | 30 | DISABLE TRAP 31 | 32 | 33 | 34 | Ecosystem 35 | 36 | 37 | vue-router 38 | 39 | 40 | vuex 41 | 42 | 43 | vue-loader 44 | 45 | 46 | awesome-vue 47 | 48 | 49 | 50 | 51 | 52 | 74 | 75 | 76 | 96 | -------------------------------------------------------------------------------- /src/stories/NoFocusGuardsStory.stories.ts: -------------------------------------------------------------------------------- 1 | import NoFocusGuardsStory from './NoFocusGuardsStory.vue' 2 | 3 | import type { Meta, StoryObj } from '@storybook/vue3' 4 | 5 | const meta = { 6 | title: 'NoFocusGuardsStory', 7 | component: NoFocusGuardsStory 8 | } satisfies Meta 9 | 10 | export default meta 11 | type Story = StoryObj 12 | 13 | export const NoFocusGuards: Story = {} 14 | -------------------------------------------------------------------------------- /src/stories/NoFocusGuardsStory.vue: -------------------------------------------------------------------------------- 1 | 2 | 3 | Button-1 4 | 5 | !ACTIVATE THE TRAP! 6 | 7 | 8 | 9 | 10 | BUTTON-2 11 | link somewhere 12 | DEACTIVATE 13 | 14 | 15 | 16 | 17 | Button-3 18 | 19 | 20 | 21 | 22 | 41 | 42 | 43 | -------------------------------------------------------------------------------- /src/stories/NoTailingGuardStory.stories.ts: -------------------------------------------------------------------------------- 1 | import NoTailingGuardStory from './NoTailingGuardStory.vue' 2 | 3 | import type { Meta, StoryObj } from '@storybook/vue3' 4 | 5 | const meta = { 6 | title: 'NoTailingGuardStory', 7 | component: NoTailingGuardStory 8 | } satisfies Meta 9 | 10 | export default meta 11 | type Story = StoryObj 12 | 13 | export const NoTailingGuards: Story = {} 14 | -------------------------------------------------------------------------------- /src/stories/NoTailingGuardStory.vue: -------------------------------------------------------------------------------- 1 | 2 | 3 | Button-1 4 | 5 | !ACTIVATE THE TRAP! 6 | 7 | 8 | 9 | Probably would not work properly in storybook iframe. 10 | 14 | Open iframe in new tab 15 | 16 | 17 | 18 | 19 | 20 | BUTTON-2 21 | link somewhere 22 | DEACTIVATE 23 | 24 | 25 | 26 | 27 | 28 | 47 | 48 | 49 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "@vue/tsconfig/tsconfig.dom.json", 3 | "compilerOptions": { 4 | "module": "ESNext", 5 | "moduleResolution": "node", 6 | "strict": true, 7 | "allowJs": true, 8 | "types": ["vite/client"], 9 | "paths": { 10 | "@/*": ["./src/*"] 11 | } 12 | }, 13 | "exclude": ["./dist", "./node_modules", "./eslintrc.cjs"] 14 | } 15 | -------------------------------------------------------------------------------- /vite.config.ts: -------------------------------------------------------------------------------- 1 | import { fileURLToPath, URL } from 'node:url' 2 | 3 | import vue from '@vitejs/plugin-vue' 4 | import * as path from 'path' 5 | import { defineConfig } from 'vite' 6 | import dts from 'vite-plugin-dts' 7 | 8 | // https://vitejs.dev/config/ 9 | export default defineConfig({ 10 | plugins: [vue(), dts({ insertTypesEntry: true, rollupTypes: true })], 11 | build: { 12 | lib: { 13 | entry: path.resolve(__dirname, 'src/index.ts'), 14 | name: 'VueFocusLock', 15 | fileName: 'vue-focus-lock' 16 | }, 17 | rollupOptions: { 18 | external: ['vue'], 19 | output: { 20 | globals: { 21 | vue: 'Vue' 22 | } 23 | } 24 | } 25 | } 26 | }) 27 | --------------------------------------------------------------------------------
9 | Probably would not work properly in storybook iframe. 10 | 14 | Open iframe in new tab 15 | 16 |