smart_keymap_core/key/

layered.rs

use core::fmt::Debug;
use core::marker::Copy;
use core::ops::Index;

use serde::Deserialize;

use crate::input;
use crate::key;
use crate::key::KeyboardModifiers;
use crate::slice::Slice;

/// The type used for layer index.
pub type LayerIndex = u32;

/// The type used for set of active layers in ModifierKey.
/// (Layer bit indices `0..=[MAX_BITSET_LAYER]`.)
pub type LayerBitset = u32;

/// The maximum layer bit index representable in a [LayerBitset].
///
/// For `LayerBitset = u32`, this is 31 (bits 0..=31, i.e. 32 layers).
pub const MAX_BITSET_LAYER: usize = 8 * core::mem::size_of::<LayerBitset>() - 1;

/// The bitset with all representable modifier layers in the mask.
///
/// Includes bit [MAX_BITSET_LAYER] (e.g. bit 31 for `u32`).
pub const BITSET_MASK_ALL: LayerBitset = LayerBitset::MAX;

/// Struct for modifying layers with a bitset.
#[repr(C)]
#[derive(Debug, Deserialize, Clone, Copy, Eq, PartialEq)]
pub struct ModifierBitset {
    /// The set of layers modified.
    pub layers: LayerBitset,
    /// The mask for which layers are affected by the modification.
    #[serde(default = "default_modifier_bitset_mask")]
    pub mask: LayerBitset,
}

fn default_modifier_bitset_mask() -> LayerBitset {
    BITSET_MASK_ALL
}

/// Reference for a keyboard key.
#[derive(Deserialize, Debug, Clone, Copy, PartialEq)]
pub enum Ref {
    /// Ref to a layer modifier key.
    Modifier(u8),
    /// Ref to a layered key.
    Layered(u8),
}

/// Modifier layer key affects what layers are active.
#[derive(Debug, Deserialize, Clone, Copy, PartialEq)]
pub enum ModifierKey {
    /// Activates the given layer when held.
    Hold(LayerIndex, KeyboardModifiers),
    /// Toggles whether the given layer is active when pressed.
    Toggle(LayerIndex),
    /// Sticky layer modifier, similar to sticky modifier key.
    ///
    /// Acts the same as `Hold` variant if interrupted.
    /// If tapped, then the layer is activated for the next key tap.
    Sticky(LayerIndex),
    /// Sets the set of active layers to the given layers when the key is pressed.
    SetActiveLayers(ModifierBitset),
    /// Sets the default layer.
    Default(LayerIndex),
}

impl ModifierKey {
    /// Create a new [ModifierKey] that activates the given layer when held.
    pub const fn hold(layer: LayerIndex) -> Self {
        ModifierKey::Hold(layer, key::KeyboardModifiers::NONE)
    }

    /// Adds keyboard modifiers to a Hold modifier key.
    pub const fn with_keyboard_modifiers(self, mods: key::KeyboardModifiers) -> Self {
        match self {
            ModifierKey::Hold(layer, _) => ModifierKey::Hold(layer, mods),
            other => other,
        }
    }

    /// Create a new [ModifierKey] that activates the layer when held, or makes it sticky when tapped.
    pub const fn sticky(layer: LayerIndex) -> Self {
        ModifierKey::Sticky(layer)
    }

    /// Create a new [ModifierKey] that toggles the given layer.
    pub const fn toggle(layer: LayerIndex) -> Self {
        ModifierKey::Toggle(layer)
    }

    /// Create a new [ModifierKey] that sets the active layers to the given slice of layers when pressed.
    ///
    /// Each LayerIndex in the slice must be at most [MAX_BITSET_LAYER].
    pub const fn set_active_layers(layers: &[LayerIndex]) -> Self {
        let mut bitset = 0;

        let mut idx = 0;
        while idx < layers.len() {
            let layer = layers[idx] as usize;
            if layer <= MAX_BITSET_LAYER {
                bitset |= 1 << layer;
            } else {
                panic!("LayerIndex must be at most MAX_BITSET_LAYER");
            }
            idx += 1;
        }

        let mask = BITSET_MASK_ALL;
        ModifierKey::SetActiveLayers(ModifierBitset {
            layers: bitset,
            mask,
        })
    }

    /// Create a new [ModifierKey] that sets the active layers bitset.
    pub const fn set_active_layers_from_bitset(bitset: LayerBitset) -> Self {
        let mask = BITSET_MASK_ALL;
        ModifierKey::SetActiveLayers(ModifierBitset {
            layers: bitset,
            mask,
        })
    }

    /// Create a new [ModifierKey] that sets the active layers bitset.
    pub const fn set_active_layers_from_bitset_with_mask(
        layers: LayerBitset,
        mask: LayerBitset,
    ) -> Self {
        ModifierKey::SetActiveLayers(ModifierBitset { layers, mask })
    }

    /// Create a new [ModifierKey] that sets the default layer.
    pub const fn default(layer: LayerIndex) -> Self {
        ModifierKey::Default(layer)
    }

    /// Create a new [input::PressedKey] and [key::ScheduledEvent] for the given keymap index.
    ///
    /// Pressing a [ModifierKey::Hold] emits a [LayerEvent::Activated] event.
    pub fn new_pressed_key(&self) -> (ModifierKeyState, Option<LayerEvent>) {
        match self {
            ModifierKey::Hold(layer, _) => {
                (ModifierKeyState::new(), Some(LayerEvent::Activated(*layer)))
            }
            ModifierKey::Toggle(layer) => {
                (ModifierKeyState::new(), Some(LayerEvent::Toggled(*layer)))
            }
            ModifierKey::Sticky(layer) => (
                ModifierKeyState::sticky(),
                Some(LayerEvent::StickyActivated(*layer)),
            ),
            ModifierKey::SetActiveLayers(modifier_bitset) => (
                ModifierKeyState::new(),
                Some(LayerEvent::Set(*modifier_bitset)),
            ),
            ModifierKey::Default(layer) => (
                ModifierKeyState::new(),
                Some(LayerEvent::SetDefault(*layer)),
            ),
        }
    }
}

impl From<LayerEvent> for () {
    fn from(_: LayerEvent) -> Self {}
}

/// Style of activating a layer.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ActivationStyle {
    /// Regular layer activation.
    Regular,
    /// Sticky layer activation.
    ///
    /// Sticky layer activation is similar to sticky key modifiers.
    /// The sticky layer activation is implemented using the sticky layer modifier key.
    Sticky,
}

/// State of an individual layer: active or inactive.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Activity {
    /// The layer is active.
    Active(ActivationStyle),
    /// The layer is inactive.
    Inactive,
}

impl Activity {
    /// Returns true if the layer is active.
    pub fn is_active(&self) -> bool {
        matches!(self, Activity::Active(_))
    }
}

/// Tracks state of active layers.
pub trait LayerState: Copy + Debug {
    /// Activate the given layer.
    fn activate(&mut self, layer: LayerIndex, style: ActivationStyle);
    /// Deactivate the given layer.
    fn deactivate(&mut self, layer: LayerIndex);
    /// Get the active layers, from highest active layer to lowest.
    fn active_layers(&self) -> impl Iterator<Item = LayerIndex>;
}

impl<const L: usize> LayerState for [Activity; L] {
    fn activate(&mut self, layer_index: LayerIndex, style: ActivationStyle) {
        let layer_index: usize = layer_index as usize;
        debug_assert!(
            layer_index <= L,
            "layer must be less than array length of {}",
            L
        );
        self[layer_index - 1] = Activity::Active(style);
    }

    fn deactivate(&mut self, layer_index: LayerIndex) {
        let layer_index: usize = layer_index as usize;
        debug_assert!(
            layer_index <= L,
            "layer must be less than array length of {}",
            L
        );
        self[layer_index - 1] = Activity::Inactive;
    }

    fn active_layers(&self) -> impl Iterator<Item = LayerIndex> {
        self.iter().enumerate().rev().filter_map(|(i, activity)| {
            if activity.is_active() {
                Some(i as LayerIndex + 1)
            } else {
                None
            }
        })
    }
}

struct ActiveLayersDebugHelper<'a, const LAYER_COUNT: usize> {
    active_layers: &'a [Activity; LAYER_COUNT],
}

impl<const LAYER_COUNT: usize> core::fmt::Debug for ActiveLayersDebugHelper<'_, LAYER_COUNT> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        // Reverse-find the last Active layer to avoid printing large arrays.
        let last_active_pos = self
            .active_layers
            .iter()
            .rposition(|&pc| pc.is_active())
            .map_or(0, |pos| pos + 1);
        if last_active_pos < LAYER_COUNT {
            f.debug_list()
                .entries(&self.active_layers[..last_active_pos])
                .finish_non_exhaustive()
        } else {
            f.debug_list().entries(&self.active_layers[..]).finish()
        }
    }
}

/// Conditional layer rule: activate [Self::then_layer] while every layer in
/// [Self::if_layers] is active.
///
/// Layer indices are 1-based (same as [ModifierKey]). Bit `i` of
/// [Self::if_layers] corresponds to layer `i` (same layout as [ModifierBitset]).
#[repr(C)]
#[derive(Debug, Deserialize, Clone, Copy, Eq, PartialEq)]
pub struct ConditionalLayer {
    /// Layer activated while the condition holds.
    pub then_layer: LayerIndex,
    /// Bitset of layers that must all be active.
    pub if_layers: LayerBitset,
}

impl ConditionalLayer {
    /// Constructs a rule from a then-layer and an if-layers bitset.
    pub const fn new(then_layer: LayerIndex, if_layers: LayerBitset) -> Self {
        Self {
            then_layer,
            if_layers,
        }
    }

    /// Constructs a rule from a then-layer and if-layer indices.
    pub const fn from_if_layers(then_layer: LayerIndex, if_layers: &[LayerIndex]) -> Self {
        let mut bitset: LayerBitset = 0;
        let mut i = 0;
        while i < if_layers.len() {
            let layer = if_layers[i] as usize;
            if layer <= MAX_BITSET_LAYER {
                bitset |= 1 << layer;
            }
            i += 1;
        }
        Self {
            then_layer,
            if_layers: bitset,
        }
    }
}

/// Configuration for layered keys / sticky layers / conditional layers.
#[derive(Deserialize, Debug, Clone, Copy, PartialEq)]
pub struct Config<const CONDITIONAL_LAYER_COUNT: usize = 0> {
    /// Timeout (ms) after which an unused sticky layer deactivates.
    ///
    /// When [None], sticky layers stay active until another key is used.
    ///
    /// The timeout starts when a sticky layer modifier is *released*
    /// without interruption (sticky committed). If another key is pressed
    /// while sticky is active, the timeout is cancelled / ignored.
    #[serde(default)]
    pub sticky_timeout: Option<u16>,

    /// Rules that activate a then-layer when all of their if-layers are active.
    #[serde(default)]
    pub conditional_layers: Slice<ConditionalLayer, CONDITIONAL_LAYER_COUNT>,
}

/// Default layered config (no sticky timeout, no conditional layers).
pub const DEFAULT_CONFIG: Config = Config {
    sticky_timeout: None,
    conditional_layers: Slice::from_slice(&[]),
};

impl<const CONDITIONAL_LAYER_COUNT: usize> Config<CONDITIONAL_LAYER_COUNT> {
    /// Constructs a new default [Config].
    pub const fn new() -> Self {
        Self {
            sticky_timeout: None,
            conditional_layers: Slice::from_slice(&[]),
        }
    }
}

impl<const CONDITIONAL_LAYER_COUNT: usize> Default for Config<CONDITIONAL_LAYER_COUNT> {
    fn default() -> Self {
        Self::new()
    }
}

/// [crate::key::Context] for [LayeredKey] that tracks active layers.
#[derive(Clone, Copy)]
pub struct Context<const LAYER_COUNT: usize, const CONDITIONAL_LAYER_COUNT: usize = 0> {
    config: Config<CONDITIONAL_LAYER_COUNT>,
    default_layer: Option<LayerIndex>,
    active_layers: [Activity; LAYER_COUNT],
    // Keymap index which was pressed while a layer was sticky.
    pressed_keymap_index: Option<u16>,
    // Invalidates pending sticky-timeout events when advanced.
    sticky_timeout_id: u8,
}

impl<const LAYER_COUNT: usize, const CONDITIONAL_LAYER_COUNT: usize> Debug
    for Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("Context")
            .field("config", &self.config)
            .field("default_layer", &self.default_layer)
            .field(
                "active_layers",
                &ActiveLayersDebugHelper {
                    active_layers: &self.active_layers,
                },
            )
            .field("pressed_keymap_index", &self.pressed_keymap_index)
            .field("sticky_timeout_id", &self.sticky_timeout_id)
            .finish()
    }
}

impl<const LAYER_COUNT: usize, const CONDITIONAL_LAYER_COUNT: usize>
    Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    /// Create a new [Context].
    pub const fn new() -> Self {
        Self::from_config(Config::new())
    }

    /// Constructs a context from the given config.
    pub const fn from_config(config: Config<CONDITIONAL_LAYER_COUNT>) -> Self {
        Context {
            config,
            default_layer: None,
            active_layers: [Activity::Inactive; LAYER_COUNT],
            pressed_keymap_index: None,
            sticky_timeout_id: 0,
        }
    }

    /// Re-construct from context's [Config], clearing active layers and sticky state.
    pub fn reset(&mut self) {
        *self = Self::from_config(self.config);
    }

    fn invalidate_sticky_timeouts(&mut self) {
        self.sticky_timeout_id = self.sticky_timeout_id.wrapping_add(1);
    }

    fn deactivate_sticky_layer(&mut self, layer: LayerIndex) {
        self.active_layers.deactivate(layer);
        self.pressed_keymap_index = None;
        self.invalidate_sticky_timeouts();
        self.apply_conditional_layers();
    }

    /// Bitset of currently active layers (bit `i` = layer `i`).
    fn active_layers_bitset(&self) -> LayerBitset {
        let max_layer = 1 + LAYER_COUNT.min(MAX_BITSET_LAYER);
        (1..max_layer).fold(0, |bits, li| {
            if self.active_layers[li - 1].is_active() {
                bits | (1 << li)
            } else {
                bits
            }
        })
    }

    /// One pass over conditional rules; returns whether any then-layer changed.
    fn apply_conditional_layers_once(&mut self) -> bool {
        // Copy rules so we can mutate active_layers while iterating.
        let rules = self.config.conditional_layers;
        let active = self.active_layers_bitset();
        rules.as_slice().iter().fold(false, |changed, rule| {
            let should = (active & rule.if_layers) == rule.if_layers;
            let is_active = (active & (1 << rule.then_layer)) != 0;
            if should == is_active {
                changed
            } else if should {
                self.active_layers
                    .activate(rule.then_layer, ActivationStyle::Regular);
                true
            } else {
                self.active_layers.deactivate(rule.then_layer);
                true
            }
        })
    }

    /// Evaluate conditional layer rules until stable, or up to one pass per rule.
    ///
    /// Nested rules (a then-layer used as an if-layer of another rule) settle
    /// without depending on rule definition order. The pass limit bounds the
    /// work for a pure dependency chain and prevents non-termination if rules
    /// disagree about the same then-layer.
    fn apply_conditional_layers(&mut self) {
        for _ in 0..CONDITIONAL_LAYER_COUNT {
            if !self.apply_conditional_layers_once() {
                break;
            }
        }
    }
}

impl<const LAYER_COUNT: usize, const CONDITIONAL_LAYER_COUNT: usize> Default
    for Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    fn default() -> Self {
        Self::new()
    }
}

impl<const LAYER_COUNT: usize, const CONDITIONAL_LAYER_COUNT: usize>
    Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    /// Get the active layers.
    pub fn layer_state(&self) -> &[Activity; LAYER_COUNT] {
        &self.active_layers
    }

    fn sticky_layer(&self) -> Option<LayerIndex> {
        self.active_layers
            .iter()
            .position(|&a| a == Activity::Active(ActivationStyle::Sticky))
            .map(|i| i as LayerIndex + 1)
    }

    /// Updates the context with the [LayerEvent].
    ///
    /// Returns scheduled events (e.g. sticky timeout).
    fn handle_layer_event(&mut self, event: LayerEvent) -> key::KeyEvents<LayerEvent> {
        match event {
            LayerEvent::Activated(layer) => {
                self.active_layers.activate(layer, ActivationStyle::Regular);
                // Sticky cancelled / converted to hold — drop any sticky timeout.
                self.invalidate_sticky_timeouts();
                self.apply_conditional_layers();
                key::KeyEvents::no_events()
            }
            LayerEvent::Deactivated(layer) => {
                self.active_layers.deactivate(layer);
                self.invalidate_sticky_timeouts();
                self.apply_conditional_layers();
                key::KeyEvents::no_events()
            }
            LayerEvent::StickyActivated(layer) => {
                self.active_layers.activate(layer, ActivationStyle::Sticky);
                self.pressed_keymap_index = None;
                // Previous sticky wait is superseded while this sticky key is held.
                self.invalidate_sticky_timeouts();
                self.apply_conditional_layers();
                key::KeyEvents::no_events()
            }
            LayerEvent::StickyReleased => {
                // Sticky key released without interruption: layer stays sticky.
                // Arm optional timeout for "no next key pressed".
                if self.sticky_layer().is_none() {
                    key::KeyEvents::no_events()
                } else {
                    self.invalidate_sticky_timeouts();
                    let timeout_id = self.sticky_timeout_id;
                    match self.config.sticky_timeout {
                        Some(timeout) => {
                            key::KeyEvents::scheduled_event(key::ScheduledEvent::after(
                                timeout,
                                key::Event::key_event(0, LayerEvent::StickyTimeout(timeout_id)),
                            ))
                        }
                        None => key::KeyEvents::no_events(),
                    }
                }
            }
            LayerEvent::StickyTimeout(timeout_id) => {
                if timeout_id == self.sticky_timeout_id && self.pressed_keymap_index.is_none() {
                    if let Some(layer) = self.sticky_layer() {
                        // deactivate_sticky_layer applies conditionals.
                        self.deactivate_sticky_layer(layer);
                    }
                }
                key::KeyEvents::no_events()
            }
            LayerEvent::Toggled(layer) => {
                if self.active_layers[layer as usize - 1].is_active() {
                    self.active_layers.deactivate(layer);
                } else {
                    self.active_layers.activate(layer, ActivationStyle::Regular);
                }
                self.apply_conditional_layers();
                key::KeyEvents::no_events()
            }
            LayerEvent::Set(ModifierBitset { layers, mask }) => {
                let max_layer = 1 + LAYER_COUNT.min(MAX_BITSET_LAYER);

                // layer 0 is always active.
                for li in 1..max_layer {
                    if (mask & (1 << li)) != 0 {
                        if (layers & (1 << li)) != 0 {
                            self.active_layers
                                .activate(li as LayerIndex, ActivationStyle::Regular);
                        } else {
                            self.active_layers.deactivate(li as LayerIndex);
                        }
                    }
                }
                self.apply_conditional_layers();
                key::KeyEvents::no_events()
            }
            LayerEvent::SetDefault(0) => {
                self.default_layer = None;
                key::KeyEvents::no_events()
            }
            LayerEvent::SetDefault(layer) => {
                self.default_layer = Some(layer);
                key::KeyEvents::no_events()
            }
        }
    }

    /// Updates the context with the [key::Event].
    fn handle_event(&mut self, event: key::Event<LayerEvent>) -> key::KeyEvents<LayerEvent> {
        match event {
            key::Event::Input(input::Event::Press { keymap_index, .. }) => {
                if let Some(sticky_layer_index) = self.sticky_layer() {
                    if self.pressed_keymap_index.is_some() {
                        // The sticky layer modifier has already been used;
                        // the sticky layer should be deactivated for subsequent presses.
                        self.deactivate_sticky_layer(sticky_layer_index);
                    } else {
                        // Next key is using the sticky layer; cancel timeout.
                        self.invalidate_sticky_timeouts();
                        self.pressed_keymap_index = Some(keymap_index);
                    }
                }
                key::KeyEvents::no_events()
            }
            key::Event::Input(input::Event::Release { keymap_index, .. }) => {
                if let Some(sticky_layer_index) = self.sticky_layer() {
                    if self.pressed_keymap_index == Some(keymap_index) {
                        self.deactivate_sticky_layer(sticky_layer_index);
                    }
                }
                key::KeyEvents::no_events()
            }
            key::Event::Key { key_event, .. } => self.handle_layer_event(key_event),
            _ => key::KeyEvents::no_events(),
        }
    }
}

impl<const LAYER_COUNT: usize, const CONDITIONAL_LAYER_COUNT: usize> key::Context
    for Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    type Event = LayerEvent;

    fn handle_event(&mut self, event: key::Event<Self::Event>) -> key::KeyEvents<Self::Event> {
        self.handle_event(event)
    }

    fn reset(&mut self) {
        Context::reset(self);
    }
}

/// Errors when constructing Layers.
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum LayersError {
    /// Trying to construct more layers than the Layers can store.
    Overflow,
}

impl core::fmt::Display for LayersError {
    // This trait requires `fmt` with this exact signature.
    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
        write!(f, "LayersError::Overflow")
    }
}

/// Trait for layers of [LayeredKey].
pub trait Layers<R>: Copy + Debug {
    /// Get the highest active key, if any, for the given [LayerState].
    fn highest_active_key<LS: LayerState>(
        &self,
        layer_state: &LS,
        default_layer: Option<LayerIndex>,
    ) -> Option<(LayerIndex, R)>;
    /// Constructs layers; return Err if the iterable has more keys than Layers can store.
    fn from_iterable<I: IntoIterator<Item = Option<R>>>(keys: I) -> Result<Self, LayersError>;
}

impl<R: Copy + Debug, const L: usize> Layers<R> for [Option<R>; L] {
    fn highest_active_key<LS: LayerState>(
        &self,
        layer_state: &LS,
        default_layer: Option<LayerIndex>,
    ) -> Option<(LayerIndex, R)> {
        for layer_index in layer_state.active_layers() {
            if self[layer_index as usize - 1].is_some() {
                return self[layer_index as usize - 1].map(|k| (layer_index, k));
            }
        }

        match default_layer {
            Some(layer_index) if self[layer_index as usize - 1].is_some() => {
                self[layer_index as usize - 1].map(|k| (layer_index, k))
            }
            _ => None,
        }
    }

    fn from_iterable<I: IntoIterator<Item = Option<R>>>(keys: I) -> Result<Self, LayersError> {
        let mut layered: [Option<R>; L] = [None; L];
        for (i, maybe_key) in keys.into_iter().enumerate() {
            if i < L {
                layered[i] = maybe_key;
            } else {
                return Err(LayersError::Overflow);
            }
        }
        Ok(layered)
    }
}

/// Constructs an array of keys for the given array.
pub const fn layered_keys<K: Copy, const L: usize, const LAYER_COUNT: usize>(
    keys: [Option<K>; L],
) -> [Option<K>; LAYER_COUNT] {
    let mut layered: [Option<K>; LAYER_COUNT] = [None; LAYER_COUNT];

    if L > LAYER_COUNT {
        panic!("Too many layers for layered_keys");
    }

    let mut i = 0;

    while i < L {
        layered[i] = keys[i];
        i += 1;
    }

    layered
}

/// A key whose behavior depends on which layer is active.
#[derive(Debug, Deserialize, Clone, Copy, PartialEq)]
pub struct LayeredKey<R: Copy + Debug + PartialEq, const LAYER_COUNT: usize> {
    /// The base key, used when no layers are active.
    pub base: R,
    /// The layered keys, used when the corresponding layer is active.
    #[serde(deserialize_with = "deserialize_layered")]
    #[serde(bound(deserialize = "R: Deserialize<'de>"))]
    pub layered: [Option<R>; LAYER_COUNT],
}

/// Deserialize a [Layers].
fn deserialize_layered<'de, R, L: Layers<R>, D>(deserializer: D) -> Result<L, D::Error>
where
    R: Deserialize<'de>,
    D: serde::Deserializer<'de>,
{
    let keys_vec: heapless::Vec<Option<R>, 64> = Deserialize::deserialize(deserializer)?;

    L::from_iterable(keys_vec).map_err(serde::de::Error::custom)
}

impl<R: Copy + Debug + PartialEq, const LAYER_COUNT: usize> LayeredKey<R, LAYER_COUNT> {
    /// Constructs a new [LayeredKey].
    pub const fn new<const L: usize>(base: R, layered: [Option<R>; L]) -> Self {
        let layered = layered_keys(layered);
        Self { base, layered }
    }
}

impl<R: Copy + Debug + PartialEq, const LAYER_COUNT: usize> LayeredKey<R, LAYER_COUNT> {
    /// Presses the key, using the highest active key, if any.
    fn new_pressed_key<const CONDITIONAL_LAYER_COUNT: usize>(
        &self,
        context: &Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>,
    ) -> key::NewPressedKey<R> {
        let (_layer, passthrough_ref) = self
            .layered
            .highest_active_key(context.layer_state(), context.default_layer)
            .unwrap_or((0, self.base));

        key::NewPressedKey::key(passthrough_ref)
    }
}

/// Events from [ModifierKey] which affect [Context].
#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub enum LayerEvent {
    /// Activates the given layer.
    Activated(LayerIndex),
    /// Deactivates the given layer.
    Deactivated(LayerIndex),
    /// Toggles the given layer.
    Toggled(LayerIndex),
    /// Activates the given layer as sticky (on sticky-mod press).
    StickyActivated(LayerIndex),
    /// Sticky layer modifier released without interruption (sticky committed).
    StickyReleased,
    /// Sticky layer timed out while unused.
    ///
    /// The payload is a generation id used to ignore stale timeouts.
    StickyTimeout(u8),
    /// Sets the active layers to the given set of layers.
    Set(ModifierBitset),
    /// Changes the default layer.
    SetDefault(LayerIndex),
}

/// Struct for layer system pending key state. (No pending state).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct PendingKeyState;

/// Whether the pressed Sticky modifier key is "sticky" or "regular".
#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub enum Behavior {
    /// Key state is "sticky". (Will activate sticky modifier when released).
    Sticky,
    /// Key state is "regular". (No sticky modifiers activated when released).
    Regular,
}

/// [crate::key::KeyState] of [ModifierKey].
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ModifierKeyState {
    behavior: Behavior,
}

impl Default for ModifierKeyState {
    fn default() -> Self {
        Self::new()
    }
}

impl ModifierKeyState {
    /// Constructs a regular ModifierKeyState
    pub fn new() -> Self {
        Self {
            behavior: Behavior::Regular,
        }
    }

    /// Constructs a sticky ModifierKeyState
    pub fn sticky() -> Self {
        Self {
            behavior: Behavior::Sticky,
        }
    }

    /// Handle the given event for the given key.
    pub fn handle_event(
        &mut self,
        keymap_index: u16,
        event: key::Event<LayerEvent>,
        key: &ModifierKey,
    ) -> Option<LayerEvent> {
        match key {
            ModifierKey::Hold(layer, _) => match event {
                key::Event::Input(input::Event::Release { keymap_index: ki }) => {
                    if keymap_index == ki {
                        Some(LayerEvent::Deactivated(*layer))
                    } else {
                        None
                    }
                }
                _ => None,
            },
            ModifierKey::Toggle(_) => None,
            ModifierKey::Sticky(layer) => match event {
                key::Event::Input(input::Event::Press { keymap_index: _ }) => {
                    if self.behavior == Behavior::Sticky {
                        // Another key pressed while sticky modifier is held; make self regular
                        self.behavior = Behavior::Regular;
                        // Change the layer state to *regular*
                        Some(LayerEvent::Activated(*layer))
                    } else {
                        None
                    }
                }
                key::Event::Input(input::Event::Release { keymap_index: ki })
                    if keymap_index == ki =>
                {
                    match self.behavior {
                        Behavior::Regular => Some(LayerEvent::Deactivated(*layer)),
                        // Sticky key tapped (released without interruption):
                        // layer stays sticky; arm optional timeout via context.
                        Behavior::Sticky => Some(LayerEvent::StickyReleased),
                    }
                }
                _ => None,
            },
            ModifierKey::SetActiveLayers(_modifier_bitset) => None,
            ModifierKey::Default(layer) => match event {
                key::Event::Input(input::Event::Release { keymap_index: ki }) => {
                    if keymap_index == ki {
                        Some(LayerEvent::SetDefault(*layer))
                    } else {
                        None
                    }
                }
                _ => None,
            },
        }
    }
}

/// The [key::System] implementation for layer system keys.
///
/// `CONDITIONAL_LAYER_COUNT` is carried so the system's context
/// matches the layered [Config] / [Context] used by the keymap
/// (rules live on context, not system).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct System<
    R: Copy + Debug + PartialEq,
    ModifierKeys: Index<usize, Output = ModifierKey>,
    LayeredKeys: Index<usize, Output = LayeredKey<R, LAYER_COUNT>>,
    const LAYER_COUNT: usize,
    const CONDITIONAL_LAYER_COUNT: usize = 0,
> {
    modifier_keys: ModifierKeys,
    layered_keys: LayeredKeys,
}

impl<
        R: Copy + Debug + PartialEq,
        ModifierKeys: Index<usize, Output = ModifierKey>,
        LayeredKeys: Index<usize, Output = LayeredKey<R, LAYER_COUNT>>,
        const LAYER_COUNT: usize,
        const CONDITIONAL_LAYER_COUNT: usize,
    > System<R, ModifierKeys, LayeredKeys, LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    /// Constructs a new [System] with the given key data.
    pub const fn new(modifier_keys: ModifierKeys, layered_keys: LayeredKeys) -> Self {
        Self {
            modifier_keys,
            layered_keys,
        }
    }
}

impl<
        R: Copy + Debug + PartialEq,
        ModifierKeys: Debug + Index<usize, Output = ModifierKey>,
        LayeredKeys: Debug + Index<usize, Output = LayeredKey<R, LAYER_COUNT>>,
        const LAYER_COUNT: usize,
        const CONDITIONAL_LAYER_COUNT: usize,
    > key::System<R>
    for System<R, ModifierKeys, LayeredKeys, LAYER_COUNT, CONDITIONAL_LAYER_COUNT>
{
    type Ref = Ref;
    type Context = Context<LAYER_COUNT, CONDITIONAL_LAYER_COUNT>;
    type Event = LayerEvent;
    type PendingKeyState = PendingKeyState;
    type KeyState = ModifierKeyState;

    fn new_pressed_key(
        &self,
        keymap_index: u16,
        context: &Self::Context,
        key_ref: Ref,
    ) -> (
        key::PressedKeyResult<R, Self::PendingKeyState, Self::KeyState>,
        key::KeyEvents<Self::Event>,
    ) {
        match key_ref {
            Ref::Modifier(mod_key_index) => {
                let key = self.modifier_keys[mod_key_index as usize];
                let (m_ks, maybe_lmod_ev) = key.new_pressed_key();
                let pks = key::PressedKeyResult::Resolved(m_ks);
                let pke = match maybe_lmod_ev {
                    Some(lmod_ev) => {
                        key::KeyEvents::event(key::Event::key_event(keymap_index, lmod_ev))
                    }
                    None => key::KeyEvents::no_events(),
                };
                (pks, pke)
            }
            Ref::Layered(i) => {
                let key = &self.layered_keys[i as usize];
                let npk = key.new_pressed_key(context);
                (
                    key::PressedKeyResult::NewPressedKey(npk),
                    key::KeyEvents::no_events(),
                )
            }
        }
    }

    fn update_pending_state(
        &self,
        _pending_state: &mut Self::PendingKeyState,
        _keymap_index: u16,
        _context: &Self::Context,
        _key_ref: Ref,
        _event: key::Event<Self::Event>,
    ) -> (Option<key::NewPressedKey<R>>, key::KeyEvents<Self::Event>) {
        panic!()
    }

    fn update_state(
        &self,
        key_state: &mut Self::KeyState,
        key_ref: &Self::Ref,
        _context: &Self::Context,
        keymap_index: u16,
        event: key::Event<Self::Event>,
    ) -> key::KeyEvents<Self::Event> {
        match key_ref {
            Ref::Modifier(mod_key_index) => {
                let mod_key = &self.modifier_keys[*mod_key_index as usize];
                let maybe_ev = key_state.handle_event(keymap_index, event, mod_key);
                maybe_ev.map_or(key::KeyEvents::no_events(), |ev| {
                    key::KeyEvents::event(key::Event::key_event(keymap_index, ev))
                })
            }
            _ => key::KeyEvents::no_events(),
        }
    }

    fn key_output(
        &self,
        key_ref: &Self::Ref,
        _key_state: &Self::KeyState,
    ) -> Option<key::KeyOutput> {
        if let Ref::Modifier(mod_key_index) = key_ref {
            let key = self.modifier_keys[*mod_key_index as usize];
            match key {
                ModifierKey::Hold(_, mods) if mods != key::KeyboardModifiers::NONE => {
                    Some(key::KeyOutput::from_key_modifiers(mods))
                }
                _ => None,
            }
        } else {
            None
        }
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;

    use crate::key::keyboard;

    use crate::key::System as _;

    const LAYER_COUNT: usize = 8;

    type Context = super::Context<LAYER_COUNT>;

    #[test]
    fn test_sizeof_ref() {
        assert_eq!(2, core::mem::size_of::<Ref>());
    }

    #[test]
    fn test_sizeof_modifier_bitset() {
        assert_eq!(8, core::mem::size_of::<ModifierBitset>());
    }

    #[test]
    fn test_sizeof_event() {
        // Firmware RAM budget on 32-bit targets: LayerEvent::Set is a ModifierBitset.
        assert_eq!(12, core::mem::size_of::<LayerEvent>());
    }

    #[test]
    fn deserialize_set_active_layers_record_json() {
        let key: ModifierKey =
            serde_json::from_str(r#"{"SetActiveLayers": {"layers": 5, "mask": 3}}"#).unwrap();
        assert_eq!(
            ModifierKey::SetActiveLayers(ModifierBitset { layers: 5, mask: 3 }),
            key,
        );

        let key: ModifierKey =
            serde_json::from_str(r#"{"SetActiveLayers": {"layers": 5}}"#).unwrap();
        assert_eq!(
            ModifierKey::SetActiveLayers(ModifierBitset {
                layers: 5,
                mask: BITSET_MASK_ALL,
            }),
            key,
        );
    }

    #[test]
    fn test_pressing_hold_modifier_key_emits_event_activate_layer() {
        let layer = 1;
        let key = ModifierKey::hold(layer);

        let (_pressed_key, layer_event) = key.new_pressed_key();

        assert_eq!(Some(LayerEvent::Activated(layer)), layer_event);
    }

    #[test]
    fn test_releasing_hold_modifier_key_emits_event_deactivate_layer() {
        // Assemble: press a Hold layer modifier key
        let layer = 1;
        let key = ModifierKey::hold(layer);
        let keymap_index = 9; // arbitrary
        let (mut pressed_key_state, _) = key.new_pressed_key();

        // Act: the modifier key handles "release key" input event
        let actual_events = pressed_key_state
            .handle_event(
                keymap_index,
                key::Event::Input(input::Event::Release { keymap_index }),
                &key,
            )
            .into_iter()
            .next();

        // Assert: the pressed key should have emitted a layer deactivation event
        let first_ev = actual_events.into_iter().next();
        if let Some(actual_layer_event) = first_ev {
            let expected_layer_event = LayerEvent::Deactivated(layer);
            assert_eq!(expected_layer_event, actual_layer_event);
        } else {
            panic!("Expected Some LayerDeactivated event");
        }
    }

    #[test]
    fn test_releasing_different_hold_modifier_key_does_not_emit_event() {
        // Assemble: press a Hold layer modifier key
        let layer = 1;
        let key = ModifierKey::hold(layer);
        let keymap_index = 9; // arbitrary
        let (mut pressed_key_state, _) = key.new_pressed_key();

        // Act: the modifier key handles "release key" input event for a different key
        let different_keymap_index = keymap_index + 1;
        let different_key_released_ev = key::Event::Input(input::Event::Release {
            keymap_index: different_keymap_index,
        });
        let actual_events = pressed_key_state
            .handle_event(keymap_index, different_key_released_ev, &key)
            .into_iter()
            .next();

        // Assert: the pressed key should not emit an event
        if actual_events.is_some() {
            panic!("Expected no event emitted");
        }
    }

    #[test]
    fn test_context_handling_event_adjusts_active_layers() {
        let mut context = Context::default();

        context.handle_layer_event(LayerEvent::Activated(2));

        let actual_active_layers = &context.active_layers[0..3];
        assert_eq!(
            &[
                Activity::Inactive,
                Activity::Active(ActivationStyle::Regular),
                Activity::Inactive
            ],
            actual_active_layers
        );
    }

    /// Classic tri-layer: layer 3 active iff layers 1 and 2 are both active.
    fn tri_layer_context() -> super::Context<LAYER_COUNT, 1> {
        super::Context::from_config(Config {
            sticky_timeout: None,
            conditional_layers: Slice::from_slice(&[ConditionalLayer::from_if_layers(3, &[1, 2])]),
        })
    }

    #[test]
    fn test_conditional_layer_partial_if_layers_does_not_activate_then() {
        // Assemble
        let mut context = tri_layer_context();

        // Act
        context.handle_layer_event(LayerEvent::Activated(1));

        // Assert
        assert_eq!(Activity::Inactive, context.active_layers[2]);
    }

    #[test]
    fn test_conditional_layer_activates_when_all_if_layers_active() {
        // Assemble
        let mut context = tri_layer_context();
        context.handle_layer_event(LayerEvent::Activated(1));

        // Act
        context.handle_layer_event(LayerEvent::Activated(2));

        // Assert
        assert_eq!(
            Activity::Active(ActivationStyle::Regular),
            context.active_layers[2]
        );
    }

    #[test]
    fn test_conditional_layer_deactivates_when_if_layer_releases() {
        // Assemble
        let mut context = tri_layer_context();
        context.handle_layer_event(LayerEvent::Activated(1));
        context.handle_layer_event(LayerEvent::Activated(2));

        // Act
        context.handle_layer_event(LayerEvent::Deactivated(1));

        // Assert
        assert_eq!(Activity::Inactive, context.active_layers[2]);
    }

    #[test]
    fn test_conditional_layer_nested_fixed_point() {
        // Assemble: C ← A ∧ B; E ← C ∧ D  (layers 1,2 → 3; 3,4 → 5)
        let mut context = super::Context::<LAYER_COUNT, 2>::from_config(Config {
            sticky_timeout: None,
            conditional_layers: Slice::from_slice(&[
                ConditionalLayer::from_if_layers(3, &[1, 2]),
                ConditionalLayer::from_if_layers(5, &[3, 4]),
            ]),
        });
        context.handle_layer_event(LayerEvent::Activated(1));
        context.handle_layer_event(LayerEvent::Activated(2));

        // Act: activate D; fixed-point should turn on C (already) and E
        context.handle_layer_event(LayerEvent::Activated(4));

        // Assert
        assert_eq!(
            [
                Activity::Active(ActivationStyle::Regular), // 3
                Activity::Active(ActivationStyle::Regular), // 4
                Activity::Active(ActivationStyle::Regular), // 5
            ],
            context.active_layers[2..5]
        );
    }

    #[test]
    fn test_conditional_layer_sticky_if_layer_counts_as_active() {
        // Assemble
        let mut context = tri_layer_context();
        context.handle_layer_event(LayerEvent::StickyActivated(1));

        // Act
        context.handle_layer_event(LayerEvent::Activated(2));

        // Assert
        assert_eq!(
            Activity::Active(ActivationStyle::Regular),
            context.active_layers[2]
        );
    }

    #[test]
    fn test_conditional_layer_set_active_layers_reevaluates() {
        // Assemble
        let mut context = tri_layer_context();
        context.handle_layer_event(LayerEvent::Activated(1));
        context.handle_layer_event(LayerEvent::Activated(2));

        // Act: clear layer 1 via Set (mask only layer 1)
        context.handle_layer_event(LayerEvent::Set(ModifierBitset {
            layers: 0,
            mask: 1 << 1,
        }));

        // Assert
        assert_eq!(Activity::Inactive, context.active_layers[2]);
    }

    #[test]
    fn test_pressing_layered_key_acts_as_base_key_when_no_layers_active() {
        // Assemble
        let context = Context::default();
        let expected_ref = keyboard::Ref::KeyCode(0x04);
        let layered_key = LayeredKey::new(
            expected_ref,
            [
                Some(keyboard::Ref::KeyCode(0x05)),
                Some(keyboard::Ref::KeyCode(0x06)),
                Some(keyboard::Ref::KeyCode(0x07)),
            ],
        );
        let system = System::new([], [layered_key]);

        // Act: without activating a layer, press the layered key
        let keymap_index = 9; // arbitrary
        let key_ref = Ref::Layered(0);
        let (pkr, _pke) = system.new_pressed_key(keymap_index, &context, key_ref);

        // Assert
        let expected_pkr =
            key::PressedKeyResult::NewPressedKey(key::NewPressedKey::Key(expected_ref));
        assert_eq!(expected_pkr, pkr,);
    }

    // Terminology:
    //   "defined layer" = LayeredKey.layered[] is Some for that layer;
    //   "active layer" = Context.active_layers[] = true for that layer.

    #[test]
    fn test_pressing_layered_key_falls_through_undefined_active_layers() {
        // Assemble: layered key (with no layered definitions)
        let mut context = Context::default();
        let expected_ref = keyboard::Ref::KeyCode(0x04);
        let layered_key = LayeredKey::new(expected_ref, [None, None, None]);
        let system = System::new([], [layered_key]);

        // Act: activate all layers, press layered key
        context.handle_layer_event(LayerEvent::Activated(1));
        context.handle_layer_event(LayerEvent::Activated(2));
        context.handle_layer_event(LayerEvent::Activated(3));
        let keymap_index = 9; // arbitrary
        let key_ref = Ref::Layered(0);
        let (pkr, _pke) = system.new_pressed_key(keymap_index, &context, key_ref);

        // Assert
        let expected_pkr =
            key::PressedKeyResult::NewPressedKey(key::NewPressedKey::Key(expected_ref));
        assert_eq!(expected_pkr, pkr,);
    }

    #[test]
    fn test_pressing_layered_key_acts_as_highest_defined_active_layer() {
        // Assemble: layered key (with no layered definitions)
        let mut context = Context::default();
        let expected_ref = keyboard::Ref::KeyCode(0x09);
        let layered_key = LayeredKey::new(
            keyboard::Ref::KeyCode(0x04),
            [
                Some(keyboard::Ref::KeyCode(0x05)),
                Some(keyboard::Ref::KeyCode(0x06)),
                Some(expected_ref),
            ],
        );
        let system = System::new([], [layered_key]);

        // Act: activate all layers, press layered key
        context.handle_layer_event(LayerEvent::Activated(1));
        context.handle_layer_event(LayerEvent::Activated(2));
        context.handle_layer_event(LayerEvent::Activated(3));
        let keymap_index = 9; // arbitrary
        let key_ref = Ref::Layered(0);
        let (pkr, _pke) = system.new_pressed_key(keymap_index, &context, key_ref);

        // Assert
        let expected_pkr =
            key::PressedKeyResult::NewPressedKey(key::NewPressedKey::Key(expected_ref));
        assert_eq!(expected_pkr, pkr,);
    }

    #[test]
    fn test_pressing_layered_key_with_some_transparency_acts_as_highest_defined_active_layer() {
        // Assemble: layered key (with no layered definitions)
        let mut context = Context::default();
        let expected_ref = keyboard::Ref::KeyCode(0x09);
        let layered_key = LayeredKey::new(
            keyboard::Ref::KeyCode(0x04),
            [Some(expected_ref), Some(keyboard::Ref::KeyCode(0x06)), None],
        );
        let system = System::new([], [layered_key]);

        // Act: activate all layers, press layered key
        context.handle_layer_event(LayerEvent::Activated(1));
        context.handle_layer_event(LayerEvent::Activated(3));
        let keymap_index = 9; // arbitrary
        let key_ref = Ref::Layered(0);
        let (pkr, _pke) = system.new_pressed_key(keymap_index, &context, key_ref);

        // Assert
        let expected_pkr =
            key::PressedKeyResult::NewPressedKey(key::NewPressedKey::Key(expected_ref));
        assert_eq!(expected_pkr, pkr,);
    }

    #[test]
    fn test_layer_state_array_active_layers() {
        let mut layer_state: [Activity; 5] = [Activity::Inactive; 5];
        layer_state.activate(1, ActivationStyle::Regular);
        layer_state.activate(2, ActivationStyle::Regular);
        layer_state.activate(4, ActivationStyle::Regular);
        let actual_active_layers: Vec<LayerIndex> = layer_state.active_layers().collect();
        let expected_active_layers: Vec<LayerIndex> = vec![4, 2, 1];

        assert_eq!(expected_active_layers, actual_active_layers);
    }

    #[test]
    fn test_pressing_toggle_modifier_key_emits_event_layer_toggled() {
        // Assemble
        let layer = 1;
        let key = ModifierKey::Toggle(layer);

        // Act
        let (_pressed_key, layer_event) = key.new_pressed_key();

        // Assert
        assert_eq!(Some(LayerEvent::Toggled(layer)), layer_event);
    }
}