From 65f111b8b4a3ea803cea2556ca74eeda0b9c2647 Mon Sep 17 00:00:00 2001 From: Konstantin Schaper Date: Tue, 11 Oct 2022 16:29:33 +0200 Subject: [PATCH] Add keyboard shortcuts documentation (#2129) There is currently no documentation which shortcuts are available to the end user, neither within the application nor the documentation published on scm-manager.org. This PR adds the missing documentation in both places and introduces a new api for developers to add documentation when using `useShortcut`. It also improves the api for conditional shortcuts significantly. --- docs/de/navigation.yml | 1 + docs/de/user/shortcuts/index.md | 37 ++++++++++ docs/en/navigation.yml | 1 + docs/en/user/shortcuts/index.md | 37 ++++++++++ gradle/changelog/shortcuts_docs.yaml | 2 + scm-ui/ui-webapp/package.json | 6 +- .../ui-webapp/public/locales/de/commons.json | 18 +++++ scm-ui/ui-webapp/public/locales/de/repos.json | 7 ++ .../ui-webapp/public/locales/en/commons.json | 18 +++++ scm-ui/ui-webapp/public/locales/en/repos.json | 7 ++ scm-ui/ui-webapp/src/containers/App.tsx | 27 +++----- scm-ui/ui-webapp/src/containers/Index.tsx | 17 +++-- .../ui-webapp/src/containers/OmniSearch.tsx | 5 +- .../src/repos/containers/RepositoryRoot.tsx | 46 +++++-------- .../src/shortcuts/ShortcutDocsModal.tsx | 68 +++++++++++++++++++ .../src/shortcuts/splitKeyCombination.test.ts | 56 +++++++++++++++ .../src/shortcuts/splitKeyCombination.ts | 37 ++++++++++ scm-ui/ui-webapp/src/shortcuts/useShortcut.ts | 56 +++++++++++---- .../src/shortcuts/useShortcutDocs.tsx | 53 +++++++++++++++ yarn.lock | 10 +++ 20 files changed, 439 insertions(+), 70 deletions(-) create mode 100644 docs/de/user/shortcuts/index.md create mode 100644 docs/en/user/shortcuts/index.md create mode 100644 gradle/changelog/shortcuts_docs.yaml create mode 100644 scm-ui/ui-webapp/src/shortcuts/ShortcutDocsModal.tsx create mode 100644 scm-ui/ui-webapp/src/shortcuts/splitKeyCombination.test.ts create mode 100644 scm-ui/ui-webapp/src/shortcuts/splitKeyCombination.ts create mode 100644 scm-ui/ui-webapp/src/shortcuts/useShortcutDocs.tsx diff --git a/docs/de/navigation.yml b/docs/de/navigation.yml index dea28ffb8a..0ff8cc2a19 100644 --- a/docs/de/navigation.yml +++ b/docs/de/navigation.yml @@ -7,3 +7,4 @@ - /user/profile/ - /user/notification/ - /user/cli/ + - /user/shortcuts/ diff --git a/docs/de/user/shortcuts/index.md b/docs/de/user/shortcuts/index.md new file mode 100644 index 0000000000..626927c78e --- /dev/null +++ b/docs/de/user/shortcuts/index.md @@ -0,0 +1,37 @@ +--- +title: Tastaturkürzel +--- +Der SCM-Manager unterstützt Tastaturinteraktion und -navigation durch zusätzliche Tastenkürzel. + +### Übersicht + +Während sie den SCM-Manager verwenden, können sie eine Übersicht aller dem aktiven Benutzer auf der aktuellen Seite verfügbaren Tastenkürzel mittels der `?`-Taste aufrufen. + +### Globale Tastenkürzel + +| Key Combination | Description | +|-----------------|-------------------------------------| +| ? | Öffne die Tastaturkürzelübersicht | +| / | Fokussiere die globale Schnellsuche | +| alt r | Navigiere zur Repositoryübersicht | +| alt u | Navigiere zur Benutzerübersicht | +| alt g | Navigiere zur Gruppenübersicht | +| alt a | Navigiere zur Administration | + +### Repositoryspezifische Tastenkürzel + +| Key Combination | Description | +|-----------------|---------------| +| g i | Info | +| g b | Branches | +| g t | Tags | +| g c | Code | +| g s | Einstellungen | + +### Tastenkürzel aus Plugin + +Plugins können selbst neue Tastenkürzel definieren. +Diese können global oder repository-spezifisch sein oder in einem komplett anderen Kontext angewandt werden. +Sie werden automatisch in der Übersicht im SCM-Manager mit aufgelistet. +Um die Tastenkürzel eines Plugins innerhalb der Benutzerdokumentation zu finden, verweisen wir hier auf die Dokumentation +des jeweiligen Plugins. diff --git a/docs/en/navigation.yml b/docs/en/navigation.yml index 98507e081f..7152f930a7 100644 --- a/docs/en/navigation.yml +++ b/docs/en/navigation.yml @@ -16,6 +16,7 @@ - /user/profile/ - /user/notification/ - /user/cli/ + - /user/shortcuts/ - section: Administration entries: diff --git a/docs/en/user/shortcuts/index.md b/docs/en/user/shortcuts/index.md new file mode 100644 index 0000000000..adaa139fc6 --- /dev/null +++ b/docs/en/user/shortcuts/index.md @@ -0,0 +1,37 @@ +--- +title: Shortcuts +--- +The SCM-Manager enhances keyboard interaction and navigation through additional shortcuts. + +### Summary + +While using the SCM-Manager, a summary of all shortcuts available to the active user on the current page can be opened +from anywhere by pressing the `?` key. + +### Global Shortcuts + +| Key Combination | Description | +|-----------------|----------------------------| +| ? | Open the shortcut summary | +| / | Focus global quick search | +| alt r | Navigate to Repositories | +| alt u | Navigate to Users | +| alt g | Navigate to Groups | +| alt a | Navigate to Administration | + +### Repository-specific Shortcuts + +| Key Combination | Description | +|-----------------|-------------| +| g i | Info | +| g b | Branches | +| g t | Tags | +| g c | Code | +| g s | Settings | + +### Plugin Shortcuts + +Plugins can introduce new shortcuts. +They may be global, repository-specific or connected to an entirely different context. +They will automatically be included in the summary generated within the SCM-Manager. +To find the shortcuts outside the SCM-Manager, please refer to the documentation of the plugin. diff --git a/gradle/changelog/shortcuts_docs.yaml b/gradle/changelog/shortcuts_docs.yaml new file mode 100644 index 0000000000..8e7f8ef06a --- /dev/null +++ b/gradle/changelog/shortcuts_docs.yaml @@ -0,0 +1,2 @@ +- type: added + description: Keyboard shortcuts documentation ([#2129](https://github.com/scm-manager/scm-manager/pull/2129)) diff --git a/scm-ui/ui-webapp/package.json b/scm-ui/ui-webapp/package.json index 51ad0b7199..90f49c89dd 100644 --- a/scm-ui/ui-webapp/package.json +++ b/scm-ui/ui-webapp/package.json @@ -27,7 +27,8 @@ "string_score": "^0.1.22", "styled-components": "^5.3.5", "systemjs": "0.21.6", - "mousetrap": "^1.6.5" + "mousetrap": "^1.6.5", + "ua-parser-js": "^1.0.2" }, "scripts": { "test": "jest", @@ -50,6 +51,7 @@ "@types/styled-components": "^5.1.25", "@types/systemjs": "^0.20.6", "@types/mousetrap": "^1.6.9", + "@types/ua-parser-js": "^0.7.36", "fetch-mock": "^7.5.1", "react-test-renderer": "^17.0.1" }, @@ -68,4 +70,4 @@ "publishConfig": { "access": "public" } -} \ No newline at end of file +} diff --git a/scm-ui/ui-webapp/public/locales/de/commons.json b/scm-ui/ui-webapp/public/locales/de/commons.json index 5a039f59bb..c44a317c2e 100644 --- a/scm-ui/ui-webapp/public/locales/de/commons.json +++ b/scm-ui/ui-webapp/public/locales/de/commons.json @@ -261,5 +261,23 @@ }, "tag": { "delete": "Löschen" + }, + "shortcutDocsModal": { + "title": "Tastaturkürzel", + "description": "Die folgende Tabelle listet alle für Sie auf der aktuellen Seite verfügbaren Tastaturkürzel auf.", + "table": { + "headers": { + "keyCombination": "Tastenkombination", + "description": "Beschreibung" + } + } + }, + "shortcuts": { + "search": "Fokussiere die globale Schnellsuche", + "repositories": "Navigiere zur Repositoryübersicht", + "users": "Navigiere zur Benutzerübersicht", + "groups": "Navigiere zur Gruppenübersicht", + "admin": "Navigiere zur Administration", + "docs": "Öffne die Tastaturkürzelübersicht" } } diff --git a/scm-ui/ui-webapp/public/locales/de/repos.json b/scm-ui/ui-webapp/public/locales/de/repos.json index a71ece8ff3..744da2f5da 100644 --- a/scm-ui/ui-webapp/public/locales/de/repos.json +++ b/scm-ui/ui-webapp/public/locales/de/repos.json @@ -538,5 +538,12 @@ "queryToShort": "Tippe mindestens 2 Zeichen ein, um die Suche zu starten", "emptyResult": "Es wurden keine Ergebnisse für <0>{{query}} gefunden" } + }, + "shortcuts": { + "info": "Info", + "branches": "Branches", + "tags": "Tags", + "code": "Code", + "settings": "Einstellungen" } } diff --git a/scm-ui/ui-webapp/public/locales/en/commons.json b/scm-ui/ui-webapp/public/locales/en/commons.json index 8d72828333..f808cc39fe 100644 --- a/scm-ui/ui-webapp/public/locales/en/commons.json +++ b/scm-ui/ui-webapp/public/locales/en/commons.json @@ -262,5 +262,23 @@ }, "tag": { "delete": "Delete" + }, + "shortcutDocsModal": { + "title": "Keyboard Shortcuts", + "description": "The following table lists all keyboard shortcuts available to you on the current page.", + "table": { + "headers": { + "keyCombination": "Key Combination", + "description": "Description" + } + } + }, + "shortcuts": { + "search": "Focus global quick search", + "repositories": "Navigate to Repositories", + "users": "Navigate to Users", + "groups": "Navigate to Groups", + "admin": "Navigate to Administration", + "docs": "Open the shortcut summary" } } diff --git a/scm-ui/ui-webapp/public/locales/en/repos.json b/scm-ui/ui-webapp/public/locales/en/repos.json index 778854e0cf..9acd935234 100644 --- a/scm-ui/ui-webapp/public/locales/en/repos.json +++ b/scm-ui/ui-webapp/public/locales/en/repos.json @@ -545,5 +545,12 @@ "queryToShort": "Type at least two characters to start the search", "emptyResult": "Nothing found for query <0>{{query}}" } + }, + "shortcuts": { + "info": "Info", + "branches": "Branches", + "tags": "Tags", + "code": "Code", + "settings": "Settings" } } diff --git a/scm-ui/ui-webapp/src/containers/App.tsx b/scm-ui/ui-webapp/src/containers/App.tsx index 3c274564bf..73140f9aef 100644 --- a/scm-ui/ui-webapp/src/containers/App.tsx +++ b/scm-ui/ui-webapp/src/containers/App.tsx @@ -34,6 +34,7 @@ import useShortcut from "../shortcuts/useShortcut"; import Login from "./Login"; import NavigationBar from "./NavigationBar"; import styled from "styled-components"; +import ShortcutDocsModal from "../shortcuts/ShortcutDocsModal"; const AppWrapper = styled.div` min-height: 100vh; @@ -47,25 +48,18 @@ const App: FC = () => { usePauseShortcutsWhenModalsActive(); const history = useHistory(); - useShortcut("option+r", () => { - if (index && index._links["repositories"]) { - history.push("/repos/"); - } + + useShortcut("option+r", () => history.push("/repos/"), t("shortcuts.repositories"), { + active: !!index?._links["repositories"], }); - useShortcut("option+u", () => { - if (index && index._links["users"]) { - history.push("/users/"); - } + useShortcut("option+u", () => history.push("/users/"), t("shortcuts.users"), { + active: !!index?._links["users"], }); - useShortcut("option+g", () => { - if (index && index._links["groups"]) { - history.push("/groups/"); - } + useShortcut("option+g", () => history.push("/groups/"), t("shortcuts.groups"), { + active: !!index?._links["groups"], }); - useShortcut("option+a", () => { - if (index && index._links["config"]) { - history.push("/admin/"); - } + useShortcut("option+a", () => history.push("/admin/"), t("shortcuts.admin"), { + active: !!index?._links["config"], }); if (!index) { @@ -95,6 +89,7 @@ const App: FC = () => {
+
{content}