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

cjm_fasthtml_token_selector/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

cjm_fasthtml_token_selector/_modidx.py

@@ -0,0 +1,104 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/cjm-fasthtml-token-selector',
+                'doc_host': 'https://cj-mills.github.io',
+                'git_url': 'https://github.com/cj-mills/cjm-fasthtml-token-selector',
+                'lib_path': 'cjm_fasthtml_token_selector'},
+  'syms': { 'cjm_fasthtml_token_selector.components.inputs': { 'cjm_fasthtml_token_selector.components.inputs.build_include_selector': ( 'components/inputs.html#build_include_selector',
+                                                                                                                                         'cjm_fasthtml_token_selector/components/inputs.py'),
+                                                               'cjm_fasthtml_token_selector.components.inputs.render_hidden_inputs': ( 'components/inputs.html#render_hidden_inputs',
+                                                                                                                                       'cjm_fasthtml_token_selector/components/inputs.py')},
+            'cjm_fasthtml_token_selector.components.tokens': { 'cjm_fasthtml_token_selector.components.tokens._build_token_render_context': ( 'components/tokens.html#_build_token_render_context',
+                                                                                                                                              'cjm_fasthtml_token_selector/components/tokens.py'),
+                                                               'cjm_fasthtml_token_selector.components.tokens._is_token_selected': ( 'components/tokens.html#_is_token_selected',
+                                                                                                                                     'cjm_fasthtml_token_selector/components/tokens.py'),
+                                                               'cjm_fasthtml_token_selector.components.tokens._render_caret_indicator': ( 'components/tokens.html#_render_caret_indicator',
+                                                                                                                                          'cjm_fasthtml_token_selector/components/tokens.py'),
+                                                               'cjm_fasthtml_token_selector.components.tokens.render_end_token': ( 'components/tokens.html#render_end_token',
+                                                                                                                                   'cjm_fasthtml_token_selector/components/tokens.py'),
+                                                               'cjm_fasthtml_token_selector.components.tokens.render_token': ( 'components/tokens.html#render_token',
+                                                                                                                               'cjm_fasthtml_token_selector/components/tokens.py'),
+                                                               'cjm_fasthtml_token_selector.components.tokens.render_token_grid': ( 'components/tokens.html#render_token_grid',
+                                                                                                                                    'cjm_fasthtml_token_selector/components/tokens.py')},
+            'cjm_fasthtml_token_selector.core.config': { 'cjm_fasthtml_token_selector.core.config.TokenSelectorConfig': ( 'core/config.html#tokenselectorconfig',
+                                                                                                                          'cjm_fasthtml_token_selector/core/config.py'),
+                                                         'cjm_fasthtml_token_selector.core.config._auto_prefix': ( 'core/config.html#_auto_prefix',
+                                                                                                                   'cjm_fasthtml_token_selector/core/config.py'),
+                                                         'cjm_fasthtml_token_selector.core.config._reset_prefix_counter': ( 'core/config.html#_reset_prefix_counter',
+                                                                                                                            'cjm_fasthtml_token_selector/core/config.py')},
+            'cjm_fasthtml_token_selector.core.constants': {},
+            'cjm_fasthtml_token_selector.core.html_ids': { 'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds': ( 'core/html_ids.html#tokenselectorhtmlids',
+                                                                                                                               'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.anchor_input': ( 'core/html_ids.html#tokenselectorhtmlids.anchor_input',
+                                                                                                                                            'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.anchor_name': ( 'core/html_ids.html#tokenselectorhtmlids.anchor_name',
+                                                                                                                                           'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.container': ( 'core/html_ids.html#tokenselectorhtmlids.container',
+                                                                                                                                         'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.focus_input': ( 'core/html_ids.html#tokenselectorhtmlids.focus_input',
+                                                                                                                                           'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.focus_name': ( 'core/html_ids.html#tokenselectorhtmlids.focus_name',
+                                                                                                                                          'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.token': ( 'core/html_ids.html#tokenselectorhtmlids.token',
+                                                                                                                                     'cjm_fasthtml_token_selector/core/html_ids.py'),
+                                                           'cjm_fasthtml_token_selector.core.html_ids.TokenSelectorHtmlIds.token_grid': ( 'core/html_ids.html#tokenselectorhtmlids.token_grid',
+                                                                                                                                          'cjm_fasthtml_token_selector/core/html_ids.py')},
+            'cjm_fasthtml_token_selector.core.models': { 'cjm_fasthtml_token_selector.core.models.Token': ( 'core/models.html#token',
+                                                                                                            'cjm_fasthtml_token_selector/core/models.py'),
+                                                         'cjm_fasthtml_token_selector.core.models.TokenRenderContext': ( 'core/models.html#tokenrendercontext',
+                                                                                                                         'cjm_fasthtml_token_selector/core/models.py'),
+                                                         'cjm_fasthtml_token_selector.core.models.TokenSelectorState': ( 'core/models.html#tokenselectorstate',
+                                                                                                                         'cjm_fasthtml_token_selector/core/models.py')},
+            'cjm_fasthtml_token_selector.helpers.tokenizer': { 'cjm_fasthtml_token_selector.helpers.tokenizer.count_tokens': ( 'helpers/tokenizer.html#count_tokens',
+                                                                                                                               'cjm_fasthtml_token_selector/helpers/tokenizer.py'),
+                                                               'cjm_fasthtml_token_selector.helpers.tokenizer.get_token_list': ( 'helpers/tokenizer.html#get_token_list',
+                                                                                                                                 'cjm_fasthtml_token_selector/helpers/tokenizer.py'),
+                                                               'cjm_fasthtml_token_selector.helpers.tokenizer.token_index_to_char_position': ( 'helpers/tokenizer.html#token_index_to_char_position',
+                                                                                                                                               'cjm_fasthtml_token_selector/helpers/tokenizer.py'),
+                                                               'cjm_fasthtml_token_selector.helpers.tokenizer.tokenize': ( 'helpers/tokenizer.html#tokenize',
+                                                                                                                           'cjm_fasthtml_token_selector/helpers/tokenizer.py')},
+            'cjm_fasthtml_token_selector.js.core': { 'cjm_fasthtml_token_selector.js.core._generate_activation_js': ( 'js/core.html#_generate_activation_js',
+                                                                                                                      'cjm_fasthtml_token_selector/js/core.py'),
+                                                     'cjm_fasthtml_token_selector.js.core._generate_global_callbacks_js': ( 'js/core.html#_generate_global_callbacks_js',
+                                                                                                                            'cjm_fasthtml_token_selector/js/core.py'),
+                                                     'cjm_fasthtml_token_selector.js.core._generate_on_change_js': ( 'js/core.html#_generate_on_change_js',
+                                                                                                                     'cjm_fasthtml_token_selector/js/core.py'),
+                                                     'cjm_fasthtml_token_selector.js.core._generate_settle_handler_js': ( 'js/core.html#_generate_settle_handler_js',
+                                                                                                                          'cjm_fasthtml_token_selector/js/core.py'),
+                                                     'cjm_fasthtml_token_selector.js.core._generate_state_init_js': ( 'js/core.html#_generate_state_init_js',
+                                                                                                                      'cjm_fasthtml_token_selector/js/core.py'),
+                                                     'cjm_fasthtml_token_selector.js.core.generate_token_selector_js': ( 'js/core.html#generate_token_selector_js',
+                                                                                                                         'cjm_fasthtml_token_selector/js/core.py'),
+                                                     'cjm_fasthtml_token_selector.js.core.global_callback_name': ( 'js/core.html#global_callback_name',
+                                                                                                                   'cjm_fasthtml_token_selector/js/core.py')},
+            'cjm_fasthtml_token_selector.js.display': { 'cjm_fasthtml_token_selector.js.display._generate_gap_display_js': ( 'js/display.html#_generate_gap_display_js',
+                                                                                                                             'cjm_fasthtml_token_selector/js/display.py'),
+                                                        'cjm_fasthtml_token_selector.js.display._generate_span_display_js': ( 'js/display.html#_generate_span_display_js',
+                                                                                                                              'cjm_fasthtml_token_selector/js/display.py'),
+                                                        'cjm_fasthtml_token_selector.js.display._generate_update_inputs_js': ( 'js/display.html#_generate_update_inputs_js',
+                                                                                                                               'cjm_fasthtml_token_selector/js/display.py'),
+                                                        'cjm_fasthtml_token_selector.js.display._generate_word_display_js': ( 'js/display.html#_generate_word_display_js',
+                                                                                                                              'cjm_fasthtml_token_selector/js/display.py'),
+                                                        'cjm_fasthtml_token_selector.js.display.generate_display_js': ( 'js/display.html#generate_display_js',
+                                                                                                                        'cjm_fasthtml_token_selector/js/display.py')},
+            'cjm_fasthtml_token_selector.js.navigation': { 'cjm_fasthtml_token_selector.js.navigation._generate_gap_nav_js': ( 'js/navigation.html#_generate_gap_nav_js',
+                                                                                                                               'cjm_fasthtml_token_selector/js/navigation.py'),
+                                                           'cjm_fasthtml_token_selector.js.navigation._generate_span_nav_js': ( 'js/navigation.html#_generate_span_nav_js',
+                                                                                                                                'cjm_fasthtml_token_selector/js/navigation.py'),
+                                                           'cjm_fasthtml_token_selector.js.navigation._generate_word_nav_js': ( 'js/navigation.html#_generate_word_nav_js',
+                                                                                                                                'cjm_fasthtml_token_selector/js/navigation.py'),
+                                                           'cjm_fasthtml_token_selector.js.navigation.generate_navigation_js': ( 'js/navigation.html#generate_navigation_js',
+                                                                                                                                 'cjm_fasthtml_token_selector/js/navigation.py')},
+            'cjm_fasthtml_token_selector.js.repeat': { 'cjm_fasthtml_token_selector.js.repeat._generate_movement_dispatch_js': ( 'js/repeat.html#_generate_movement_dispatch_js',
+                                                                                                                                 'cjm_fasthtml_token_selector/js/repeat.py'),
+                                                       'cjm_fasthtml_token_selector.js.repeat.generate_key_repeat_js': ( 'js/repeat.html#generate_key_repeat_js',
+                                                                                                                         'cjm_fasthtml_token_selector/js/repeat.py')},
+            'cjm_fasthtml_token_selector.keyboard.actions': { 'cjm_fasthtml_token_selector.keyboard.actions.build_token_selector_url_map': ( 'keyboard/actions.html#build_token_selector_url_map',
+                                                                                                                                             'cjm_fasthtml_token_selector/keyboard/actions.py'),
+                                                              'cjm_fasthtml_token_selector.keyboard.actions.create_token_nav_actions': ( 'keyboard/actions.html#create_token_nav_actions',
+                                                                                                                                         'cjm_fasthtml_token_selector/keyboard/actions.py'),
+                                                              'cjm_fasthtml_token_selector.keyboard.actions.create_token_selector_mode': ( 'keyboard/actions.html#create_token_selector_mode',
+                                                                                                                                           'cjm_fasthtml_token_selector/keyboard/actions.py'),
+                                                              'cjm_fasthtml_token_selector.keyboard.actions.render_token_action_buttons': ( 'keyboard/actions.html#render_token_action_buttons',
+                                                                                                                                            'cjm_fasthtml_token_selector/keyboard/actions.py')}}}

cjm_fasthtml_token_selector/components/inputs.py

@@ -0,0 +1,46 @@
+"""Hidden input rendering for HTMX state sync."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/components/inputs.ipynb.
+
+# %% auto #0
+__all__ = ['render_hidden_inputs', 'build_include_selector']
+
+# %% ../../nbs/components/inputs.ipynb #330fdfc6
+from typing import Any, Optional, Tuple
+
+from fasthtml.common import Div, Hidden
+
+from ..core.models import TokenSelectorState
+from ..core.html_ids import TokenSelectorHtmlIds
+
+# %% ../../nbs/components/inputs.ipynb #2ebc5b73
+def render_hidden_inputs(
+    ids:TokenSelectorHtmlIds,                   # HTML IDs for this instance
+    state:Optional[TokenSelectorState] = None,  # current state
+    oob:bool = False,                           # render with hx-swap-oob
+) -> Any:  # tuple of anchor and focus hidden inputs
+    """Render hidden inputs for HTMX form submission."""
+    anchor = state.anchor if state else 0
+    focus = state.focus if state else 0
+
+    anchor_input = Hidden(
+        value=str(anchor),
+        id=ids.anchor_input,
+        name=ids.anchor_name,
+        **(dict(hx_swap_oob="true") if oob else {}),
+    )
+    focus_input = Hidden(
+        value=str(focus),
+        id=ids.focus_input,
+        name=ids.focus_name,
+        **(dict(hx_swap_oob="true") if oob else {}),
+    )
+
+    return (anchor_input, focus_input)
+
+# %% ../../nbs/components/inputs.ipynb #bd8bb783
+def build_include_selector(
+    ids:TokenSelectorHtmlIds,  # HTML IDs for this instance
+) -> str:  # CSS selector string for hx_include
+    """Build a CSS selector for including anchor and focus inputs in HTMX requests."""
+    return f"#{ids.anchor_input}, #{ids.focus_input}"

cjm_fasthtml_token_selector/components/tokens.py

@@ -0,0 +1,217 @@
+"""Token grid rendering for all three selection modes (gap, word, span)."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/components/tokens.ipynb.
+
+# %% auto #0
+__all__ = ['render_token', 'render_end_token', 'render_token_grid']
+
+# %% ../../nbs/components/tokens.ipynb #99d42647
+from typing import Any, Callable, List, Optional
+
+from fasthtml.common import Div, Span
+
+from cjm_fasthtml_daisyui.utilities.semantic_colors import bg_dui
+from cjm_fasthtml_daisyui.utilities.border_radius import border_radius
+
+from cjm_fasthtml_tailwind.utilities.spacing import p
+from cjm_fasthtml_tailwind.utilities.sizing import w, h
+from cjm_fasthtml_tailwind.utilities.typography import font_size, italic
+from cjm_fasthtml_tailwind.utilities.layout import position, top, left
+from cjm_fasthtml_tailwind.utilities.effects import opacity
+from cjm_fasthtml_tailwind.utilities.interactivity import cursor, select
+from cjm_fasthtml_tailwind.utilities.transitions_and_animation import animate
+from cjm_fasthtml_tailwind.utilities.transforms import translate
+from cjm_fasthtml_tailwind.utilities.flexbox_and_grid import flex_display, flex_wrap, gap
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+from cjm_fasthtml_token_selector.core.constants import (
+    CARET_INDICATOR_CLS, OPACITY_50_CLS, HIGHLIGHT_CLS,
+)
+from ..core.config import TokenSelectorConfig
+from ..core.models import Token, TokenRenderContext, TokenSelectorState
+from ..core.html_ids import TokenSelectorHtmlIds
+
+# %% ../../nbs/components/tokens.ipynb #0df5a9a9
+def _is_token_selected(
+    index:int,              # token index
+    mode:str,               # selection mode
+    anchor:int,             # anchor position
+    focus:int,              # focus position
+) -> bool:  # whether the token is in the selection
+    """Check if a token at the given index is within the current selection."""
+    if mode == "gap":
+        return False  # gap mode selects positions between tokens, not tokens themselves
+    elif mode == "word":
+        return index == anchor
+    elif mode == "span":
+        lo, hi = min(anchor, focus), max(anchor, focus)
+        return lo <= index <= hi
+    return False
+
+# %% ../../nbs/components/tokens.ipynb #2b37bdad
+def _build_token_render_context(
+    token:Token,                    # token being rendered
+    mode:str,                       # selection mode
+    anchor:int,                     # anchor position
+    focus:int,                      # focus position
+) -> TokenRenderContext:  # render context for styling callback
+    """Build a render context for the per-token styling callback."""
+    return TokenRenderContext(
+        token=token,
+        is_selected=_is_token_selected(token.index, mode, anchor, focus),
+        is_anchor=(token.index == anchor),
+        is_focus=(token.index == focus),
+        selection_mode=mode,
+    )
+
+# %% ../../nbs/components/tokens.ipynb #cd35fb5a
+def _render_caret_indicator() -> Any:  # caret indicator Div element
+    """Render the pulsing caret indicator bar."""
+    return Div(cls=CARET_INDICATOR_CLS)
+
+# %% ../../nbs/components/tokens.ipynb #a7c9db4c
+def render_token(
+    token:Token,                                      # token to render
+    config:TokenSelectorConfig,                       # config for this instance
+    ids:TokenSelectorHtmlIds,                         # HTML IDs
+    state:Optional[TokenSelectorState] = None,        # current state for highlighting
+    style_callback:Optional[Callable] = None,         # (TokenRenderContext) -> str for extra CSS
+    read_only:bool = False,                           # disable interaction
+) -> Any:  # Span element for this token
+    """Render a single interactive word token."""
+    anchor = state.anchor if state else 0
+    focus = state.focus if state else 0
+    mode = config.selection_mode
+    is_read_only = read_only or config.read_only
+    idx = token.index
+
+    # Determine visual state
+    selected = _is_token_selected(idx, mode, anchor, focus)
+    show_caret = (mode == "gap" and idx == anchor and state is not None)
+    dim = (mode == "gap" and idx < anchor and state is not None)
+
+    # Build token content
+    children = []
+    if show_caret:
+        children.append(_render_caret_indicator())
+    children.append(Span(token.text))
+
+    # Build CSS classes
+    cls_parts = [
+        "token", position.relative,
+        p.x(1), p.y(0.5),
+        border_radius.selector, cursor.pointer, select.none,
+    ]
+    if dim:
+        cls_parts.append(OPACITY_50_CLS)
+    if selected:
+        cls_parts.append(HIGHLIGHT_CLS)
+    if not is_read_only:
+        cls_parts.append(bg_dui.base_200.hover)
+
+    # Per-token styling callback
+    extra_cls = ""
+    if style_callback:
+        ctx = _build_token_render_context(token, mode, anchor, focus)
+        extra_cls = style_callback(ctx) or ""
+    if extra_cls:
+        cls_parts.append(extra_cls)
+
+    # Click handler
+    onclick = None
+    if not is_read_only:
+        ns = f"window.tokenSelectors['{config.prefix}']"
+        if mode == "gap":
+            onclick = f"{ns}.selectGap({idx})"
+        elif mode == "word":
+            onclick = f"{ns}.selectWord({idx})"
+        elif mode == "span":
+            onclick = f"{ns}.selectToken({idx})"
+
+    return Span(
+        *children,
+        id=ids.token(idx),
+        data_token_index=str(idx),
+        cls=combine_classes(*cls_parts),
+        onclick=onclick,
+    )
+
+# %% ../../nbs/components/tokens.ipynb #91bd40f4
+from cjm_fasthtml_daisyui.utilities.semantic_colors import text_dui
+
+# %% ../../nbs/components/tokens.ipynb #efb4515f
+def render_end_token(
+    config:TokenSelectorConfig,                 # config for this instance
+    ids:TokenSelectorHtmlIds,                   # HTML IDs
+    state:Optional[TokenSelectorState] = None,  # current state
+    read_only:bool = False,                     # disable interaction
+) -> Any:  # end sentinel Span element
+    """Render the end-of-text sentinel token."""
+    word_count = state.word_count if state else 0
+    anchor = state.anchor if state else 0
+    mode = config.selection_mode
+    is_read_only = read_only or config.read_only
+
+    # Caret at end position (gap mode only)
+    show_caret = (mode == "gap" and anchor == word_count and state is not None)
+
+    children = []
+    if show_caret:
+        children.append(_render_caret_indicator())
+    children.append(Span(config.end_token_text, cls=combine_classes(font_size.sm, italic)))
+
+    cls_parts = [
+        "token", position.relative,
+        p.x(1), p.y(0.5),
+        text_dui.base_content.opacity(30),
+        cursor.pointer, select.none,
+    ]
+    if not is_read_only:
+        cls_parts.append(text_dui.base_content.hover)
+
+    onclick = None
+    if not is_read_only and mode == "gap":
+        ns = f"window.tokenSelectors['{config.prefix}']"
+        onclick = f"{ns}.selectGap({word_count})"
+
+    return Span(
+        *children,
+        data_token_index=str(word_count),
+        cls=combine_classes(*cls_parts),
+        onclick=onclick,
+    )
+
+# %% ../../nbs/components/tokens.ipynb #8b429b4b
+def render_token_grid(
+    tokens:List[Token],                               # token list to render
+    config:TokenSelectorConfig,                       # config for this instance
+    ids:TokenSelectorHtmlIds,                         # HTML IDs
+    state:Optional[TokenSelectorState] = None,        # current state for highlighting
+    style_callback:Optional[Callable] = None,         # (TokenRenderContext) -> str for extra CSS
+    read_only:bool = False,                           # disable all interaction
+) -> Any:  # Div containing the complete token grid
+    """Render the full interactive token grid."""
+    is_read_only = read_only or config.read_only
+
+    # Render individual tokens
+    token_elements = [
+        render_token(t, config, ids, state, style_callback, is_read_only)
+        for t in tokens
+    ]
+
+    # End token (gap mode only, if enabled)
+    if config.show_end_token and config.selection_mode == "gap":
+        token_elements.append(render_end_token(config, ids, state, is_read_only))
+
+    word_count = len(tokens)
+
+    return Div(
+        *token_elements,
+        id=ids.token_grid,
+        data_word_count=str(word_count),
+        cls=combine_classes(
+            "token-container",
+            flex_display, flex_wrap.wrap,
+            gap(1), p(2),
+        ),
+    )

cjm_fasthtml_token_selector/core/config.py

@@ -0,0 +1,57 @@
+"""Configuration dataclass for token selector initialization."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/config.ipynb.
+
+# %% auto #0
+__all__ = ['TokenSelectorConfig']
+
+# %% ../../nbs/core/config.ipynb #4904f597
+from dataclasses import dataclass, field
+
+from cjm_fasthtml_token_selector.core.constants import (
+    SelectionMode,
+    DEFAULT_INITIAL_DELAY, DEFAULT_REPEAT_INTERVAL, DEFAULT_THROTTLE_FLOOR,
+    DEFAULT_LEFT_KEY, DEFAULT_RIGHT_KEY, DEFAULT_END_TOKEN_TEXT,
+)
+
+# %% ../../nbs/core/config.ipynb #4f3321a9
+_prefix_counter:int = 0
+
+def _auto_prefix() -> str: # unique prefix string
+    """Generate an auto-incrementing unique prefix."""
+    global _prefix_counter
+    p = f"ts{_prefix_counter}"
+    _prefix_counter += 1
+    return p
+
+def _reset_prefix_counter() -> None:
+    """Reset the prefix counter (for testing only)."""
+    global _prefix_counter
+    _prefix_counter = 0
+
+# %% ../../nbs/core/config.ipynb #2ac6669d
+@dataclass
+class TokenSelectorConfig:
+    """Initialization-time settings for a token selector instance."""
+    prefix:str = field(default_factory=_auto_prefix)  # unique instance prefix
+    selection_mode:SelectionMode = "gap"  # selection behavior: "gap", "word", or "span"
+
+    # Key repeat engine timing
+    initial_delay:int = DEFAULT_INITIAL_DELAY      # ms before first repeat
+    repeat_interval:int = DEFAULT_REPEAT_INTERVAL   # ms between repeats
+    throttle_floor:int = DEFAULT_THROTTLE_FLOOR     # minimum ms between movements
+
+    # Key mappings (for the internal key repeat engine)
+    left_key:str = DEFAULT_LEFT_KEY    # key for leftward navigation
+    right_key:str = DEFAULT_RIGHT_KEY  # key for rightward navigation
+
+    # Display
+    end_token_text:str = DEFAULT_END_TOKEN_TEXT  # text for the sentinel end token
+    show_end_token:bool = True   # whether to show the end token
+
+    # Behavior
+    read_only:bool = False       # disable click/keyboard interaction
+    wrap_navigation:bool = False # wrap around at boundaries
+
+    # Callbacks
+    on_change_callback:str = ""  # JS function name called on selection change

cjm_fasthtml_token_selector/core/constants.py

@@ -0,0 +1,50 @@
+"""CSS class constants, selection mode type, timing defaults, and key defaults for the token selector."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/constants.ipynb.
+
+# %% auto #0
+__all__ = ['SelectionMode', 'OPACITY_50_CLS', 'CARET_INDICATOR_CLS', 'HIGHLIGHT_CLS', 'DEFAULT_INITIAL_DELAY',
+           'DEFAULT_REPEAT_INTERVAL', 'DEFAULT_THROTTLE_FLOOR', 'DEFAULT_LEFT_KEY', 'DEFAULT_RIGHT_KEY',
+           'DEFAULT_END_TOKEN_TEXT']
+
+# %% ../../nbs/core/constants.ipynb #2309118c
+from typing import Literal
+
+# %% ../../nbs/core/constants.ipynb #a026c6f9
+from cjm_fasthtml_daisyui.utilities.semantic_colors import bg_dui
+
+from cjm_fasthtml_tailwind.utilities.sizing import w, h
+from cjm_fasthtml_tailwind.utilities.layout import position, top, left
+from cjm_fasthtml_tailwind.utilities.effects import opacity
+from cjm_fasthtml_tailwind.utilities.transitions_and_animation import animate
+from cjm_fasthtml_tailwind.utilities.transforms import translate
+from cjm_fasthtml_tailwind.core.base import combine_classes
+
+# %% ../../nbs/core/constants.ipynb #07b9f913
+SelectionMode = Literal["gap", "word", "span"]
+
+# %% ../../nbs/core/constants.ipynb #717f0741
+OPACITY_50_CLS = str(opacity(50))
+
+# %% ../../nbs/core/constants.ipynb #75b65c24
+CARET_INDICATOR_CLS = combine_classes(
+    "caret-indicator",
+    w(0.5), h(5), bg_dui.error,
+    position.absolute, left.negative(1), top("1/2"), translate.y.negative("1/2"),
+    animate.pulse
+)
+
+# %% ../../nbs/core/constants.ipynb #c2f02ac7
+HIGHLIGHT_CLS = str(bg_dui.primary.opacity(20))
+
+# %% ../../nbs/core/constants.ipynb #ba9f3ddf
+DEFAULT_INITIAL_DELAY:int = 400   # ms before first repeat
+DEFAULT_REPEAT_INTERVAL:int = 80  # ms between repeats
+DEFAULT_THROTTLE_FLOOR:int = 50   # minimum ms between movements
+
+# %% ../../nbs/core/constants.ipynb #472a38eb
+DEFAULT_LEFT_KEY:str = "ArrowLeft"
+DEFAULT_RIGHT_KEY:str = "ArrowRight"
+
+# %% ../../nbs/core/constants.ipynb #9fee5792
+DEFAULT_END_TOKEN_TEXT:str = "(End)"

cjm_fasthtml_token_selector/core/html_ids.py

@@ -0,0 +1,51 @@
+"""Prefix-based HTML ID generator for token selector DOM elements."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/html_ids.ipynb.
+
+# %% auto #0
+__all__ = ['TokenSelectorHtmlIds']
+
+# %% ../../nbs/core/html_ids.ipynb #00fedd76
+from dataclasses import dataclass
+
+# %% ../../nbs/core/html_ids.ipynb #24a81661
+@dataclass
+class TokenSelectorHtmlIds:
+    """Prefix-based HTML ID generator for token selector DOM elements."""
+    prefix:str  # unique instance prefix
+
+    @property
+    def container(self) -> str:  # outer wrapper ID
+        """Outer token selector wrapper."""
+        return f"{self.prefix}-token-selector"
+
+    @property
+    def token_grid(self) -> str:  # flex-wrap token container ID
+        """Flex-wrap token container."""
+        return f"{self.prefix}-token-grid"
+
+    @property
+    def anchor_input(self) -> str:  # hidden input ID for anchor position
+        """Hidden input ID for anchor position (hyphenated, for CSS selectors)."""
+        return f"{self.prefix}-anchor"
+
+    @property
+    def focus_input(self) -> str:  # hidden input ID for focus position
+        """Hidden input ID for focus position (hyphenated, for CSS selectors)."""
+        return f"{self.prefix}-focus"
+
+    @property
+    def anchor_name(self) -> str:  # form field name for anchor position
+        """Form field name for anchor position (underscored, for Python kwargs)."""
+        return f"{self.prefix}_anchor"
+
+    @property
+    def focus_name(self) -> str:  # form field name for focus position
+        """Form field name for focus position (underscored, for Python kwargs)."""
+        return f"{self.prefix}_focus"
+
+    def token(self,
+              index:int,  # token position index
+             ) -> str:  # individual token span ID
+        """Individual token span ID."""
+        return f"{self.prefix}-token-{index}"

cjm_fasthtml_token_selector/core/models.py

@@ -0,0 +1,37 @@
+"""Data models for tokens, render context, and mutable runtime state."""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/models.ipynb.
+
+# %% auto #0
+__all__ = ['Token', 'TokenRenderContext', 'TokenSelectorState']
+
+# %% ../../nbs/core/models.ipynb #cd8f9e39
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+# %% ../../nbs/core/models.ipynb #1a22b1bf
+@dataclass
+class Token:
+    """A single token in the token grid."""
+    text:str        # the token text content
+    index:int       # 0-based position in the token list
+    metadata:Any = None  # optional consumer metadata per token
+
+# %% ../../nbs/core/models.ipynb #a8270e15
+@dataclass
+class TokenRenderContext:
+    """Context passed to per-token styling callbacks."""
+    token:Token        # the token being rendered
+    is_selected:bool   # whether this token is in the current selection
+    is_anchor:bool     # whether this token is at the anchor position
+    is_focus:bool      # whether this token is at the focus position
+    selection_mode:str  # current selection mode
+
+# %% ../../nbs/core/models.ipynb #84e86d0a
+@dataclass
+class TokenSelectorState:
+    """Mutable runtime state for a token selector instance."""
+    anchor:int = 0      # anchor position (gap index or token index)
+    focus:int = 0       # focus position (same as anchor in gap/word mode)
+    word_count:int = 0  # total number of tokens
+    active:bool = False # whether the key repeat engine is active