feat: add NcKbd component #7401

ShGKme · 2025-08-27T22:15:57Z

☑️ Resolves

Ref: [Meta] Forms design improvement #7124
First component for keyboard shortcuts — replacement for <kbd>
- Custom styling
- Localized key names
- Auto icons
- macOS handling
- Custom slot for customisation

Note: complete form will have an additional component for an entire keyboard shortcut list

🖼️ Screenshots

Windows

macOS

🏁 Checklist

⛑️ Tests are included or are not applicable
📘 Component documentation has been extended, updated or is not applicable
2️⃣ Backport to stable8 for maintained Vue 2 version or not applicable

src/components/NcKbd/NcKbd.vue

susnux · 2025-08-28T09:53:57Z

src/components/NcKbd/NcKbd.vue

+	Escape: !mac
+		? t('Escape') // TRANSLATORS: Escape key on keyboard
+		: '⎋',
+	Space: t('Space'), // TRANSLATORS: Space key on keyboard


if we sometimes use icons for them, maybe use this for space?
https://pictogrammers.com/library/mdi/icon/keyboard-space/

its quite common, no? cc @nextcloud-libraries/designers

We never use icons (images). It was discussed with @kra-mo that symbols look fine on macOS.

Same for the space — even though there is a symbol, it was decided to use a word here.

Definitely would put it for mac, otherwise it stands out too much.
Also might be less confusion for translators. That's usually the only button that doesn't have a text on a physical keyboard, and also the one i would translate out of all other

UPD: maybe this? ␣

Yes it will look silly translated like in German I rarely see this like

[Strg] + [Leertaste]

I would expect the icon for the space key as it does not has any label on the keyboard.
But also for the other icons you added for Mac, are you sure they work for screen readers? If not maybe just use icons and add aria label with the real name.

I didn't test these symbols specifically, but usually it works well with screen readers.
I'd prefer to use symbols to safe from translating it.

We can also add a comment for translator to translate it only if it is a common practice.

E.g., CTRL almost never translated in Russian.

In any case, I think the word Space is still more well-recognized internationally than the ␣ symbol, but I might be wrong.

Could you show some example in an app on Linux?

E.g.:

At least everything is better than the firefox and thunderbird shortcuts help which uses really silly names...
If you both did not see the symbol that often then its probably fine, it just stands out quite visible for MacOS

it just stands out quite visible for MacOS

I do agree that it does, but for macOS specifically, it's just about following platform conventions

src/components/NcKbd/NcKbd.vue

susnux

Space as icon or as text is a @nextcloud-libraries/designers decision, while I rarely saw a label used (especially translated) its probably ok.
So I let this up to the designers - code is fine!

Antreesy

Otherwise good

src/utils/platform.ts

src/components/NcKbd/NcKbd.vue

Signed-off-by: Grigorii K. Shartsev <me@shgk.me>

ShGKme · 2025-08-28T12:28:01Z

Rebased onto main, squashed

ShGKme · 2025-08-28T12:28:29Z

If we decied to use an icon for the space, we can update it later without a breaking change.

ShGKme · 2025-08-28T12:32:16Z

src/components/NcKbd/NcKbd.vue

+	/**
+	 * Key name or symbol to display.
+	 * For common special keys (CTRL, ALT, SHIFT, Arrow keys, etc.) it will display the symbol on macOS and the localized name on Windows/Linux.
+	 */
+	symbol?: 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Control' | 'Alt' | 'Shift' | 'Enter' | 'Space' | 'Tab' | 'Delete' | 'Escape' | (string & {})


Just in case before merging.

@susnux Are you fine with this prop name?
(key cannot be used as it is a special attribute).
Alternative: keyname, keycode (but it has a different meaning in web api), code.

As you also write "Key name" as the doc I think keyname is pretty good.
But also symbol seems to fit here so you can merged if you like ;)

But proper name would be keyName which would be <NcKbd key-name="..." /> maybe stick with symbol instead 😅

@Antreesy Do I remember it correctly, that in useHotKey the preferred way to set a key is the keyCode (like KeyF, not F)?

No it takes F and then checks if key is equal (e.g. F === F) otherwise falls back to get the keyCode and removes the Key or Digit and then compares

Just F would be preferable, as we can then derive the keyCode from it

ShGKme · 2025-08-28T19:16:41Z

/backport to stable1

backportbot · 2025-08-28T19:16:46Z

The backport to stable1 failed. Please do this backport manually.

# Switch to the target branch and update it
git checkout stable1
git pull origin stable1

# Create the new backport branch
git checkout -b backport/7401/stable1

# Cherry pick the change from the commit sha1 of the change against the default branch
# This might cause conflicts, resolve them
git cherry-pick deaebab5 0e596d41

# Push the cherry pick commit to the remote repository and open a pull request
git push origin backport/7401/stable1

Error: Failed to clone repository: Failed to create working tree: Preparing worktree (new branch 'backport/7401/stable1')
fatal: not a valid object name: 'origin/stable1'

Learn more about backports at https://docs.nextcloud.com/server/stable/go.php?to=developer-backports.

susnux · 2025-08-28T19:37:13Z

backport to stable1

Quite old branch ;)

susnux · 2025-08-28T19:37:19Z

/backport to stable8

ShGKme · 2025-08-28T19:37:51Z

Quite old branch ;)

I'm tired 😴

ShGKme added this to the 9.0.0-rc.7 milestone Aug 27, 2025

ShGKme self-assigned this Aug 27, 2025

ShGKme added enhancement New feature or request 2. developing Work in progress labels Aug 27, 2025

Antreesy reviewed Aug 28, 2025

View reviewed changes

src/components/NcKbd/NcKbd.vue Outdated Show resolved Hide resolved

ShGKme force-pushed the feat/NcKbd branch from b96e011 to 21cb243 Compare August 28, 2025 09:45

ShGKme added 3. to review Waiting for reviews and removed 2. developing Work in progress labels Aug 28, 2025

ShGKme marked this pull request as ready for review August 28, 2025 09:47

ShGKme requested a review from susnux August 28, 2025 09:49

kra-mo approved these changes Aug 28, 2025

View reviewed changes

susnux reviewed Aug 28, 2025

View reviewed changes

src/components/NcKbd/NcKbd.vue Show resolved Hide resolved

susnux reviewed Aug 28, 2025

View reviewed changes

src/components/NcKbd/NcKbd.vue Show resolved Hide resolved

susnux approved these changes Aug 28, 2025

View reviewed changes

Antreesy approved these changes Aug 28, 2025

View reviewed changes

src/utils/platform.ts Outdated Show resolved Hide resolved

src/components/NcKbd/NcKbd.vue Show resolved Hide resolved

susnux approved these changes Aug 28, 2025

View reviewed changes

ShGKme added 2 commits August 28, 2025 14:27

feat: add NcKbd component

deaebab

Signed-off-by: Grigorii K. Shartsev <me@shgk.me>

chore(l10n): extract

0e596d4

Signed-off-by: Grigorii K. Shartsev <me@shgk.me>

ShGKme force-pushed the feat/NcKbd branch from 3131112 to 0e596d4 Compare August 28, 2025 12:27

ShGKme commented Aug 28, 2025

View reviewed changes

ShGKme merged commit 69d410c into main Aug 28, 2025
25 checks passed

ShGKme deleted the feat/NcKbd branch August 28, 2025 19:16

backportbot bot added the backport-request label Aug 28, 2025

backportbot bot mentioned this pull request Aug 28, 2025

[stable8] feat: add NcKbd component #7407

Merged

2 tasks

backportbot bot removed the backport-request label Aug 28, 2025

Antreesy mentioned this pull request Sep 1, 2025

chore: release v9.0.0-rc.8 #7421

Merged

Antreesy modified the milestones: 9.0.0-rc.7, 9.0.0-rc.8 Sep 1, 2025

AndyScherzinger mentioned this pull request Sep 15, 2025

[Meta] Forms design improvement #7124

Closed

feat: add NcKbd component #7401

feat: add NcKbd component #7401

Uh oh!

Conversation

ShGKme commented Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

☑️ Resolves

🖼️ Screenshots

Windows

macOS

🏁 Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Antreesy Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

susnux left a comment

Choose a reason for hiding this comment

Uh oh!

Antreesy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ShGKme commented Aug 28, 2025

Uh oh!

ShGKme commented Aug 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ShGKme commented Aug 28, 2025

Uh oh!

backportbot bot commented Aug 28, 2025

Uh oh!

susnux commented Aug 28, 2025

Uh oh!

susnux commented Aug 28, 2025

Uh oh!

ShGKme commented Aug 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ShGKme commented Aug 27, 2025 •

edited

Loading

Antreesy Aug 28, 2025 •

edited

Loading