Merge pull request #2813 from SUI-Components/kbd

feat(components/atom/kbd): add new component

components/atom/kbd/.gitignore

@@ -0,0 +1,2 @@
+lib
+node_modules

components/atom/kbd/.npmignore

@@ -0,0 +1,6 @@
+assets
+demo
+src
+test
+node_modules
+CHANGELOG.md

components/atom/kbd/CHANGELOG.md

@@ -0,0 +1 @@
+# CHANGELOG

components/atom/kbd/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 SUI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

components/atom/kbd/README.md

@@ -0,0 +1,32 @@
+# AtomKbd
+
+> The keyboard key component exists to show which key or combination of keys performs a given action.
+
+[![documentation](https://img.shields.io/badge/read%20the%20doc-black?logo=readthedocs)](https://sui-components.vercel.app/workbench/atom/kbd/)
+[![issue](https://img.shields.io/badge/report%20a%20bug-black?logo=openbugbounty&logoColor=red)](https://github.com/SUI-Components/sui-components/issues/new?&projects=4&template=bug-report.yml&assignees=&template=report-a-bug.yml&title=🪲+&labels=bug,component,atom,kbd)
+[![npm](https://img.shields.io/npm/dt/%40s-ui/react-atom-kbd?logo=npm&labelColor=black)](https://www.npmjs.com/package/@s-ui/react-atom-kbd)
+
+[![Issues open](https://img.shields.io/github/issues-search/SUI-Components/sui-components?query=is%3Aopen%20label%3Acomponent%20label%3Akbd&logo=openbugbounty&logoColor=red&label=issues%20open&color=red)](https://github.com/SUI-Components/sui-components/issues?q=is%3Aopen+label%3Acomponent+label%3Akbd)
+[![NPM](https://img.shields.io/npm/l/%40s-ui%2Freact-atom-kbd)](https://github.com/SUI-Components/sui-components/blob/main/components/atom/kbd/LICENSE.md)
+
+## Installation
+
+```sh
+$ npm install @s-ui/react-atom-kbd --save
+```
+
+## Usage
+
+### Basic usage
+```js
+import Kbd from '@s-ui/react-atom-kbd'
+
+return (
+  <AtomKbd>
+    A
+  </AtomKbd>
+)
+```
+
+
+> **Find full description and more examples in the [demo page](https://sui-components.now.sh/workbench/atom/kbd/demo).**

components/atom/kbd/demo/articles/ArticleA11y.js

@@ -0,0 +1,23 @@
+import PropTypes from 'prop-types'
+
+import {Article, Box, H2, Paragraph} from '@s-ui/documentation-library'
+
+const ArticleA11y = ({className}) => {
+  return (
+    <Article className={className}>
+      <H2>Accessibility</H2>
+      <Box style={{backgroundColor: 'color-mix(in srgb, #00FF00 10%, transparent)'}}>
+        <Paragraph>
+          ✅ This component has been successfully tested for WCAG 2.0 levels A and AA, WCAG 2.1 levels A and AA and for
+          common accessibility best practices.
+        </Paragraph>
+      </Box>
+    </Article>
+  )
+}
+
+ArticleA11y.propTypes = {
+  className: PropTypes.string
+}
+
+export default ArticleA11y

components/atom/kbd/demo/articles/ArticleCombinations.js

@@ -0,0 +1,39 @@
+import PropTypes from 'prop-types'
+
+import {Article, H2, Paragraph, Strong} from '@s-ui/documentation-library'
+
+import AtomKbd from '../../src/index.js'
+
+const ArticleCombinations = ({className}) => {
+  return (
+    <Article className={className}>
+      <H2>Combinations</H2>
+      <Paragraph>
+        The only punctuation you should need is the + to indicate that a combination of keys will activate the shortcut.
+      </Paragraph>
+      <Article style={{display: 'block', width: '100%'}}>
+        <AtomKbd>shift</AtomKbd> + <AtomKbd>H</AtomKbd>
+      </Article>
+      <Paragraph>
+        If two different keys can execute the same action or the shortcut itself may look different on the user's
+        keyboard, write "or" in between.
+      </Paragraph>
+      <Article style={{display: 'block', width: '100%'}}>
+        <AtomKbd>shift</AtomKbd> or <AtomKbd>H</AtomKbd>
+      </Article>
+      <Paragraph>
+        When combining a keyboard key and a mouse action combine it using the previous rules and the action name bold
+        and uppercase preceded by the 🖱 symbol glyph.
+      </Paragraph>
+      <Article style={{display: 'block', width: '100%'}}>
+        <AtomKbd>option</AtomKbd> + 🖱 <Strong>SCROLL</Strong>
+      </Article>
+    </Article>
+  )
+}
+
+ArticleCombinations.propTypes = {
+  className: PropTypes.string
+}
+
+export default ArticleCombinations

components/atom/kbd/demo/articles/ArticleGuidelines.js

@@ -0,0 +1,37 @@
+import PropTypes from 'prop-types'
+
+import {Article, H2, Paragraph, UnorderedList, ListItem, Anchor} from '@s-ui/documentation-library'
+
+const ArticleGuidelines = ({className}) => {
+  return (
+    <Article className={className}>
+      <H2>Guideline</H2>
+      <Paragraph>All shortcuts should do their best to match what appears on the user’s keyboard.</Paragraph>
+      <UnorderedList>
+        <ListItem>All single letters A-Z are uppercase.</ListItem>
+        <UnorderedList>
+          <ListItem>
+            Do NOT use{' '}
+            <Anchor href="https://en.wikipedia.org/wiki/List_of_Unicode_characters">
+              Glyph unicode representations
+            </Anchor>{' '}
+            for the special key symbols.
+          </ListItem>
+        </UnorderedList>
+        <ListItem>For non-letter keys such as enter, esc and shift, stick to lowercase.</ListItem>
+        <ListItem>Use the arrow symbol as opposed to spelling things out.</ListItem>
+        <ListItem>For function keys, stick to uppercase.</ListItem>
+        <ListItem>
+          For combination between keys and mouse events type the mouse event name upper-cased preceded by the 🖱️unicode
+          glyph.
+        </ListItem>
+      </UnorderedList>
+    </Article>
+  )
+}
+
+ArticleGuidelines.propTypes = {
+  className: PropTypes.string
+}
+
+export default ArticleGuidelines

components/atom/kbd/demo/articles/ArticleKeyboard.js

@@ -0,0 +1,112 @@
+import PropTypes from 'prop-types'
+
+import {Article, H2} from '@s-ui/documentation-library'
+
+import AtomKbd from '../../src/index.js'
+
+const ArticleKeyboard = ({className}) => {
+  return (
+    <Article className={className}>
+      <H2>Default</H2>
+      <div style={{display: 'flex', justifyContent: 'space-between', flexDirection: 'column', gap: 8, maxWidth: 800}}>
+        <div style={{display: 'flex', justifyContent: 'space-between'}}>
+          <AtomKbd>esc</AtomKbd>
+          <AtomKbd>F1</AtomKbd>
+          <AtomKbd>F2</AtomKbd>
+          <AtomKbd>F3</AtomKbd>
+          <AtomKbd>F4</AtomKbd>
+          <AtomKbd>F5</AtomKbd>
+          <AtomKbd>F6</AtomKbd>
+          <AtomKbd>F7</AtomKbd>
+          <AtomKbd>F8</AtomKbd>
+          <AtomKbd>F9</AtomKbd>
+          <AtomKbd>F10</AtomKbd>
+          <AtomKbd>F11</AtomKbd>
+          <AtomKbd>F12</AtomKbd>
+          <AtomKbd>eject</AtomKbd>
+        </div>
+        <div style={{display: 'flex', justifyContent: 'space-between'}}>
+          <AtomKbd>§</AtomKbd>
+          <AtomKbd>1</AtomKbd>
+          <AtomKbd>2</AtomKbd>
+          <AtomKbd>3</AtomKbd>
+          <AtomKbd>4</AtomKbd>
+          <AtomKbd>5</AtomKbd>
+          <AtomKbd>6</AtomKbd>
+          <AtomKbd>7</AtomKbd>
+          <AtomKbd>8</AtomKbd>
+          <AtomKbd>9</AtomKbd>
+          <AtomKbd>0</AtomKbd>
+          <AtomKbd>-</AtomKbd>
+          <AtomKbd>=</AtomKbd>
+          <AtomKbd>backspace</AtomKbd>
+        </div>
+        <div style={{display: 'flex', justifyContent: 'space-between'}}>
+          <AtomKbd>tab</AtomKbd>
+          <AtomKbd>Q</AtomKbd>
+          <AtomKbd>W</AtomKbd>
+          <AtomKbd>E</AtomKbd>
+          <AtomKbd>R</AtomKbd>
+          <AtomKbd>T</AtomKbd>
+          <AtomKbd>Y</AtomKbd>
+          <AtomKbd>U</AtomKbd>
+          <AtomKbd>O</AtomKbd>
+          <AtomKbd>P</AtomKbd>
+          <AtomKbd>[</AtomKbd>
+          <AtomKbd>]</AtomKbd>
+          <AtomKbd>enter</AtomKbd>
+        </div>
+        <div style={{display: 'flex', justifyContent: 'space-between'}}>
+          <AtomKbd>caps lock</AtomKbd>
+          <AtomKbd>A</AtomKbd>
+          <AtomKbd>S</AtomKbd>
+          <AtomKbd>D</AtomKbd>
+          <AtomKbd>F</AtomKbd>
+          <AtomKbd>G</AtomKbd>
+          <AtomKbd>H</AtomKbd>
+          <AtomKbd>J</AtomKbd>
+          <AtomKbd>K</AtomKbd>
+          <AtomKbd>L</AtomKbd>
+          <AtomKbd>;</AtomKbd>
+          <AtomKbd>'</AtomKbd>
+          <AtomKbd>\</AtomKbd>
+          <AtomKbd>enter</AtomKbd>
+        </div>
+        <div style={{display: 'flex', justifyContent: 'space-between'}}>
+          <AtomKbd>shift</AtomKbd>
+          <AtomKbd>`</AtomKbd>
+          <AtomKbd>Z</AtomKbd>
+          <AtomKbd>X</AtomKbd>
+          <AtomKbd>C</AtomKbd>
+          <AtomKbd>V</AtomKbd>
+          <AtomKbd>B</AtomKbd>
+          <AtomKbd>N</AtomKbd>
+          <AtomKbd>M</AtomKbd>
+          <AtomKbd>,</AtomKbd>
+          <AtomKbd>.</AtomKbd>
+          <AtomKbd>/</AtomKbd>
+          <AtomKbd>right shift</AtomKbd>
+        </div>
+        <div style={{display: 'flex', justifyContent: 'space-between'}}>
+          <AtomKbd>fn</AtomKbd>
+          <AtomKbd>control</AtomKbd>
+          <AtomKbd>option</AtomKbd>
+          <AtomKbd>command</AtomKbd>
+          <AtomKbd>space</AtomKbd>
+          <AtomKbd>command</AtomKbd>
+          <AtomKbd>option</AtomKbd>
+          <AtomKbd>←</AtomKbd>
+          <AtomKbd>↑</AtomKbd>
+          <AtomKbd>↓</AtomKbd>
+          <AtomKbd>→</AtomKbd>
+        </div>
+      </div>
+    </Article>
+  )
+}
+
+ArticleKeyboard.propTypes = {
+  className: PropTypes.string
+}
+
+export default ArticleKeyboard

components/atom/kbd/demo/index.js

@@ -0,0 +1,32 @@
+/* eslint-disable no-console */
+
+import {H1, Paragraph} from '@s-ui/documentation-library'
+
+import ArticleKeyboard from './articles/ArticleKeyboard.js'
+import ArticleGuidelines from './articles/ArticleGuidelines.js'
+import ArticleCombinations from './articles/ArticleCombinations.js'
+import ArticleA11y from './articles/ArticleA11y.js'
+import {CLASS_SECTION} from './settings.js'
+
+import './index.scss'
+
+const Demo = () => {
+  return (
+    <div className="sui-StudioPreview">
+      <H1>Kbd</H1>
+      <Paragraph>
+        The keyboard key component exists to show which key or combination of keys performs a given action.
+      </Paragraph>
+      <br />
+      <ArticleKeyboard className={CLASS_SECTION} />
+      <br />
+      <ArticleGuidelines className={CLASS_SECTION} />
+      <br />
+      <ArticleCombinations className={CLASS_SECTION} />
+      <br />
+      <ArticleA11y className={CLASS_SECTION} />
+    </div>
+  )
+}
+
+export default Demo

components/atom/kbd/demo/index.scss

@@ -0,0 +1,6 @@
+@import '~@s-ui/react-atom-input/lib/index';
+@import '~@s-ui/react-atom-textarea/lib/index';
+@import '~@s-ui/react-atom-checkbox/lib/index';
+@import '~@s-ui/react-atom-label/lib/index';
+
+@import '../src/index';

components/atom/kbd/demo/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@s-ui/react-atom-kbd-demo",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+  }
+}

components/atom/kbd/demo/settings.js

@@ -0,0 +1,2 @@
+export const BASE_CLASS_DEMO = `DemoKbd`
+export const CLASS_SECTION = `${BASE_CLASS_DEMO}-section`

components/atom/kbd/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@s-ui/react-atom-kbd",
+  "version": "1.0.0",
+  "description": "",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "@s-ui",
+    "react",
+    "component",
+    "atom",
+    "kbd"
+  ],
+  "main": "lib/index.js",
+  "scripts": {
+    "prepublishOnly": "rimraf ./lib && npm run build:js && npm run build:styles",
+    "build:js": "babel --presets sui ./src --out-dir ./lib",
+    "build:styles": "cpx './src/**/*.scss' ./lib"
+  },
+  "dependencies": {
+    "@s-ui/component-dependencies": "1",
+    "classnames": "2.5.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SUI-Components/sui-components",
+    "directory": "components/atom/helpText"
+  },
+  "config": {
+    "title": "kbd",
+    "category": "atom",
+    "type": "components"
+  },
+  "bugs": {
+    "url": "https://github.com/SUI-Components/sui-components/issues?q=is%3Aopen+label%3A%22Component%3A+kbd%22"
+  },
+  "homepage": "https://sui-components.vercel.app/",
+  "license": "MIT"
+}