cjm-fasthtml-token-selector 0.0.1__py3-none-any.whl

cjm_fasthtml_token_selector/js/repeat.py

@@ -0,0 +1,119 @@
+"""Custom key repeat engine with configurable initial delay, repeat interval, and throttle floor."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/js/repeat.ipynb.
+
+# %% auto #0
+__all__ = ['generate_key_repeat_js']
+
+# %% ../../nbs/js/repeat.ipynb #684c3b7a
+from ..core.config import TokenSelectorConfig
+
+# %% ../../nbs/js/repeat.ipynb #b02029c9
+def _generate_movement_dispatch_js(
+    config:TokenSelectorConfig,  # config for this instance
+) -> str:  # JS code fragment for the movement dispatcher
+    """Generate the key-to-movement dispatch logic."""
+    left_key = config.left_key
+    right_key = config.right_key
+    mode = config.selection_mode
+
+    # Base movement for unmodified keys
+    base_dispatch = f"""
+        if (key === '{left_key}') return ns.moveLeft;
+        if (key === '{right_key}') return ns.moveRight;
+"""
+
+    # Shift-modified keys for span extend
+    if mode == "span":
+        shift_dispatch = f"""
+        if (key === '{left_key}') return ns.extendLeft;
+        if (key === '{right_key}') return ns.extendRight;
+"""
+    else:
+        shift_dispatch = """
+        return null;
+"""
+
+    return f"""
+    ns._getMovementFn = function(key, shiftKey) {{
+        if (shiftKey) {{{shift_dispatch}
+        }}
+        {base_dispatch}
+        return null;
+    }};
+"""
+
+# %% ../../nbs/js/repeat.ipynb #0122283a
+def generate_key_repeat_js(
+    config:TokenSelectorConfig,  # config with timing settings
+) -> str:  # JS code fragment for the IIFE
+    """Generate the custom key repeat engine JS."""
+    initial_delay = config.initial_delay
+    repeat_interval = config.repeat_interval
+    throttle_floor = config.throttle_floor
+
+    dispatch = _generate_movement_dispatch_js(config)
+
+    return dispatch + f"""
+    // Key repeat engine state
+    ns._repeatTimer = null;
+    ns._repeatKey = null;
+    ns._repeatShift = false;
+    ns._lastMoveTime = 0;
+
+    ns._handleKeyDown = function(e) {{
+        if (!ns.active) return;
+
+        var moveFn = ns._getMovementFn(e.key, e.shiftKey);
+        if (!moveFn) return;
+
+        e.preventDefault();
+        e.stopPropagation();
+
+        // If same key already held, let the timer run
+        if (ns._repeatKey === e.key && ns._repeatShift === e.shiftKey) return;
+
+        // Cancel any existing repeat
+        if (ns._repeatTimer) {{
+            clearTimeout(ns._repeatTimer);
+            ns._repeatTimer = null;
+        }}
+
+        ns._repeatKey = e.key;
+        ns._repeatShift = e.shiftKey;
+
+        // Immediate first movement
+        var now = Date.now();
+        if (now - ns._lastMoveTime >= {throttle_floor}) {{
+            moveFn();
+            ns._lastMoveTime = now;
+        }}
+
+        // Start repeat after initial delay, then switch to interval
+        ns._repeatTimer = setTimeout(function repeatTick() {{
+            var fn = ns._getMovementFn(ns._repeatKey, ns._repeatShift);
+            if (!fn || !ns.active) {{
+                ns._repeatKey = null;
+                ns._repeatShift = false;
+                return;
+            }}
+            var tickNow = Date.now();
+            if (tickNow - ns._lastMoveTime >= {throttle_floor}) {{
+                fn();
+                ns._lastMoveTime = tickNow;
+            }}
+            ns._repeatTimer = setTimeout(repeatTick, {repeat_interval});
+        }}, {initial_delay});
+    }};
+
+    ns._handleKeyUp = function(e) {{
+        if (e.key === ns._repeatKey) {{
+            if (ns._repeatTimer) {{
+                clearTimeout(ns._repeatTimer);
+                ns._repeatTimer = null;
+            }}
+            ns._repeatKey = null;
+            ns._repeatShift = false;
+        }}
+    }};
+"""

cjm_fasthtml_token_selector/keyboard/actions.py

@@ -0,0 +1,157 @@
+"""Keyboard navigation library integration factories for token selector mode, actions, URL maps, and hidden action buttons."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/keyboard/actions.ipynb.
+
+# %% auto #0
+__all__ = ['create_token_selector_mode', 'create_token_nav_actions', 'build_token_selector_url_map',
+           'render_token_action_buttons']
+
+# %% ../../nbs/keyboard/actions.ipynb #9cae2c4c
+from typing import Any, Dict, Tuple
+
+from fasthtml.common import Div, Button, Hidden
+
+from cjm_fasthtml_tailwind.utilities.layout import display_tw
+
+from cjm_fasthtml_keyboard_navigation.core.actions import KeyAction
+from cjm_fasthtml_keyboard_navigation.core.modes import KeyboardMode
+
+from ..core.config import TokenSelectorConfig
+from ..core.html_ids import TokenSelectorHtmlIds
+from ..js.core import global_callback_name
+
+# %% ../../nbs/keyboard/actions.ipynb #a1223d9d
+def create_token_selector_mode(
+    config:TokenSelectorConfig,         # config for this instance
+    mode_name:str = "token-select",     # mode name for the keyboard nav system
+    indicator_text:str = "Token Select", # mode indicator text
+    exit_key:str = "",                  # exit key (empty = programmatic only via Escape KeyAction)
+    exit_on_zone_change:bool = False,   # whether to exit on zone change
+) -> KeyboardMode:  # configured keyboard mode
+    """Create a keyboard mode that activates/deactivates the token selector."""
+    return KeyboardMode(
+        name=mode_name,
+        on_enter=global_callback_name(config.prefix, "activate"),
+        on_exit=global_callback_name(config.prefix, "deactivate"),
+        indicator_text=indicator_text,
+        exit_key=exit_key,
+        exit_on_zone_change=exit_on_zone_change,
+    )
+
+# %% ../../nbs/keyboard/actions.ipynb #464fca0c
+def create_token_nav_actions(
+    config:TokenSelectorConfig,           # config for this instance
+    zone_id:str,                          # focus zone ID
+    mode_name:str = "token-select",       # mode name (must match the mode)
+    confirm_button_id:str = "",           # HTMX button ID for confirm action
+    cancel_button_id:str = "",            # HTMX button ID for cancel action
+) -> Tuple[KeyAction, ...]:  # non-movement keyboard actions
+    """Create keyboard actions for the token selector."""
+    actions = []
+    mode_scope = (mode_name,)
+
+    # Confirm: Enter
+    if confirm_button_id:
+        actions.append(KeyAction(
+            key="Enter",
+            htmx_trigger=confirm_button_id,
+            mode_names=mode_scope,
+            mode_exit=True,
+            description="Confirm selection",
+            hint_group="Token Select",
+            zone_ids=(zone_id,),
+        ))
+        # Space as alias (hidden from hints)
+        actions.append(KeyAction(
+            key=" ",
+            htmx_trigger=confirm_button_id,
+            mode_names=mode_scope,
+            mode_exit=True,
+            description="Confirm selection",
+            hint_group="Token Select",
+            show_in_hints=False,
+            zone_ids=(zone_id,),
+        ))
+
+    # Cancel: Escape
+    if cancel_button_id:
+        actions.append(KeyAction(
+            key="Escape",
+            htmx_trigger=cancel_button_id,
+            mode_names=mode_scope,
+            mode_exit=True,
+            description="Cancel",
+            hint_group="Token Select",
+            zone_ids=(zone_id,),
+        ))
+
+    # Home: move to first position
+    actions.append(KeyAction(
+        key="Home",
+        js_callback=global_callback_name(config.prefix, "moveToFirst"),
+        mode_names=mode_scope,
+        description="Go to start",
+        hint_group="Token Select",
+        zone_ids=(zone_id,),
+    ))
+
+    # End: move to last position
+    actions.append(KeyAction(
+        key="End",
+        js_callback=global_callback_name(config.prefix, "moveToLast"),
+        mode_names=mode_scope,
+        description="Go to end",
+        hint_group="Token Select",
+        zone_ids=(zone_id,),
+    ))
+
+    return tuple(actions)
+
+# %% ../../nbs/keyboard/actions.ipynb #8b6a950a
+def build_token_selector_url_map(
+    confirm_button_id:str,  # button ID for confirm action
+    cancel_button_id:str,   # button ID for cancel action
+    confirm_url:str,        # URL for confirm action
+    cancel_url:str,         # URL for cancel action
+) -> Dict[str, str]:  # button ID -> URL mapping
+    """Build URL map for keyboard system with token selector action buttons."""
+    url_map = {}
+    if confirm_button_id and confirm_url:
+        url_map[confirm_button_id] = confirm_url
+    if cancel_button_id and cancel_url:
+        url_map[cancel_button_id] = cancel_url
+    return url_map
+
+# %% ../../nbs/keyboard/actions.ipynb #039e1b6e
+def render_token_action_buttons(
+    confirm_button_id:str,          # button ID for confirm
+    cancel_button_id:str,           # button ID for cancel
+    confirm_url:str,                # URL for confirm action
+    cancel_url:str,                 # URL for cancel action
+    ids:TokenSelectorHtmlIds,       # HTML IDs (for hx_include)
+    extra_include:str = "",         # additional hx_include selectors
+) -> Any:  # Div containing hidden action buttons
+    """Render hidden HTMX buttons for confirm/cancel actions."""
+    include = f"#{ids.anchor_input}, #{ids.focus_input}"
+    if extra_include:
+        include = f"{include}, {extra_include}"
+
+    buttons = []
+    if confirm_button_id and confirm_url:
+        buttons.append(Button(
+            id=confirm_button_id,
+            hx_post=confirm_url,
+            hx_swap="none",
+            hx_include=include,
+            cls=str(display_tw.hidden),
+        ))
+    if cancel_button_id and cancel_url:
+        buttons.append(Button(
+            id=cancel_button_id,
+            hx_post=cancel_url,
+            hx_swap="none",
+            hx_include=include,
+            cls=str(display_tw.hidden),
+        ))
+
+    return Div(*buttons, cls=str(display_tw.hidden))