fix(checkbox): toggle on mouse release (#303)

* fix(checkbox): toggle on mouse release

* fix(checkbox): address review feedback

* test(checkbox): clean rebased integration coverage

Author: RtlZeroMemory

docs/widgets/catalog.json

@@ -337,8 +337,17 @@
     },
     {
       "name": "checkbox",
-      "requiredProps": ["id", "checked", "onChange"],
-      "commonProps": ["label", "disabled"],
+      "requiredProps": ["id", "checked"],
+      "commonProps": [
+        "onChange",
+        "label",
+        "disabled",
+        "focusable",
+        "accessibleLabel",
+        "focusConfig",
+        "dsTone",
+        "dsSize"
+      ],
       "example": "ui.checkbox({ id: 'agree', checked, onChange })"
     },
     {

docs/widgets/checkbox.md

@@ -21,9 +21,12 @@ ui.checkbox({
 |---|---|---|---|
 | `id` | `string` | **required** | Unique identifier for focus and event routing |
 | `checked` | `boolean` | **required** | Current checked state |
+| `focusable` | `boolean` | `true` | Opt out of Tab focus while keeping id-based routing available |
+| `accessibleLabel` | `string` | - | Semantic label used for accessibility and focus announcements |
 | `label` | `string` | - | Optional label displayed next to the box |
 | `onChange` | `(checked: boolean) => void` | - | Called when the user toggles the checkbox |
 | `disabled` | `boolean` | `false` | Disable focus and interaction |
+| `focusConfig` | `FocusConfig` | - | Custom focus appearance configuration |
 | `dsTone` | `"default" \| "primary" \| "danger" \| "success" \| "warning"` | `"default"` | Design-system tone for checked/focus rendering |
 | `dsSize` | `"sm" \| "md" \| "lg"` | `"md"` | Design-system size preset |
 | `key` | `string` | - | Reconciliation key |
@@ -38,7 +41,8 @@ The indicator and label use `checkboxRecipe()` for checked/focus/disabled states
 
 - Focusable when enabled.
 - Toggle with **Space** (and commonly **Enter** depending on terminal key mapping).
-- **Mouse click** focuses and toggles the checkbox.
+- **Mouse down** focuses the checkbox.
+- **Mouse up on the same checkbox** toggles it when `onChange` is provided.
 - **Tab / Shift+Tab** moves focus.
 
 ## Examples
@@ -48,9 +52,19 @@ The indicator and label use `checkboxRecipe()` for checked/focus/disabled states
 ```typescript
 import { ui } from "@rezi-ui/core";
 
-ui.checkbox({ id: "flag", checked: state.flag, onChange: (c) => app.update((s) => ({ ...s, flag: c })) });
+ui.checkbox({
+  id: "flag",
+  checked: state.flag,
+  accessibleLabel: "Feature flag",
+  onChange: (c) => app.update((s) => ({ ...s, flag: c })),
+});
 ```
 
+When `label` is omitted or visually ambiguous, provide `accessibleLabel` so focus
+announcements and other semantic affordances stay clear. Set `focusable: false`
+only when you intentionally want the checkbox out of Tab order while keeping
+id-based routing available.
+
 ### 2) Disabled
 
 ```typescript

packages/core/src/app/__tests__/widgetRenderer.integration.test.ts

@@ -621,6 +621,45 @@ describe("WidgetRenderer integration battery", () => {
     assert.deepEqual(values, []);
   });
 
+  test("checkbox mouse toggles on release over the same target", () => {
+    const backend = createNoopBackend();
+    const renderer = new WidgetRenderer<void>({
+      backend,
+      requestRender: () => {},
+    });
+
+    const changes: boolean[] = [];
+    const vnode = ui.checkbox({
+      id: "agree",
+      checked: false,
+      label: "Agree",
+      onChange: (checked) => changes.push(checked),
+    });
+
+    const res = renderer.submitFrame(
+      () => vnode,
+      undefined,
+      { cols: 40, rows: 5 },
+      defaultTheme,
+      noRenderHooks(),
+    );
+    assert.ok(res.ok);
+
+    const down = renderer.routeEngineEvent(mouseEvent(1, 0, 3, { timeMs: 1, buttons: 1 }));
+    assert.equal(down.action, undefined);
+    assert.deepEqual(changes, []);
+    assert.equal(renderer.getFocusedId(), "agree");
+
+    const up = renderer.routeEngineEvent(mouseEvent(1, 0, 4, { timeMs: 2, buttons: 0 }));
+    assert.deepEqual(up.action, {
+      id: "agree",
+      action: "toggle",
+      checked: true,
+    });
+    assert.deepEqual(changes, [true]);
+    assert.equal(renderer.getFocusedId(), "agree");
+  });
+
   test("select uses Enter and Space to advance like the inline cycler runtime", () => {
     const backend = createNoopBackend();
     const renderer = new WidgetRenderer<void>({

packages/core/src/app/widgetRenderer/routeEngineEvent.ts

@@ -141,6 +141,29 @@ type SplitPaneLastDividerDown = Readonly<{
   timeMs: number;
 }> | null;
 
+function extendMousePressableIds(
+  pressableIds: ReadonlySet<string>,
+  checkboxById: ReadonlyMap<string, CheckboxProps>,
+): ReadonlySet<string> {
+  let merged: Set<string> | null = null;
+
+  for (const [id, checkbox] of checkboxById) {
+    if (
+      typeof checkbox.onChange !== "function" ||
+      checkbox.disabled === true ||
+      pressableIds.has(id)
+    ) {
+      continue;
+    }
+    if (merged === null) {
+      merged = new Set(pressableIds);
+    }
+    merged.add(id);
+  }
+
+  return merged ?? pressableIds;
+}
+
 export type RouteEngineEventOutcome = Readonly<{
   needsRender: boolean;
   action?: RoutedAction;
@@ -677,7 +700,7 @@ export function routeEngineEventImpl(
             pressedId: state.pressedId,
             hitTestTargetId: mouseTargetId,
             enabledById,
-            pressableIds: ctx.pressableIds,
+            pressableIds: extendMousePressableIds(ctx.pressableIds, ctx.checkboxById),
           })
         : EMPTY_ROUTING;
 
@@ -731,6 +754,20 @@ export function routeEngineEventImpl(
 
   if (res.action) {
     if (res.action.action === "press") {
+      const checkbox = ctx.checkboxById.get(res.action.id);
+      if (checkbox && typeof checkbox.onChange === "function" && checkbox.disabled !== true) {
+        const nextChecked = !checkbox.checked;
+        checkbox.onChange(nextChecked);
+        return Object.freeze({
+          needsRender,
+          action: Object.freeze({
+            id: res.action.id,
+            action: "toggle",
+            checked: nextChecked,
+          }),
+        });
+      }
+
       const btn = ctx.buttonById.get(res.action.id);
       if (btn?.onPress) btn.onPress();
       const link = ctx.linkById.get(res.action.id);