semantic-forms 5.1.12 → 5.2.1

package/docs/statics/pages/usage.html

@@ -132,6 +132,54 @@
         </dl>
       </form>
 
+      <h5>Add custom keyboard shortcuts</h5>
+
+      <p>Add keyboard shortcuts on specific inputs to focus them by adding a <code>data-focus-key</code> attribute and optional <code>data-focus-modifier</code> attribute.</p>
+
+      <pre><code class='language-html' lang='html'><escape>
+<form class="semanticForms" method="post">
+  <dl>
+    <dt><label for="focus-1">Focus me!</label></dt>
+    <dd><input id="focus-1" name="focus-1" type="text" data-focus-key="Y"></dd>
+
+    <!-- change the modifier -->
+    <dt><label for="focus-2">Focus me!</label></dt>
+    <dd><input id="focus-2" name="focus-2" type="text" data-focus-key="Y" data-focus-modifier="alt"></dd>
+
+    <!-- specify modifier by OS -->
+    <dt><label for="focus-2">Focus me!</label></dt>
+    <dd><input id="focus-2" name="focus-2" type="text" data-focus-key="Z" data-focus-modifier-win="alt" data-focus-modifier-linux="meta" data-focus-modifier-mac="cmd"></dd>
+  </dl>
+</form>
+</escape></code></pre>
+      
+      <form class="semanticForms" method="post">
+        <dl>
+          <dt><label for="focus-1">Focus me!</label></dt>
+          <dd><input id="focus-1" name="focus-1" type="text" data-focus-key="Y"></dd>
+      
+          <!-- change the modifier -->
+          <dt><label for="focus-2">Focus me!</label></dt>
+          <dd><input id="focus-2" name="focus-2" type="text" data-focus-key="Y" data-focus-modifier="alt"></dd>
+      
+          <!-- specify modifier by OS -->
+          <dt><label for="focus-3">Focus me!</label></dt>
+          <dd><input id="focus-3" name="focus-3" type="text" data-focus-key="Z" data-focus-modifier-win="alt" data-focus-modifier-linux="meta" data-focus-modifier-max="cmd"></dd>
+        </dl>
+      </form>
+
+      <ul>
+        <li><p>The focus key should be a single character, and is not case-sensitive. If multiple characters are detected, only the first one will be used. Special characters (!, @, #, etc.) will require <kbd>Shift</kbd> to be pressed with the keyboard shortcut.</p></li>
+        <li>
+          <p>The modifier key value may be "metactrl," "ctrl," "cmd," "meta," or "alt." The default value is "metactrl" and will automatically be applied if the <code>data-focus-modifier</code> attribute is not present.</p>
+          <ul>
+            <li>Some combinations are unable to be used due to conflicts with browser and OS keyboard shortcuts. See <a href="https://rooseveltframework.org/docs/semantic-forms/latest/reservedKeyboardShortcuts">reserved keyboard shortcuts</a> for a full overview.</li>
+            <li><p>OS-specific modifier keys can be set with <code>data-focus-modifier-win</code> (Windows), <code>data-focus-modifier-linux</code> (Linux) and <code>data-focus-modifier-mac</code> (Mac).</p></li>
+            <li><p>Due to a limited range of available shortcuts, the "Start" (win) key on Windows will be replaced with "Ctrl."</p></li>
+          </ul>
+        </li>
+      </ul>
+
       <h5 id="custominputfields">Customizing input fields</h5>
 
       <p>By default, input fields will display an X icon to clear the text and password fields will also display a show/hide toggle for displaying the password in plain text. You can customize this behavior as follows:</p>

package/package.json

@@ -8,7 +8,7 @@
       "url": "https://github.com/rooseveltframework/semantic-forms/graphs/contributors"
     }
   ],
-  "version": "5.1.12",
+  "version": "5.2.1",
   "files": [
     "dist",
     "semanticForms.scss",
@@ -21,8 +21,8 @@
   "readmeFilename": "README.md",
   "devDependencies": {
     "@jsdevtools/coverage-istanbul-loader": "3.0.5",
-    "@playwright/test": "1.56.0",
-    "eslint": "9.37.0",
+    "@playwright/test": "1.56.1",
+    "eslint": "9.38.0",
     "eslint-plugin-html": "8.1.3",
     "express": "5.1.0",
     "nodemon": "3.1.10",

package/semanticForms.js

@@ -11,9 +11,84 @@ const semanticForms = () => {
 
   const nodeNameLookup = ['TEXTAREA', 'SELECT']
   const inputTypeLookup = ['checkbox', 'color', 'date', 'datetime-local', 'email', 'file', 'image', 'month', 'number', 'password', 'radio', 'range', 'search', 'tel', 'text', 'time', 'url', 'week']
+  const keyboardShortcuts = []
+
+  // custom keyboard shortcut listener
+  document.addEventListener('keydown', (e) => {
+    const specialCharMap = {
+      Minus: '-',
+      Equal: '=',
+      BracketLeft: '[',
+      BracketRight: ']',
+      Backslash: '\\',
+      Semicolon: ';',
+      Quote: '\'',
+      Comma: ',',
+      Period: '.',
+      Slash: '/',
+      Backquote: '`'
+    }
+
+    const shiftSpecialCharMap = {
+      1: '!',
+      2: '@',
+      3: '#',
+      4: '$',
+      5: '%',
+      6: '^',
+      7: '&',
+      8: '*',
+      9: '(',
+      0: ')',
+      Minus: '_',
+      Equal: '+',
+      BracketLeft: '{',
+      BracketRight: '}',
+      Backslash: '|',
+      Semicolon: ':',
+      Quote: '"',
+      Comma: '<',
+      Period: '>',
+      Slash: '?',
+      Backquote: '~'
+    }
+
+    const shortcut = keyboardShortcuts.find(shortcut => {
+      let matchesKey = false
+      if (e.altKey && !e.shiftKey) {
+        // mac adjusts the key value if altKey is pressed
+        matchesKey = 'Key' + shortcut.key.toUpperCase() === e.code ||
+          'Digit' + shortcut.key.toUpperCase() === e.code ||
+          shortcut.key === e.key ||
+          specialCharMap[e.code] === shortcut.key
+      } else if (e.shiftKey) {
+        // check shift special character map
+        const code = e.code.replace(/Key|Digit/, '')
+        matchesKey = (shiftSpecialCharMap[code] || shiftSpecialCharMap[e.key]) &&
+          (shiftSpecialCharMap[code] === shortcut.key || shiftSpecialCharMap[e.key] === shortcut.key)
+      } else {
+        matchesKey = shortcut.key.toUpperCase() === e.key.toUpperCase()
+      }
+      if (!matchesKey) return false
+
+      let matchesModifier
+      if (shortcut.modifier) {
+        if (shortcut.modifier === shortcut.defaultModifier) matchesModifier = shortcut.os === 'windows' || shortcut.os === 'linux' ? e.ctrlKey : e.metaKey
+        if (shortcut.modifier === 'meta') matchesModifier = e.metaKey
+        if (shortcut.modifier === 'alt') matchesModifier = e.altKey
+        if (shortcut.modifier === 'ctrl') matchesModifier = e.ctrlKey
+      }
+      return matchesModifier
+    })
+
+    if (shortcut) {
+      e.preventDefault()
+      shortcut.input.focus()
+    }
+  })
 
   // progressively enhance form elements that have the semanticForms class
-  const forms = document.querySelectorAll('form.semanticForms:not(.semanticFormsActive)')
+  const forms = document.querySelectorAll('form.semanticForms:not(.semanticFormsActive), table.semanticForms:not(.semanticFormsActive)')
 
   for (const form of forms) {
     form.classList.add('semanticFormsActive')
@@ -45,6 +120,10 @@ const semanticForms = () => {
         input.classList.add('semanticform')
 
         // #region create labels
+
+        const newLabel = document.createElement('label')
+        newLabel.className = 'floatLabelFormAnimatedLabel'
+
         if (type === 'checkbox' || type === 'radio') {
           // recursively find <dd> element
           let dd = input.parentNode
@@ -56,9 +135,6 @@ const semanticForms = () => {
           }
 
           if (dd.firstChild.nodeName !== 'LABEL') {
-            const newLabel = document.createElement('label')
-            newLabel.className = 'floatLabelFormAnimatedLabel'
-
             if (type === 'checkbox' && input.parentNode.nodeName === 'DD') {
               newLabel.setAttribute('for', input.id)
               input.parentNode.classList.add('singleCheckbox')
@@ -99,10 +175,7 @@ const semanticForms = () => {
           div.append(label.closest('dt'), dd)
           dl.append(div)
         } else {
-          const newLabel = document.createElement('label')
           newLabel.setAttribute('for', input.id)
-          newLabel.className = 'floatLabelFormAnimatedLabel'
-
           newLabel.innerHTML = label.innerHTML
 
           if (input.hasAttribute('title') && label.getAttribute('data-show-help-icon') !== null && !label.querySelector('span.help')) {
@@ -121,6 +194,97 @@ const semanticForms = () => {
         }
         // #endregion
 
+        // #region keyboard shortcuts
+        if (input.getAttribute('data-focus-key') !== null) {
+          function handleKeyboardShortcut () {
+            const os = getOS()
+            // this is the custom keyword for meta on linux/mac, ctrl on windows
+            const defaultModifier = 'metactrl'
+
+            // get focus key value
+            let focusKey = input.getAttribute('data-focus-key')
+            if (focusKey.length > 1) {
+              console.error(`Provided focus key "${focusKey}" is more than one character. Using first character only.`)
+              focusKey = focusKey.toString()[0]
+            }
+
+            // get focus modifier value
+            let modifierSymbol
+            let modifierKey = defaultModifier
+            const modifierAttr = {
+              default: input.getAttribute('data-focus-modifier') || defaultModifier,
+              linux: input.getAttribute('data-focus-modifier-linux'),
+              mac: input.getAttribute('data-focus-modifier-mac'),
+              windows: input.getAttribute('data-focus-modifier-win')
+            }
+            if (os && modifierAttr[os]) {
+              // a specific modifier key has been set by the user
+              modifierKey = modifierAttr[os]
+            } else {
+              modifierKey = modifierAttr.default
+            }
+
+            // validate passed in modifier
+            const recognizedModifiers = ['ctrl', 'alt', 'opt', 'meta', 'cmd', defaultModifier]
+            if (!recognizedModifiers.includes(modifierKey)) {
+              console.error(`Received an unrecognized modifier, "${modifierKey}," defaulting to "${defaultModifier}."`, input)
+              modifierKey = defaultModifier
+            }
+
+            // retrieve modifier symbol
+            if (['alt', 'opt'].includes(modifierKey)) {
+              modifierSymbol = os === 'mac' ? '⌥' : '⎇'
+            } else if (['meta', 'win', 'cmd'].includes(modifierKey) || (modifierKey === defaultModifier && os === 'mac')) {
+              if (os === 'mac') {
+                modifierSymbol = '⌘'
+              } else if (os === 'linux') {
+                modifierSymbol = '◆'
+              } else {
+                modifierSymbol = '⊞'
+              }
+            } else if (modifierKey === 'ctrl' || (modifierKey === defaultModifier && (os === 'windows' || os === 'linux'))) {
+              if (os === 'mac') {
+                modifierSymbol = '⌃'
+              } else {
+                modifierSymbol = 'Ctrl'
+              }
+            }
+
+            // add the shortcut to the cached array, if not a duplicate
+            if (keyboardShortcuts.some(shortcut => shortcut.key === focusKey && shortcut.modifier === modifierKey)) {
+              console.error(`Duplicate keyboard shortcut "${modifierKey} + ${focusKey}" detected. Only the first input will be focusable using this keyboard shortcut.`, input)
+            } else {
+              keyboardShortcuts.push({
+                key: focusKey,
+                modifier: modifierKey,
+                input,
+                os,
+                defaultModifier
+              })
+            }
+
+            // set the shortcut indicator/title
+            if (input.nodeName === 'TEXTAREA' || input.type === 'text' || input.type === 'number') {
+              // create focus indicator for valid inputs
+              const indicator = document.createElement('span')
+              indicator.classList.add('focus-key')
+              indicator.innerHTML = `<kbd>${modifierSymbol} ${focusKey.toUpperCase()}</kbd>`
+              insertAfter(indicator, newLabel)
+            } else {
+              // update the input title
+              if (input.getAttribute('title')) {
+                input.setAttribute('title', input.getAttribute('title') + ` (${modifierSymbol} + ${focusKey})`)
+              } else {
+                input.setAttribute('title', `Focus with ${modifierSymbol} + ${focusKey}`)
+              }
+            }
+          }
+
+          // placed in a function so that it may exit while still completing other semantic-form enhancements
+          handleKeyboardShortcut()
+        }
+        // #endregion
+
         // #region standard inputs
         // check for auto-grow attribute on textareas
         if (input.getAttribute('data-auto-grow') !== null) {
@@ -133,7 +297,6 @@ const semanticForms = () => {
             newInput.setAttribute('data-auto-grow', '')
             input.replaceWith(newInput)
             input = newInput
-
           }
 
           if (input.nodeName === 'TEXTAREA') {
@@ -194,9 +357,9 @@ const semanticForms = () => {
             dd.classList.remove(match)
             div.classList.add(match)
           }
-          
+
           // check for max-content attribute
-          // this may be removed once fully supported in Firefox and Safari: https://caniuse.com/wf-field-sizing 
+          // this may be removed once fully supported in Firefox and Safari: https://caniuse.com/wf-field-sizing
           if (input.getAttribute('data-max-content') !== null) {
             if (!('fieldSizing' in document.createElement('input').style)) {
               const adjustWidth = () => {
@@ -342,7 +505,7 @@ const semanticForms = () => {
           }
 
           // progressively enhance textarea for Firefox and Safari
-          // this may be removed once fully supported in Firefox and Safari: https://caniuse.com/wf-field-sizing 
+          // this may be removed once fully supported in Firefox and Safari: https://caniuse.com/wf-field-sizing
           if (input.getAttribute('data-auto-grow') !== null) {
             const adjustHeight = () => {
               if (input.value.length) {
@@ -380,6 +543,25 @@ const semanticForms = () => {
     else referenceNode.parentNode.appendChild(newNode)
   }
 
+  /**
+   * Uses the navigator to best determine the clients operating system.
+   * @returns Operating system string (`mac`, `windows`, `linux`)
+   */
+  function getOS () {
+    const userAgent = window.navigator.userAgent
+    const platform = window.navigator.platform
+    let os = null
+
+    if (platform.includes('Win')) {
+      os = 'windows'
+    } else if (platform.includes('Mac') || /iPhone|iPad|iPod/.test(userAgent)) {
+      os = 'mac'
+    } else if (platform.includes('Linux') || /Android/.test(userAgent)) {
+      os = 'linux'
+    }
+    return os
+  }
+
   // handle undo/redo
   let lastFocusedInput
   let lastClearFieldPressed