# jamesplease/lrud architecture

> Architecture diagram of the GitHub repository jamesplease/lrud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamesplease/lrud
- Repository: https://github.com/jamesplease/lrud

## Overview

##### Main Components
- Focus Management Core – At the heart is the FocusStore which maintains the state including focus hierarchy, current focused node, active node, and event propagation. This connects to all functions that update or retrieve state.
- Focus Components – Your “View Layer” represented by React components such as:
- <FocusRoot>: The top-level node that sets global orientation, wrapping, and serves as the anchor of the focus tree.
- <FocusNode>: Represents individual focusable nodes. They encapsulate properties like focusId, orientation, grid navigation details, event callbacks (e.g., onArrow, onSelected) and CSS classes.
- Utilities and Internal Functions – Helpers found in “src/utils” and in the “src/focus-store,” which are responsible for computations and state validations (e.g., creating, updating, or deleting nodes).

##### Architectural Patterns
- Component-Based Architecture:
- Separation of concerns: UI components are “dumb” wrappers (FocusRoot/FocusNode) that delegate to internal logic.
- The Focus Management pattern is intermediary between user inputs and DOM updates, ensuring that focus changes propagate through the component tree.
- Event Propagation:
- Hook Abstraction:
- Focus hooks encapsulate logic for interacting with the focus tree. Illustrate how these hooks (mounted in the consuming application) access FocusStore state and trigger imperative commands (like setFocus).

##### Technologies and Frameworks
- React is the key framework.

##### Detail Without Overcomplicating
- A side section summarizing “Examples” and “Guides” that show practical use cases.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Components Subgraph
    subgraph "UI Components"
        FR("FocusRoot"):::ui
        FN("FocusNode"):::ui
    end

    %% State Management Subgraph
    subgraph "State Management"
        FS("FocusStore"):::state
    end

    %% Hooks & Utilities Subgraph
    subgraph "Hooks & Utilities"
        HK("Hooks"):::hook
        UT("Utils"):::util
    end

    %% Event Processing Subgraph
    subgraph "Event Processing"
        LI("LRUD Input"):::event
        AK("Arrow Key Processing"):::event
        UF("Focus Updates"):::event
    end

    %% Connections for Event Processing flow
    LI -->|"triggers"| AK
    AK -->|"calls"| UF
    UF -->|"updates"| FS
    UT -->|"supports"| AK
    UT -->|"supports"| UF

    %% Connections for UI Components and their interaction with State Management
    FR -->|"lifecycleEvents"| FS
    FN -->|"lifecycleEvents"| FS
    FS -->|"notifies"| FR
    FS -->|"notifies"| FN

    %% Connections for Hooks interaction with State Management
    FS -->|"stateChanges"| HK
    HK -->|"setFocus"| FS

    %% Click Events
    click FS "https://github.com/jamesplease/lrud/blob/main/src/focus-store.ts"
    click FR "https://github.com/jamesplease/lrud/blob/main/src/focus-context.tsx"
    click FN "https://github.com/jamesplease/lrud/blob/main/src/focus-node.tsx"
    click HK "https://github.com/jamesplease/lrud/tree/main/src/hooks"
    click AK "https://github.com/jamesplease/lrud/blob/main/src/handle-arrow/handle-arrow.ts"
    click UF "https://github.com/jamesplease/lrud/tree/main/src/update-focus"
    click UT "https://github.com/jamesplease/lrud/tree/main/src/utils"
    click LI "https://github.com/jamesplease/lrud/tree/main/src/lrud-input"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef state fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef event fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef hook fill:#F5CBA7,stroke:#7D6608,stroke-width:2px;
    classDef util fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
```
