fix(w-anchor): make a control reachable by keyboard and remote, and cost one stop

CHANGELOG.md

@@ -6,6 +6,21 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.
 
 ---
 
+## [Unreleased]
+
+### Added
+
+- **A focused `WAnchor` activates on the keyboard and on a television remote.** `onTap` now answers `ActivateIntent`, which `WidgetsApp` raises for `Enter`, `Space`, numpad `Enter`, the gamepad A button and `select`, the D-pad centre on Android TV and the click on the Apple TV remote. `WAnchor` binds no key of its own, so a key the platform adds later arrives for free. Only `onTap` is bound: `ActivateIntent` means the primary action and there is no second key for `onLongPress` or `onDoubleTap`, which matches every button Flutter ships.
+
+### Fixed
+
+- **One control is one traversal stop, and the focus ring lands on the thing that activates.** `WDiv` wraps itself in a gestureless `WAnchor` whenever its className carries `hover:`, `focus:` or `active:`, and that wrapper was a full focus stop publishing its own state. So `WAnchor(onTap:) > WDiv('focus:ring-2')`, the shape of every ring-styled control, cost two presses of Tab: the first landed on the node carrying the gesture and drew no ring, the second drew the ring on a node `Enter` could not activate. A gestureless wrapper is now a styling wrapper: it is not a traversal stop, and it inherits `focus` and `disabled` from the nearest anchor above it instead of shadowing them. Two shapes are deliberately unchanged: a `WDiv` carrying `focus:` with no anchor above it keeps its own node, because that is how a consumer styles a custom control, and a focusable descendant still lights the wrapper's ring, because `FocusNode.hasFocus` covers descendants and a `WInput` inside a ring-styled `WDiv` has always drawn the ring around the field being typed in.
+- **`disabled:` now fires on a `WDiv` inside a disabled `WAnchor`.** The same shadowing, in a third state: the gestureless wrapper published `isDisabled: false` over a disabled ancestor, so the element carrying `disabled:opacity-50` never saw it. Covered by the same inheritance.
+
+### Added
+
+- **`WindAnchorState.hasPrimaryFocus`**, separating "this element is the focus" from "this element contains the focus". A gestureless wrapper republishes it with the inherited value ORed in, so the signal chains through nesting: a wrapper's own node never holds primary focus, so stopping at it left a ring two wrappers deep dark, and any `hover:` or `active:` class on an intermediate div creates that second wrapper. `isFocused` has always been the second of those, because it comes from `FocusNode.hasFocus`, which is true for an ancestor of the real holder. The distinction is what a styling wrapper has to inherit: a tappable card containing a text field reports focus-within while the user types, so a wrapper inheriting `isFocused` lit its ring while sitting beside the field rather than around it. Defaults to `false`, so nothing that constructs the state by hand has to change.
+
 ## [1.5.2] - 2026-09-08
 
 ### Fixed

README.md

@@ -82,6 +82,7 @@ WDiv(
 | 📱 | **Responsive prefixes** | `sm:`, `md:`, `lg:`, `xl:`, `2xl:` breakpoints, plus custom breakpoints via the theme. |
 | 🌙 | **First-class dark mode** | `dark:` prefix with runtime toggle and automatic system-brightness sync. Every color token carries its `dark:` pair in the same className. |
 | 🎯 | **State prefixes** | `hover:`, `focus:`, `disabled:`, `loading:`, `selected:`, and any custom state. Zero `MouseRegion`, zero `setState`, zero `_isHovered` booleans. |
+| ⌨️ | **Reachable without a pointer** | A `WAnchor` with an `onTap` is one traversal stop, and it activates on `Enter`, `Space`, the gamepad A button and the D-pad centre. The same binding serves a keyboard, a gamepad and a television remote. |
 | 🔌 | **Platform prefixes** | `ios:`, `android:`, `web:`, `mobile:` for conditional styling without a single `if`. Works on all 6 Flutter platforms. |
 | 🎭 | **Customizable theme** | 24 configurable `WindThemeData` fields. Override every token scale: colors, spacing, typography, shadows, breakpoints, animations. Defaults match Tailwind v3 / v4. Define `aliases` to create bare-token className shortcuts expanded before parsing. |
 | 📡 | **Server-driven UI** | `WDynamic` renders widget trees from JSON. Ship UI updates without ship-blocking releases. Whitelisted 13 Wind widgets + 16 Flutter core widgets. |

doc/widgets/w-anchor.md

@@ -7,6 +7,7 @@ The foundational state wrapper that detects user gestures (Hover, Focus, Press)
 - [Props](#props)
 - [Layout Modes](#layout-modes)
 - [Event Handling](#event-handling)
+- [Keyboard and Remote Control](#keyboard-and-remote-control)
 - [State Variants](#state-variants)
 - [Styling Examples](#styling-examples)
 - [All Supported Classes](#all-supported-classes)
@@ -108,6 +109,63 @@ WAnchor(
 )
 ```
 
+## Keyboard and Remote Control
+
+A focused `WAnchor` runs its `onTap` when the user presses the activation key. `WAnchor` binds no key of its own: it answers `ActivateIntent`, which `WidgetsApp` already raises for `Enter`, `Space`, the numeric keypad `Enter`, the gamepad A button and `select`. `select` is the D-pad centre on Android TV and the click on the Apple TV remote, so one binding covers a keyboard, a gamepad and a remote, and a key the platform adds later arrives for free.
+
+```dart
+// Reachable by Tab, activated by Enter, Space or the D-pad centre.
+WAnchor(onTap: play, child: const WText('Play'))
+```
+
+Only `onTap` is bound. `ActivateIntent` means the primary action and there is no second key for a secondary one, so `onLongPress` and `onDoubleTap` stay pointer-only, exactly as they are on Flutter's own buttons.
+
+An anchor with no `onTap`, or a disabled one, binds nothing and lets the key travel on to whatever is above it. That is narrower than it may look: a `CallbackAction` is always enabled and `ShortcutManager` reports a key handled for any enabled action, so binding unconditionally would have made a long-press-only anchor eat the activation key belonging to the row around it, and on web eat `Space`'s scroll with it, because `Space` maps to `PrioritizedIntents([ActivateIntent, ScrollIntent])` and an always-enabled action wins that race.
+
+### One control is one stop
+
+A control has to cost one press of the remote, so only an anchor that carries a gesture is a traversal stop. A gestureless `WAnchor` is a styling wrapper, and it inherits from the nearest anchor above it instead of publishing its own state.
+
+This matters because `WDiv` wraps itself in a gestureless `WAnchor` whenever its className carries `hover:`, `focus:` or `active:`. Without the inheritance, the element carrying `focus:ring-2` would be the one element that could not see the focus:
+
+```dart
+// One stop. Tab lands on the anchor, the ring is drawn on the div, and
+// Enter fires onTap.
+WAnchor(
+  onTap: clear,
+  child: const WDiv(
+    className: 'p-2 rounded-full focus:ring-2 focus:ring-blue-500',
+    child: WIcon(Icons.close),
+  ),
+)
+```
+
+Two shapes are unaffected. A `WDiv` carrying `focus:` with no anchor above it keeps its own focus node, because that is how a consumer styles a custom control. And a focusable descendant still lights the wrapper's ring: `FocusNode.hasFocus` covers descendants, so a `WInput` inside a ring-styled `WDiv` draws the ring around the field the user is typing in.
+
+What the wrapper inherits is deliberately narrow: the ancestor's PRIMARY focus, never its focus-within. It passes that signal on rather than stopping at it, because any `hover:` or `active:` class on a div in between creates a second wrapper whose own node never holds focus, and a ring two wrappers deep would otherwise stay dark. The two are different questions and `WindAnchorState` now exposes both. A tappable card containing a text field reports focus-within the whole time the user types, so a wrapper inheriting that would light up even when it sits *beside* the field rather than around it:
+
+```dart
+// The ring belongs to nothing here, and stays dark while the field has focus.
+WAnchor(
+  onTap: open,
+  child: const WDiv(
+    className: 'flex flex-row',
+    children: <Widget>[
+      WDiv(className: 'p-2 focus:ring-2', child: WText('Label')),
+      WDiv(className: 'flex-1 min-w-0', child: WInput()),
+    ],
+  ),
+)
+```
+
+`hover` is not inherited at all. It is a pointer position, and two siblings inside one anchor legitimately highlight independently.
+
+### What is not here
+
+Wind ships no `FocusTraversalPolicy`. Directional movement is Flutter's default `DirectionalFocusTraversalPolicyMixin`, which scopes left and right to the enclosing horizontal `Scrollable` and up and down to the vertical one, so a stack of horizontal rails behaves reasonably without configuration. Focus memory per region, edge behaviour (wrap, stop or leave) and ordering beyond geometry are a consumer concern today; reach for `FocusTraversalGroup` with your own policy.
+
+One upstream limit is worth knowing before it is diagnosed as a Wind bug: directional traversal cannot reach a list item that has not been built, so focus stops at the edge of a lazy list's cache extent ([flutter/flutter#91741](https://github.com/flutter/flutter/issues/91741)), and it can land on a cached item that is scrolled out of sight ([flutter/flutter#91795](https://github.com/flutter/flutter/issues/91795)).
+
 ## State Variants
 
 `WAnchor` enables several state prefixes for all Wind widgets in its subtree. This allows you to define complex interactive styles easily.
@@ -160,6 +218,7 @@ While `WAnchor` does not take a `className`, it facilitates the use of these sta
 | Interaction | `hover:`, `focus:`, `disabled:` |
 | Custom States | Any value passed to the `states` prop (e.g., `active:`, `error:`) |
 | Gestures | Enables `onTap`, `onLongPress`, `onDoubleTap` |
+| Keys | `onTap` also runs on `ActivateIntent` (`Enter`, `Space`, gamepad A, D-pad `select`) |
 
 ## Customizing Theme
 

doc/widgets/w-div.md

@@ -116,6 +116,8 @@ Precedence: inline `backgroundColor` wins over any `bg-*` / `dark:bg-*` resolved
 
 That wrap is styling only: the auto-wrapped `WAnchor` carries no gesture, so it publishes no `button` node to assistive technology. A `WDiv` with `hover:bg-slate-100` styles on hover and still announces as whatever its content is, rather than as a control that does nothing when activated.
 
+It is not a keyboard or remote stop either. Inside a tappable `WAnchor` the wrapper inherits that anchor's `focus` and `disabled` rather than claiming a stop of its own, so the control is reached once and the ring is drawn on the element the user activates. Standing alone, with no anchor above it, the `WDiv` keeps its own focus node and stays reachable. `hover` is never inherited, so sibling divs inside one anchor still highlight independently. See [WAnchor](./w-anchor.md#keyboard-and-remote-control).
+
 For direct gesture support (taps, long presses) or to create semantic buttons, use [WAnchor](w-anchor.md) or [WButton](w-button.md).
 
 <a name="state-variants"></a>

example/lib/pages/interactivity/anchor_basic.dart

@@ -105,6 +105,27 @@ class AnchorBasicExamplePage extends StatelessWidget {
             ),
           ),
         ),
+        ExampleSection(
+          title: 'Keyboard and Remote',
+          description:
+              'Tab to this button and press Enter or Space. The same binding is the D-pad centre on Android TV. It is one stop, not two: the ring is styled on the inner WDiv and the gesture lives on the anchor.',
+          child: WAnchor(
+            onTap: () {},
+            semanticLabel: 'Play',
+            child: WDiv(
+              className: '''
+                px-4 py-2 rounded-lg duration-200
+                bg-violet-600 dark:bg-violet-500
+                hover:bg-violet-700 dark:hover:bg-violet-400
+                focus:ring-2 focus:ring-violet-400 dark:focus:ring-violet-300
+              ''',
+              child: const WText(
+                'Play',
+                className: 'text-white font-medium',
+              ),
+            ),
+          ),
+        ),
       ],
     );
   }

lib/src/state/wind_anchor_state.dart

@@ -7,7 +7,10 @@ import 'package:flutter/foundation.dart';
 ///
 /// ### Properties:
 /// - **isHovering:** True when mouse is over the widget.
-/// - **isFocused:** True when the widget has keyboard focus.
+/// - **isFocused:** True when the widget, or anything inside it, has keyboard
+///   focus.
+/// - **hasPrimaryFocus:** True when the widget, or the control it decorates,
+///   is the focus. Never true merely because something inside it is.
 /// - **isDisabled:** True when interactions are blocked.
 /// - **customStates:** Set of user-defined states like `selected` or `loading`.
 ///
@@ -17,9 +20,29 @@ class WindAnchorState {
   /// Whether the mouse pointer is hovering over the widget.
   final bool isHovering;
 
-  /// Whether the widget has keyboard focus.
+  /// Whether the widget, or anything inside it, has keyboard focus.
+  ///
+  /// This is focus-WITHIN, because it comes from `FocusNode.hasFocus`, which is
+  /// true for an ancestor of the node that actually holds focus. That is the
+  /// right signal for a ring drawn around a text field's container, and the
+  /// wrong one for asking "is this element the focus".
   final bool isFocused;
 
+  /// Whether this widget, or the control it decorates, is the focus.
+  ///
+  /// Not the same as "this exact node holds focus", and the difference is
+  /// deliberate. A gestureless [WAnchor] cannot request focus at all, so a
+  /// styling wrapper reports the primary focus of the anchor it decorates,
+  /// passing the signal on to any wrapper nested inside it. Without that a ring
+  /// two wrappers deep stayed dark, and one `hover:` class on a div in between
+  /// is enough to create the second wrapper.
+  ///
+  /// What it is never true for is containment. A tappable card holding a text
+  /// field reports [isFocused] the whole time the user types, because that is
+  /// focus-within; this stays false, which is what keeps a wrapper sitting
+  /// BESIDE the field from lighting up with it.
+  final bool hasPrimaryFocus;
+
   /// Whether the widget is disabled and ignoring interactions.
   final bool isDisabled;
 
@@ -38,6 +61,7 @@ class WindAnchorState {
     required this.isHovering,
     required this.isFocused,
     required this.isDisabled,
+    this.hasPrimaryFocus = false,
     this.customStates,
   });
 
@@ -58,6 +82,7 @@ class WindAnchorState {
     return other is WindAnchorState &&
         other.isHovering == isHovering &&
         other.isFocused == isFocused &&
+        other.hasPrimaryFocus == hasPrimaryFocus &&
         other.isDisabled == isDisabled &&
         setEquals(other.customStates, customStates);
   }
@@ -67,6 +92,7 @@ class WindAnchorState {
   int get hashCode =>
       isHovering.hashCode ^
       isFocused.hashCode ^
+      hasPrimaryFocus.hashCode ^
       isDisabled.hashCode ^
       (customStates == null ? 0 : Object.hashAllUnordered(customStates!));
 }