rewrite keymap system, introduce transient-like functionality by mahmoodsh36 · Pull Request #2100 · lem-project/lem

mahmoodsh36 · 2026-01-14T22:38:28Z

this is very preliminary work. this is an opinionated rewrite of the keymap system that i think makes more sense and is more intuitive.
yet to be handled/written/re-written:

undefine-key
priorities (some stuff is broken)
proper transient-like functionality with proper grid displays and self-documenting keybindings
the keymap system now allows for "dynamic" (non-static) keys or keymaps to be bound on-demand. unlike the old implementation which had nested pre-defined hashmaps, the new implementation uses a different data structure but tries to maintain backwards compatibility with the old implementation (atleast for now).
i will be following this PR with more work and documentation/explanations. the goal was to rewrite the keymap system so that things like transient or which-key are a natural consequence of the data structure and are more intertwined with the core (unlike in emacs).

mahmoodsh36 · 2026-01-18T19:29:25Z

an initial preview of the popup thingy. the double instances of unnamed keymap thing is intentional since its displaying nested keymaps.

mahmoodsh36 · 2026-01-18T19:30:03Z

there are still things to be done such as:

implement "sticky" keys such as infixes
fix keymap priorities/precedence
implement undefine-key
some key sequences should be considered as a single prefix, such as keys "-g" that resemble commandline arguments and are composed of 2 keys not only one. this is currently not possible because a popup only displays single keys and doesnt recurse to display the longer key sequence which is the intended design, but maybe we should also allow for some sub-keymaps to be recursed into and longer key sequences to be displayed.
functionality isnt yet customizable beside the CLOS interface. more customization variables should be introduced that customize behavior.

mahmoodsh36 · 2026-01-18T20:09:56Z

i need to stop the habit of force pushing, lol

mahmoodsh36 · 2026-01-24T15:58:17Z

i introduced the following "suffix" values for now:

:cancel to drop the current key sequence entirely without invoking a command
:drop to avoid adding the current key to the key sequence, which makes the prefix act as an "infix" key
:back to avoid adding the current key and to pop the last recorded key which has the effect of "going back" to parent menu in the transient popup.

this behavior is customized by setting the value of the suffix to one of those (or to a symbol that is resolved later to a command that is executed). i dont think this belongs in the suffix slot, i think it would be more ideal for a suffix to always resolve to a command, but currently the function 'read-command' which is part of the event/key handler can only resolve a specific key sequence to a single command. currently the behavior of an infix (such as 'choice') is customized by overriding 'prefix-invoke' but this functionality i think belongs in the suffix itself. i have yet to think of a redesign to make this more intuitive.

i think the suffix itself shouldnt necessarily hold the special value that decides the behaviors cancel/drop/back, i think that belongs in a different defmethod (call it prefix-behavior) so that a prefix can both resolve to a command and have custom behavior.

…plicit function suffixes

before this, after typing / and trying to search, the following keys would be interpreted as if they were entered in normal mode instead, and searching functionality was broken. this is more of a bandaid than a fix, i need to rewrite the whole 'undef-hook' thing which i think is annoying and unintuitive

mahmoodsh36 · 2026-01-30T19:59:25Z

there are still things to be done such as:

implement "sticky" keys such as infixes

fix keymap priorities/precedence

implement undefine-key

some key sequences should be considered as a single prefix, such as keys "-g" that resemble commandline arguments and are composed of 2 keys not only one. this is currently not possible because a popup only displays single keys and doesnt recurse to display the longer key sequence which is the intended design, but maybe we should also allow for some sub-keymaps to be recursed into and longer key sequences to be displayed.

functionality isnt yet customizable beside the CLOS interface. more customization variables should be introduced that customize behavior.

first 3 are done.

code-contractor-app

Code Contractor validation failed ❌ — see the sticky comment for full results.

code-contractor-app · 2026-03-14T22:05:27Z

@@ -0,0 +1,77 @@
+(in-package :lem/transient)


Code Contractor: defpackage_rule

Contract: contract

AI check failed: "defpackage_rule"

Reason:
New files use IN-PACKAGE or other first forms instead of a top-level DEFPACKAGE or UIOP:DEFINE-PACKAGE as required.

code-contractor-app · 2026-03-14T22:05:27Z

+    (cond
+      ((keymap-show-p keymap)
+       (show-transient keymap))
+      ((loop for mode in active-modes


Code Contractor: loop_keywords_rule

Contract: contract

AI check failed: "loop_keywords_rule"

Reason:
Added code uses LOOP with unprefixed keywords (e.g. "for", "in", "do") instead of colon-prefixed keywords (e.g. ":for", ":in", ":do").

code-contractor-app · 2026-03-14T22:05:27Z

+    :initarg :suffix
+    :documentation "the suffix defined for the prefix, could be another prefix or a keymap or a function that returns one.")
+   (active-p
+    :initarg :active-p


Code Contractor: docstring_rule

Contract: contract

AI check failed: "docstring_rule"

Reason:
The diff adds exported symbols (classes, generics, and commands) without the required docstrings/documentation. Examples: exported generics lack a :documentation option, exported classes lack class docstrings, and an exported define-command (demo-run) is defined without a docstring. These violate the rule requiring docstrings for exported functions, methods, classes and that generic functions include a :documentation option.

code-contractor-app · 2026-03-14T22:05:27Z

 (define-key *copilot-completion-keymap* "Tab" 'copilot-accept-suggestion)
 (define-key *copilot-completion-keymap* 'copilot-next-suggestion 'copilot-next-suggestion)
 (define-key *copilot-completion-keymap* 'copilot-previous-suggestion 'copilot-previous-suggestion)



Code Contractor: internal_symbol_rule

Contract: contract

AI check failed: "internal_symbol_rule"

Reason:
Added code contains direct references to internal (non-exported) symbols via package double-colon qualifiers (e.g. lem-core::other-keymaps), which violates the rule to use exported symbols from lem or lem-core and avoid internal symbol access.

code-contractor-app · 2026-03-14T22:05:27Z

@@ -0,0 +1,531 @@
+(in-package :lem/transient)
+
+(defvar *transient-popup-window*


Code Contractor: functional_style_rule

Contract: contract

AI check failed: "functional_style_rule"

Reason:
The diff adds multiple top-level dynamic state variables with defvar that appear to be used as shared state across functions, which violates the rule to avoid using defvar for state passed between functions (prefer explicit function arguments).

handling of undef-hook wasnt right which caused C-n/C-p not to work for prompt completion. undef-hook is a leftover from previous keymap code and i should think of a way to rewrite its functionality that is more ideal.

mahmoodsh36 · 2026-04-02T14:11:20Z

rebased on main, tho there wasnt really a necessary reason to

vindarel · 2026-04-04T11:38:28Z

The PR being ready is great news.

IIRC you said the breaking changes are minimal, mostly name changes.

deprecation warnings instead hard renames/rewrites would be nice too.

that would be nice.

Also we kinda need a document that explains what are these hard renames.

Aaaaand

we kinda need a README for the transient system. I see there's a demo.lisp, but we need some english text with a presentation and simple examples (and screenshots). Can you do this?

I want to try everything,

and we'll ping cxxxr for review.

vindarel · 2026-04-04T11:52:03Z

+                   (when (or (typep suffix 'keymap)
+                             (typep suffix 'prefix))
+                     (f suffix)))))
+           (f (node)


I'd avoid single-letters function names.

vindarel · 2026-04-04T11:53:24Z

+                      (when (or (typep suffix 'keymap)
+                                (typep suffix 'prefix))
+                        (f suffix)))))))
+    (f keymap)))


there are no more labels so was it necessary??

vindarel · 2026-04-04T11:56:31Z

+                 (funcall (fdefinition (list 'setf property-method)) props object))))))))
+
+(defun parse-transient (bindings)
+  "defines a transient menu. args yet to be documented."


documentation (at least first parts) welcome.

mahmoodsh36 · 2026-04-11T22:07:38Z

notable renames

*keymaps* is no longer relevant. we use *root-keymap* which maintains the full structure at any point in time.
keymap's :parent arg became :base, so make-keymap and make-vi-keymap now take :base instead of :parent.
keymap's :name arg became :description, so make-keymap and make-vi-keymap now take :description instead of :name. and keymap-name is now keymap-description.
keymap-find-keybind was renamed to keymap-find (and modified).
other-keymaps now serves a similar job to what all-keymaps did before the changes (but very different). maybe i should reconsider the rename, but the issue is that it doesnt really collect 'all' keymaps.

defining keys remains the same, but the internal code in keymap.lisp and input.lisp was heavily modified. the diff shows many edited files but most just correspond to renames.

it would be easy to maintain backwards compatibility for things like the :name and :parent renames. the rest, not so much.

vindarel · 2026-04-21T10:51:39Z

Thank you for the readme and the small updates.

This PR looks good to me.

Let's have a couple more testers?!

vindarel · 2026-04-24T12:11:00Z

Merged 🥳 🚀

Thank you to the testers,

hats off to @mahmoodsh36 for this work.

vindarel · 2026-04-24T13:58:06Z

https://github.com/lem-project/lem/blob/main/extensions/transient/readme.org

https://lem-project.github.io/usage/transient/

mahmoodsh36 added 3 commits January 14, 2026 19:53

rewrite keymap system

06ca1cc

introduce keymap-activate and initialize transient.lisp

3793971

add simple popup

c588bed

make popup more informative

c27b19c

mahmoodsh36 force-pushed the transient branch from d980ec3 to e3f6d6a Compare January 18, 2026 19:36

improve docstrings a little more

78f4796

mahmoodsh36 added 6 commits January 18, 2026 22:12

slight refactor

155b527

make multi-choice prefix work

bdba683

fix order of keymaps (hence fix priorities)

ad9ce93

slight change

43112dc

add find-prefix-by-id

ce57101

introduce :back, :cancel suffix values

aad05cb

mahmoodsh36 added 9 commits January 25, 2026 23:10

rename package to lem/transient

d42842a

rename package to lem/transient

df5d8e4

rename package to lem/transient and system to lem-transient

aa42f22

use "intern" with explicit package name

ca27e2e

introduce prefix-behavior, with-last-read-key-sequence, and handle ex…

9fe484f

…plicit function suffixes

use :description instead of :name for keymaps

3d5d820

introduce toggle infix, use prompt for multi-choice infix

674b205

fix undefine-key (actually undefine-key-internal)

60149a5

remvoe some redundant stuff

f1c9db1

mahmoodsh36 force-pushed the transient branch from 9d5f5ec to 30d4ea5 Compare January 30, 2026 20:57

mahmoodsh36 added 2 commits January 30, 2026 23:41

properly parse keymap keywords in transient, change title styling

6e39a90

small fix

ec7418e

code-contractor-app Bot suggested changes Mar 14, 2026

View reviewed changes

mahmoodsh36 added 6 commits March 18, 2026 00:18

use defvar instead of defparameter to avoid issues on recomp

06bdc4a

fix handling of undef-hook

dce4e71

handling of undef-hook wasnt right which caused C-n/C-p not to work for prompt completion. undef-hook is a leftover from previous keymap code and i should think of a way to rewrite its functionality that is more ideal.

set popup max-lines to 10 instead of 15 by default

95d0dae

fix undef-hook/function-table edge case

b595931

fix popup behavior when switching buffers

5eb74c7

remove outdated comment

a237414

mahmoodsh36 force-pushed the transient branch from 9abe4ff to 74cc94b Compare April 2, 2026 14:10

mahmoodsh36 force-pushed the transient branch from 74cc94b to bbdebef Compare April 2, 2026 14:14

mahmoodsh36 added 2 commits April 2, 2026 19:37

fix outdated argument name (:name to :description)

7abc872

rename define-transient-key, add macro for it.

9123268

vindarel reviewed Apr 4, 2026

View reviewed changes

mahmoodsh36 added 2 commits April 9, 2026 16:06

add some documentation/examples

2f73fb3

small change in docs, small fix

a2cb07e

mahmoodsh36 added 2 commits April 12, 2026 01:21

reduce single-char namings of bindings/functions

797f6fa

some docstrings

6526f3c

mahmoodsh36 force-pushed the transient branch 2 times, most recently from ee24264 to 6526f3c Compare April 18, 2026 12:55

mahmoodsh36 added 2 commits April 23, 2026 22:31

fix always-show behavior

3b3ac5f

fix edge case in scrolling keys behavior

2c2ce88

vindarel merged commit 6d9bea0 into lem-project:main Apr 24, 2026
10 checks passed

mahmoodsh36 mentioned this pull request Apr 24, 2026

add vi-mode insert-state-related tests #2146

Merged

		@@ -0,0 +1,531 @@
		(in-package :lem/transient)

		(defvar transient-popup-window

Uh oh!

Conversation

mahmoodsh36 commented Jan 14, 2026

Uh oh!

mahmoodsh36 commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mahmoodsh36 commented Jan 18, 2026

Uh oh!

mahmoodsh36 commented Jan 18, 2026

Uh oh!

mahmoodsh36 commented Jan 24, 2026

Uh oh!

mahmoodsh36 commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

code-contractor-app Bot left a comment

Choose a reason for hiding this comment

Uh oh!

code-contractor-app Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

code-contractor-app Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

code-contractor-app Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

code-contractor-app Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

code-contractor-app Bot Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

mahmoodsh36 commented Apr 2, 2026

Uh oh!

vindarel commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vindarel Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

vindarel Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

vindarel Apr 4, 2026

Choose a reason for hiding this comment

Uh oh!

mahmoodsh36 commented Apr 11, 2026

Uh oh!

vindarel commented Apr 21, 2026

Uh oh!

Uh oh!

vindarel commented Apr 24, 2026

Uh oh!

vindarel commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mahmoodsh36 commented Jan 18, 2026 •

edited

Loading

mahmoodsh36 commented Jan 30, 2026 •

edited

Loading

vindarel commented Apr 4, 2026 •

edited

Loading