Keyboard Shortcuts

V2 data forms can declare keyboard shortcuts as a top-level array on the schema. Each entry binds a key combination to a named script and is registered under a per-form scope, so a form effectively resets all of its shortcuts every time it mounts — you never have to manually un-register them.

Why declarative

Shortcuts live in the schema next to scripts and bridge. The form author writes a key → script mapping; the platform handles registration, scoping, and cleanup. Because each shortcut points at a named script, the same script can be invoked via a hotkey, a button click, a trigger, or a service-bridge response without duplicating code.

Schema

Add a shortcuts array to the form’s top-level definition:

version: "2"
bridge:
  permissions: ["data:read", "navigation"]
shortcuts:
  - key: "control+1"
    description: "Jump to the invoice page"
    group: "navigation"
    scriptRef: gotoInvoice
  - key: "control+f"
    altKey: "meta+f"
    description: "Focus the total field"
    scriptRef: focusTotal
scripts:
  gotoInvoice: |
    (ctx, bridge) => bridge.navigation.setPage(1)
  focusTotal: |
    (ctx, bridge) => bridge.navigation.focusAttribute(
      ctx.dataObjects[0]?.uuid,
      "invoice/total"
    )
nodes:
  - component: v2:panel
    # ...

FormShortcut Fields

Field	Type	Required	Description
`key`	`string`	Yes	Primary binding (e.g. `"control+1"`, `"meta+shift+s"`)
`altKey`	`string \| string[]`	No	One or more alternative bindings that also fire the script
`description`	`string`	Yes	Label shown in the keyboard-shortcuts help dialog (`⌘/`)
`group`	`string`	No	Help-dialog group: `"navigation"`, `"zoom"`, `"data-entry"`, `"document"`, or `"ui"`
`scriptRef`	`string`	Yes	Name of a script in the form’s `scripts` map to invoke

Lifecycle and scoping

Every shortcut is registered under the scope form:<viewId>. The platform:

On mount — clears the scope (so a stale registration from a previous mount is gone), then registers each entry under the scope.
On shortcuts change — runs the same clear-then-register cycle automatically. Hot-reloading a form during development replaces the bindings cleanly.
On unmount — clears the scope. Shortcuts from other forms or the global help dialog are untouched.

Because scopes are isolated, two open forms can register the same key in different ways — the binding effective at any moment is the one belonging to the most recently mounted form for that key.

If your form’s key collides with a global shortcut already in the help dialog (for example meta+/), the existing global binding wins and the form’s is silently dropped. Prefer keys not used globally.

Cross-platform notation

You author bindings with the same key string on every platform (for example control+1), and the platform normalizes them to the keystroke each browser actually delivers, so most bindings work for Windows, Linux, and Mac reviewers without per-platform entries. On Mac this means:

control+X is rewritten to ⌘⌥X (meta+alt) at runtime. A binding declared as control+1 therefore fires when a Mac reviewer presses ⌘⌥1, not the physical Control key. This is expected — if you are debugging why a control+1 shortcut appears to respond to ⌘⌥1 on Mac, that is the normalization at work.
alt+<letter> and alt+<digit> chords auto-derive the macOS-substituted character. macOS turns ⌥+key into a special character (for example ⌥R→®, ⌥6→§, ⌥⇧R→‰), and the shortcut auto-registers that form so a plain ⌥+key still triggers. Note: the option dead-key letters (e, i, n, u) and ⌥⇧K produce no standalone character and are not auto-derived — declare an explicit altKey for those.
Registered chords are reclaimed from the browser. Any registered chord is intercepted in the capture phase (preventDefault) so the browser’s built-in behaviour — Chrome tab switching on Ctrl+PageDown / Ctrl+5–8 (matched as ⌘⌥5–8 on Mac), for example — doesn’t consume it first. This only applies when focus is outside an input, textarea, select, or contentEditable element, so typing in a field is never affected.

The altKey field still lets you add explicit alternative bindings when you want one; the Mac rewrites above happen automatically and do not require an altKey entry.

Inside the script

Scripts referenced by scriptRef follow the standard V2 signature — a function of (ctx, bridge):

(ctx, bridge) => {
  // ctx exposes the form's data context plus a `shortcut` payload
  // describing the FormShortcut entry that fired this invocation.
  bridge.log.debug("Triggered by " + ctx.shortcut.key);

  // bridge.* gives you the same Bridge API documented under
  // "Bridge API & External Services".
  bridge.navigation.setPage(1);
}

The ctx.shortcut payload ({ key, description, scriptRef, ... }) is added by the shortcut dispatcher so a single script can branch on which binding fired it.

What scripts typically do

The most common actions a shortcut performs are spatial navigation, attribute focus, and data-object manipulation — all available through the bridge:

// Jump the spatial viewer to a known page
bridge.navigation.setPage(3);

// Focus a specific field and highlight its tag in the document
bridge.navigation.focusAttribute(parentUuid, "shipment/originZip");

// Read the current page so a shortcut can "go to next page in this group"
const current = bridge.navigation.getCurrentPage();
const total = bridge.navigation.getPageCount();
if (current && current < total) bridge.navigation.setPage(current + 1);

// Add a child data object under a known parent
const obj = await bridge.data.addDataObject(parentUuid, "LineItem");
bridge.data.setAttribute(obj.uuid, "LineItem/Description", "New line");

See Bridge API & External Services for the full method surface.

Example: rotate the current page

A common review task is fixing a sideways scan. bridge.navigation.rotatePage(direction) rotates the spatial viewer’s current page by 90° in the given direction, and a pair of shortcuts makes it a one-keystroke flip:

version: "2"
bridge:
  permissions: ["navigation"]
shortcuts:
  - key: "alt+r"
    description: "Rotate page right"
    group: "document"
    scriptRef: rotateRight
  - key: "alt+shift+r"
    description: "Rotate page left"
    group: "document"
    scriptRef: rotateLeft
scripts:
  rotateRight: |
    (ctx, bridge) => bridge.navigation.rotatePage("right")
  rotateLeft: |
    (ctx, bridge) => bridge.navigation.rotatePage("left")

alt+r and alt+shift+r are example bindings chosen by the form author — exactly like every other shortcut in this guide, you pick the keys — not a fixed global hotkey. Swap them for any combination that suits your reviewers. A few things to know about rotatePage:

Permission. It calls the navigation capability, so "navigation" must be in bridge.permissions.
Direction is "left" or "right". Those are the only two accepted values. Any other string is ignored (a console warning is logged and the call is a no-op).
Rotation is relative. Each call turns the page ±90° from its current angle rather than setting an absolute angle — so calling rotatePage("right") twice lands at 180°, and a following rotatePage("left") returns it to 90°.
Current page only. It rotates just the page the viewer is on. Rotating every page of a document remains a separate menu action.
Targets one document. With no argument it rotates the page of the form’s default (first) document family. Pass an optional documentFamilyId — bridge.navigation.rotatePage("right", familyId) — to target a specific open document; rotation applied to one document does not bleed across to others.

The method returns nothing. An invalid direction logs a console warning and is a no-op, but a missing navigation permission throws a Permission denied: navigation error like any other gated Bridge call.

Permissions

Shortcut scripts call the same Bridge API as any other V2 script, so they obey the same bridge.permissions contract. A shortcut that calls bridge.navigation.setPage(...) needs "navigation" in the form’s permissions array; one that calls bridge.data.addDataObject(...) needs "data:write". Permission errors surface to the browser console and the shortcut becomes a no-op.

Help dialog

Registered shortcuts appear in the global keyboard-shortcuts help dialog (open with ⌘/ on Mac or Ctrl+/ on Windows/Linux), grouped by the optional group field. Use a clear description — that’s what users will see when they’re hunting for a key.

Example: invoice review form

A reviewer-oriented form that binds the number keys to the document’s classification groups and uses Tab-like flow to move between common fields:

version: "2"
bridge:
  permissions: ["data:read", "data:write", "navigation"]
shortcuts:
  - key: "control+1"
    description: "Jump to Invoice"
    group: "navigation"
    scriptRef: gotoInvoice
  - key: "control+2"
    description: "Jump to Bill of Lading"
    group: "navigation"
    scriptRef: gotoBOL
  - key: "control+t"
    description: "Focus invoice total"
    group: "data-entry"
    scriptRef: focusTotal
  - key: "control+n"
    description: "Add a line item"
    group: "data-entry"
    scriptRef: addLineItem
scripts:
  gotoInvoice: |
    (ctx, bridge) => bridge.navigation.setPage(
      ctx.invoicePage ?? 1
    )
  gotoBOL: |
    (ctx, bridge) => bridge.navigation.setPage(
      ctx.bolPage ?? 2
    )
  focusTotal: |
    (ctx, bridge) => bridge.navigation.focusAttribute(
      ctx.dataObjects[0]?.uuid,
      "invoice/total"
    )
  addLineItem: |
    async (ctx, bridge) => {
      const parent = ctx.dataObjects[0];
      const obj = await bridge.data.addDataObject(parent.uuid, "LineItem");
      bridge.navigation.focusAttribute(obj.uuid, "LineItem/Description");
    }

When the reviewer opens this form, four shortcuts appear in the help dialog under “Navigation” and “Data Entry”. Switching to a different form removes them; reopening this form restores them. No manual cleanup is required.

Conformance

The shortcut dispatcher and Bridge API are covered by a conformance suite in kodexa-ui/src/schema/runtime/conformance/. Each binding behaviour ships as a paired .js + .expected.json script that runs against a stub-store-backed Bridge — the suite catches binding regressions before they reach the browser.

Introduction

Activity Plans

Triggers

Task Templates

Task Groups

MCP Connector

Data Definitions

Excel Processing

Scripting

Intakes

Formulas

Project Templates

Data Forms

Working with Claude Code

Working with Kodexa Agent

Reference

Why declarative

Schema

FormShortcut Fields

Lifecycle and scoping

Cross-platform notation

Inside the script

What scripts typically do

Example: rotate the current page

Permissions

Help dialog

Example: invoice review form

Conformance

​Why declarative

​Schema

​FormShortcut Fields

​Lifecycle and scoping

​Cross-platform notation

​Inside the script

​What scripts typically do

​Example: rotate the current page

​Permissions

​Help dialog

​Example: invoice review form

​Conformance

Why declarative

Schema

FormShortcut Fields

Lifecycle and scoping

Cross-platform notation

Inside the script

What scripts typically do

Example: rotate the current page

Permissions

Help dialog

Example: invoice review form

Conformance