CtrlK Documentation

The first IOUX (Integrated Operational UX) for enterprise web apps. 19 modules, 150 tests, zero dependencies.

CtrlK is an interaction layer that sits between your users and your application. It adds command palette, keyboard shortcuts, saved views, persistent selections, field navigation, macros, undo, and shareable view links — on top of any existing enterprise web app. No redesign required.

Installation

# npm
npm install @ctrlk/core

# yarn
yarn add @ctrlk/core

# CDN (Pattern A drop-in)
<script src="https://unpkg.com/ctrlk/dist/ctrlk.runtime.min.js"></script>

Framework-specific packages:

npm install @ctrlk/react       # React hooks + Provider
npm install @ctrlk/angular     # Service + directives
npm install @ctrlk/ag-grid     # AG Grid adapter

Quick Start

30-Second Setup (Pattern A)

<!-- Add before </body>. That's it. -->
<script src="ctrlk.runtime.min.js"></script>

<!-- Result:
  · Ctrl+K opens command palette
  · All buttons auto-discovered as commands
  · Ctrl+D cycles density
  · Every section and link is searchable -->

Programmatic Setup (Pattern B)

import ctrlk from 'ctrlk';

// Initialize with options
ctrlk.init({
  palette: true,          // Enable command palette UI
  density: true,          // Enable density controller
  autoDiscover: true,     // Auto-register DOM elements
  session: true,          // Enable session tracking
  macros: true,           // Enable macro recording
  history: true,          // Enable undo/redo
});

// Register a command
ctrlk.commands.register({
  id: 'filter.active',
  title: 'Show Active Only',
  shortcut: 'Alt+A',
  category: 'Filters',
  icon: '✅',
  execute: () => applyFilter('active'),
});

Integration Patterns

Each pattern extends the previous. Start with A, evolve to C over time. No migration or rewrite needed.

EventBus Core

The internal event system. All modules communicate through this bus. You rarely call it directly, but you can subscribe to any event for custom behavior.

// Listen for any command execution
const unsub = ctrlk.bus.on('command:executed', ({ id }) => {
  console.log(`Command executed: ${id}`);
});

// Later: clean up
unsub();

CommandRegistry Core

The central registry of all commands. Every action in CtrlK is a command — palette entries, shortcuts, macro steps, and history entries all reference commands by ID.

CommandDef Object

Events emitted: command:registered command:executed command:unregistered

ShortcutEngine Core

Scope-aware keyboard shortcut binding. Supports modifier keys, key chords (sequences), and scope-based activation (e.g. a shortcut only active when a grid is focused).

Shortcut Format

'Ctrl+K'           // Single shortcut
'Ctrl+Shift+S'     // Multiple modifiers
'Alt+1'            // Alt + number
'F2'               // Function key
'Ctrl+K Ctrl+S'    // Chord (press Ctrl+K, then Ctrl+S)
'Escape'           // Named key

Events emitted: shortcut:fired shortcut:chord-started

CommandPalette Core

The Ctrl+K searchable command UI. Renders a floating overlay with fuzzy search, keyboard navigation, category grouping, and shortcut display.

Events emitted: palette:opened palette:closed palette:selected

DensityController Core

Controls information density across the application. Cycles between compact, comfortable, and spacious by setting CSS custom properties on the document root.

CSS Custom Properties Set

Events emitted: density:changed

AutoDiscovery Core

Scans the DOM and auto-registers elements as commands. Buttons get their text content as the title, links get their href, sections get navigation commands. This is what makes Pattern A work with zero configuration.

ViewStateManager State

Save, restore, and share complete application view states. A "view" captures grid columns, filters, sort, scroll position, density, and any custom app state. Default limit: 5 saved views with LRU eviction.

Constructor Options

new ViewStateManager(bus, {
  maxViews: 5,   // Default: 5. LRU eviction when exceeded.
});

view:saved Event Payload

{
  name: 'Monday Review',
  slot: 2,                    // Position (1-based)
  shortcut: 'Ctrl+2',          // Assigned shortcut (null if slot > 9)
  totalSaved: 3,               // Current count
  maxViews: 5,                 // Configured max
  remaining: 2,                // Slots available
  evicted: 'Old View',         // Name of evicted view (null if none)
}

Events: view:saved view:loaded view:deleted view:evicted

SelectionModel State

Cross-page persistent selections with named sets and set operations. Selections survive pagination, filtering, and navigation.

Events: selection:changed selection:cleared selection:set-saved

FieldRegistry State

Field-level navigation and tracking for detail pages. Registers form fields for jump-to, dirty tracking, empty navigation, and pinning.

Events: field:focused field:dirty field:pinned

GridAdapter Adapter

Abstract interface that grid-specific adapters implement. This is the contract between CtrlK and any grid library.

MacroEngine Power

Record, parameterize, and replay command sequences. A macro is a named list of commands that can be replayed with a single keystroke.

Events: macro:recording-started macro:recording-stopped macro:played

HistoryManager Power

Application-level undo/redo with branching. Tracks commands that define an undo function and allows reversal.

Events: history:undo history:redo history:pushed

ActiveFilterBar Power

Renders dismissible filter chips showing all active filters. Each chip has a × button to remove that filter.

ColumnNavigator Nav

Column search, bookmarks, and horizontal navigation. The module that solves Problem #1 — finding columns in a 150-column grid.

Default shortcuts: Ctrl+G (search), Ctrl+→ / Ctrl+← (bookmark nav)

FocusNavigator Nav

Spatial zone navigation. Defines zones (toolbar, grid, sidebar, detail panel) and cycles between them with F6.

SessionTracker Nav

Track which records have been visited, reviewed, or marked dirty in a batch workflow. Shows progress (e.g. "12/30 reviewed").

Events: session:visited session:reviewed session:progress

ViewShare New

Shareable application views. Three tiers: URL links (no server), stored team views (app provides storage), and live sharing (Enterprise).

Tier 1 — URL Links (no server)

Tier 2 — Stored Sharing (app provides storage)

Tier 3 — Live Sharing (Enterprise)

Events: share:link-created share:published share:loaded share:broadcast-start

React Integration Framework

Setup

import { CtrlKProvider } from '@ctrlk/react';
import ctrlk from 'ctrlk';

function App() {
  return (
    <CtrlKProvider instance={ctrlk}>
      <YourApp />
    </CtrlKProvider>
  );
}

Available Hooks

import { useCtrlkCommand, useCtrlkView } from '@ctrlk/react';

function DataGrid() {
  // Command auto-registers, auto-unregisters on unmount
  useCtrlkCommand({
    id: 'grid.refresh',
    title: 'Refresh Data',
    shortcut: 'Ctrl+R',
    execute: () => fetchData(),
  }, []);

  // View state survives navigation
  const [filters, setFilters] = useCtrlkView('grid.filters', {});

  return <Grid filters={filters} />;
}

Angular Integration Framework

Setup

import { CtrlkModule } from '@ctrlk/angular';

@NgModule({
  imports: [CtrlkModule.forRoot()],
})

Available Directives

<!-- Register commands from templates -->
<button
  ctrlkCommand="export.csv"
  ctrlkCommandTitle="Export to CSV"
  ctrlkCommandShortcut="Ctrl+Shift+E"
  (click)="exportCsv()">
  Export
</button>

<!-- Register fields for jump-to -->
<input
  ctrlkField="patient.name"
  ctrlkFieldLabel="Patient Name"
  ctrlkFieldSection="Demographics"
  [(ngModel)]="patient.name" />

Vue 3 Integration Framework

import { onMounted, onUnmounted } from 'vue';
import ctrlk from 'ctrlk';

export function useCtrlkCommand(def) {
  let unregister;
  onMounted(() => { unregister = ctrlk.commands.register(def); });
  onUnmounted(() => { unregister?.(); });
}

export function useCtrlkField(fieldId, options) {
  onMounted(() => { ctrlk.fields.register(fieldId, options); });
}

AG Grid Adapter Adapter

import { AgGridAdapter } from '@ctrlk/ag-grid';

gridOptions.onGridReady = (params) => {
  const adapter = new AgGridAdapter(params.api);
  ctrlk.views.setGridAdapter(adapter);
};

API Translation

DevExtreme Adapter Adapter

const grid = new DevExpress.ui.dxDataGrid(el, { ... });

// DevExtreme has a built-in state() method
const adapter = {
  captureState: () => grid.state(),
  restoreState: (s) => grid.state(s),
  setColumnVisible: (f, v) => grid.columnOption(f, 'visible', v),
  ensureColumnVisible: (f) => {
    const idx = grid.getVisibleColumnIndex(f);
    grid.getScrollable()?.scrollToElement(/*...*/);
  },
};
ctrlk.views.setGridAdapter(adapter);

Configuration

ctrlk.init({
  // Feature toggles
  palette: true,            // Enable command palette UI
  density: true,            // Enable density controller
  autoDiscover: true,       // Auto-register DOM elements
  session: true,            // Enable session tracking
  macros: true,             // Enable macro recording
  history: true,            // Enable undo/redo

  // Shortcuts
  paletteShortcut: 'Ctrl+K',
  densityCycleShortcut: 'Ctrl+D',

  // ViewStateManager
  maxViews: 5,              // Max saved views (LRU eviction)
});

Events Reference

Keyboard Shortcuts

Default Shortcuts (configurable)

CtrlK — The first IOUX for enterprise web apps · ctrlk.dev
MIT License · Prabhu Raja