@opentui/keymap 0.0.0-20260423-618ea9b1 → 0.1.106

package/src/types.d.ts

@@ -41,11 +41,44 @@ export interface NormalizedKeyStroke extends KeyStrokeInput {
     meta: boolean;
     super: boolean;
 }
-export type KeyMatch = symbol;
+export type KeyMatch = string;
 export interface EventMatchResolverContext {
     resolveKey(key: KeyLike): KeyMatch;
 }
 export type EventMatchResolver<TEvent extends KeymapEvent = KeymapEvent> = (event: TEvent, ctx: EventMatchResolverContext) => readonly KeyMatch[] | undefined;
+export declare const KEY_DISAMBIGUATION_DECISION: unique symbol;
+export declare const KEY_DEFERRED_DISAMBIGUATION_DECISION: unique symbol;
+export interface KeyDisambiguationDecision {
+    readonly [KEY_DISAMBIGUATION_DECISION]: true;
+}
+export interface KeyDeferredDisambiguationDecision {
+    readonly [KEY_DEFERRED_DISAMBIGUATION_DECISION]: true;
+}
+export interface KeyDisambiguationContext<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
+    readonly event: Readonly<Omit<TEvent, "preventDefault" | "stopPropagation">>;
+    readonly focused: TTarget | null;
+    readonly sequence: readonly KeySequencePart[];
+    readonly stroke: KeySequencePart;
+    readonly exact: readonly ActiveBinding<TTarget, TEvent>[];
+    readonly continuations: readonly ActiveKey<TTarget, TEvent>[];
+    getData(name: string): unknown;
+    setData(name: string, value: unknown): void;
+    runExact(): KeyDisambiguationDecision;
+    continueSequence(): KeyDisambiguationDecision;
+    clear(): KeyDisambiguationDecision;
+    defer(run: KeyDeferredDisambiguationHandler<TTarget, TEvent>): KeyDisambiguationDecision;
+}
+export interface KeyDeferredDisambiguationContext<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
+    readonly signal: AbortSignal;
+    readonly sequence: readonly KeySequencePart[];
+    readonly focused: TTarget | null;
+    sleep(ms: number): Promise<boolean>;
+    runExact(): KeyDeferredDisambiguationDecision;
+    continueSequence(): KeyDeferredDisambiguationDecision;
+    clear(): KeyDeferredDisambiguationDecision;
+}
+export type KeyDeferredDisambiguationHandler<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = (ctx: KeyDeferredDisambiguationContext<TTarget, TEvent>) => KeyDeferredDisambiguationDecision | void | Promise<KeyDeferredDisambiguationDecision | void>;
+export type KeyDisambiguationResolver<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = (ctx: KeyDisambiguationContext<TTarget, TEvent>) => KeyDisambiguationDecision | undefined;
 export interface ResolvedKeyToken {
     stroke: NormalizedKeyStroke;
     match: KeyMatch;
@@ -97,7 +130,7 @@ export type RunCommandResult = {
     reason: "not-found";
 } | {
     ok: false;
-    reason: "invalid-args" | "rejected" | "error";
+    reason: "inactive" | "disabled" | "invalid-args" | "rejected" | "error";
     command?: CommandRecord;
 };
 export interface CommandContext<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
@@ -136,27 +169,34 @@ export interface BindingInput<TTarget extends object = object, TEvent extends Ke
 }
 export type BindingShorthand<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = Record<string, BindingCommand<TTarget, TEvent>>;
 export type Bindings<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = BindingInput<TTarget, TEvent>[] | BindingShorthand<TTarget, TEvent>;
-export type Scope = "global" | "focus" | "focus-within";
+export type TargetMode = "focus" | "focus-within";
 export interface LayerFields<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
     priority?: number;
     bindings?: Bindings<TTarget, TEvent>;
     commands?: readonly CommandDefinition<TTarget, TEvent>[];
+    targetMode?: TargetMode;
+    /**
+     * Extra layer fields feed layer-field compilers and binding compilation via
+     * `BindingParserContext.layer` / `BindingTransformerContext.layer`. Unlike
+     * binding and command fields, layer fields do not compile into public attrs.
+     */
     [key: string]: unknown;
 }
+export interface Layer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> extends LayerFields<TTarget, TEvent> {
+    target?: TTarget;
+}
 export interface GlobalLayer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> extends LayerFields<TTarget, TEvent> {
     target?: undefined;
-    scope?: "global";
 }
 export interface FocusWithinLayer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> extends LayerFields<TTarget, TEvent> {
     target: TTarget;
-    scope?: "focus-within";
+    targetMode?: TargetMode;
 }
 export interface FocusLayer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> extends LayerFields<TTarget, TEvent> {
     target: TTarget;
-    scope: "focus";
+    targetMode?: TargetMode;
 }
 export type TargetLayer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = FocusWithinLayer<TTarget, TEvent> | FocusLayer<TTarget, TEvent>;
-export type Layer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = GlobalLayer<TTarget, TEvent> | TargetLayer<TTarget, TEvent>;
 export interface ParsedCommand {
     input: string;
     name: string;
@@ -245,6 +285,10 @@ export type BindingFieldCompiler = (value: unknown, ctx: BindingFieldContext) =>
 export interface LayerFieldContext {
     require(name: string, value: unknown): void;
     /**
+     * Layer fields only influence activation and binding compilation. They do
+     * not expose `attr(...)` because the current model has no layer-level attrs
+     * surface on `ActiveKey`, `ActiveBinding`, or `CommandRecord`.
+     *
      * Registers a runtime matcher. Raw callbacks re-run on every read;
      * reactive matchers stay cached until they notify.
      */
@@ -252,7 +296,6 @@ export interface LayerFieldContext {
 }
 export type LayerFieldCompiler = (value: unknown, ctx: LayerFieldContext) => void;
 export interface LayerAnalysisContext<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
-    scope: Scope;
     target?: TTarget;
     order: number;
     bindingInputs: readonly BindingInput<TTarget, TEvent>[];
@@ -271,7 +314,6 @@ export interface LayerBindingAnalysis<TTarget extends object = object, TEvent ex
     preventDefault: boolean;
     fallthrough: boolean;
     sourceBinding: ParsedBindingInput<TTarget, TEvent>;
-    sourceScope: Scope;
     sourceTarget?: TTarget;
     sourceLayerOrder: number;
     sourceBindingIndex: number;
@@ -386,11 +428,6 @@ export interface RawInterceptOptions {
     priority?: number;
 }
 export type { Keymap };
-export type KeymapActiveKey<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = ActiveKey<TTarget, TEvent>;
-export type KeymapBindingInput<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = BindingInput<TTarget, TEvent>;
-export type KeymapCommandDefinition<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = CommandDefinition<TTarget, TEvent>;
-export type KeymapCommandRecord = CommandRecord;
-export type KeymapCommandEntry<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> = CommandEntry<TTarget, TEvent>;
 export interface RuntimeMatcher {
     source: string;
     match: () => boolean;
@@ -419,7 +456,6 @@ export interface RuntimeMatchable {
 export interface CompiledBinding<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> extends ActiveBinding<TTarget, TEvent>, RuntimeMatchable {
     run?: CommandHandler<TTarget, TEvent>;
     sourceBinding: ParsedBindingInput<TTarget, TEvent>;
-    sourceScope: Scope;
     sourceTarget?: TTarget;
     sourceLayerOrder: number;
     sourceBindingIndex: number;
@@ -466,8 +502,7 @@ export interface SequenceNode<TTarget extends object = object, TEvent extends Ke
 export interface RegisteredLayer<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
     order: number;
     target?: TTarget;
-    indexTarget: TTarget;
-    scope: Scope;
+    targetMode?: TargetMode;
     priority: number;
     requires: readonly [name: string, value: unknown][];
     matchers: readonly RuntimeMatcher[];
@@ -485,11 +520,6 @@ export interface RegisteredLayer<TTarget extends object = object, TEvent extends
     hasTokenBindings: boolean;
     root: SequenceNode<TTarget, TEvent>;
     offTargetDestroy?: () => void;
-    bucket?: RegisteredLayerBucket<TTarget, TEvent>;
-}
-export interface RegisteredLayerBucket<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
-    focusLayers: RegisteredLayer<TTarget, TEvent>[];
-    focusWithinLayers: RegisteredLayer<TTarget, TEvent>[];
 }
 export interface PendingSequenceCapture<TTarget extends object = object, TEvent extends KeymapEvent = KeymapEvent> {
     layer: RegisteredLayer<TTarget, TEvent>;

package/src/keymap-benchmark.d.ts

@@ -1 +0,0 @@
-export {};