fix(select): align contract and runtime behavior (#304)

* fix(select): align contract and runtime behavior

* fix(select): update API report

Author: RtlZeroMemory

docs/widgets/catalog.json

@@ -301,8 +301,18 @@
     },
     {
       "name": "select",
-      "requiredProps": ["id", "value", "options", "onChange"],
-      "commonProps": ["placeholder", "disabled"],
+      "requiredProps": ["id", "value", "options"],
+      "commonProps": [
+        "onChange",
+        "placeholder",
+        "disabled",
+        "focusable",
+        "accessibleLabel",
+        "focusConfig",
+        "dsVariant",
+        "dsTone",
+        "dsSize"
+      ],
       "example": "ui.select({ id: 'country', value, options, onChange })"
     },
     {

docs/widgets/select.md

@@ -1,6 +1,6 @@
 # Select
 
-A focusable dropdown selection widget for choosing one value from a list of options.
+A focusable inline selection widget that cycles through one value from a list of options.
 
 ## Usage
 
@@ -24,11 +24,13 @@ ui.select({
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `id` | `string` | **required** | Unique identifier for focus and event routing |
+| `focusable` | `boolean` | `true` | Opt out of Tab focus while keeping id-based routing available |
+| `accessibleLabel` | `string` | - | Semantic label used for accessibility and focus announcements |
 | `value` | `string` | **required** | Currently selected value |
 | `options` | `{ value: string; label: string; disabled?: boolean }[]` | **required** | Available options |
 | `onChange` | `(value: string) => void` | - | Called when selection changes |
 | `disabled` | `boolean` | `false` | Disable focus and interaction |
-| `placeholder` | `string` | - | Text shown when no matching option label is found |
+| `placeholder` | `string` | `"Select..."` | Text shown when the current value has no matching option label |
 | `focusConfig` | `FocusConfig` | - | Control focus visuals; `{ indicator: "none" }` suppresses focused select decoration |
 | `dsVariant` | `"solid" \| "soft" \| "outline" \| "ghost"` | - | Reserved for future select recipes (currently ignored) |
 | `dsTone` | `"default" \| "primary" \| "danger" \| "success" \| "warning"` | - | Reserved for future select recipes (currently ignored) |
@@ -51,9 +53,11 @@ If the active theme does not provide semantic color tokens, selects fall back to
 - Focusable when enabled.
 - **Mouse click** focuses the select widget.
 - Navigate options with **ArrowUp/ArrowDown**.
-- Confirm selection with **Enter**.
+- **Enter** and **Space** advance to the next enabled option.
 - **Tab / Shift+Tab** moves focus to the next/previous widget.
 
+This widget does not open a popup or dropdown list. It renders the current label inline and cycles through enabled options.
+
 ## Examples
 
 ### 1) With a `field` wrapper

packages/core/etc/core.api.md

@@ -5230,7 +5230,6 @@ export type SelectProps = Readonly<{
     onChange?: (value: string) => void;
     disabled?: boolean;
     placeholder?: string;
-    error?: boolean;
     focusConfig?: FocusConfig;
     dsVariant?: WidgetVariant;
     dsTone?: WidgetTone;
@@ -8014,7 +8013,7 @@ export type ZrUiErrorCode = "ZRUI_INVALID_STATE" | "ZRUI_MODE_CONFLICT" | "ZRUI_
 // src/runtime/instances.ts:161:3 - (ae-forgotten-export) The symbol "AppStateSelection" needs to be exported by the entry point index.d.ts
 // src/runtime/localState.ts:401:3 - (ae-forgotten-export) The symbol "TreeFlatCache" needs to be exported by the entry point index.d.ts
 // src/runtime/localState.ts:406:3 - (ae-forgotten-export) The symbol "TreePrefixCache" needs to be exported by the entry point index.d.ts
-// src/runtime/widgetMeta/focusInfo.ts:7:3 - (ae-forgotten-export) The symbol "RuntimeInstance" needs to be exported by the entry point index.d.ts
+// src/runtime/widgetMeta/focusInfo.ts:8:3 - (ae-forgotten-export) The symbol "RuntimeInstance" needs to be exported by the entry point index.d.ts
 // src/testing/renderer.ts:93:3 - (ae-forgotten-export) The symbol "TestRecordedOp" needs to be exported by the entry point index.d.ts
 // src/widgets/composition.ts:88:3 - (ae-forgotten-export) The symbol "UnknownCallback" needs to be exported by the entry point index.d.ts
 // src/widgets/style.ts:26:3 - (ae-forgotten-export) The symbol "UnderlineStyle" needs to be exported by the entry point index.d.ts

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

@@ -621,6 +621,59 @@ describe("WidgetRenderer integration battery", () => {
     assert.deepEqual(values, []);
   });
 
+  test("select uses Enter and Space to advance like the inline cycler runtime", () => {
+    const backend = createNoopBackend();
+    const renderer = new WidgetRenderer<void>({
+      backend,
+      requestRender: () => {},
+    });
+
+    let value = "dark";
+    const values: string[] = [];
+    const view = () =>
+      ui.select({
+        id: "theme",
+        value,
+        options: [
+          { value: "dark", label: "Dark" },
+          { value: "light", label: "Light" },
+          { value: "system", label: "System" },
+        ],
+        onChange: (nextValue) => {
+          value = nextValue;
+          values.push(nextValue);
+        },
+      });
+
+    let res = renderer.submitFrame(
+      () => view(),
+      undefined,
+      { cols: 40, rows: 5 },
+      defaultTheme,
+      noRenderHooks(),
+    );
+    assert.ok(res.ok);
+
+    renderer.routeEngineEvent(keyEvent(3 /* TAB */));
+    assert.equal(renderer.getFocusedId(), "theme");
+
+    renderer.routeEngineEvent(keyEvent(2 /* ENTER */));
+    assert.equal(value, "light");
+
+    res = renderer.submitFrame(
+      () => view(),
+      undefined,
+      { cols: 40, rows: 5 },
+      defaultTheme,
+      noRenderHooks(),
+    );
+    assert.ok(res.ok);
+
+    renderer.routeEngineEvent(keyEvent(32 /* SPACE */));
+    assert.equal(value, "system");
+    assert.deepEqual(values, ["light", "system"]);
+  });
+
   test("focusTrap wraps TAB within active trap", () => {
     const backend = createNoopBackend();
     const renderer = new WidgetRenderer<void>({

packages/core/src/renderer/renderToDrawlist/widgets/renderFormWidgets.ts

@@ -13,6 +13,7 @@ import {
   selectRecipe,
   sliderRecipe,
 } from "../../../ui/recipes.js";
+import { DEFAULT_PLACEHOLDER, getSelectDisplayText } from "../../../widgets/select.js";
 import {
   DEFAULT_SLIDER_TRACK_WIDTH,
   formatSliderValue,
@@ -873,19 +874,13 @@ export function renderFormWidgets(
         !disabled,
       );
       const value = typeof props.value === "string" ? props.value : "";
-      const placeholder = typeof props.placeholder === "string" ? props.placeholder : "Select…";
+      const placeholder =
+        typeof props.placeholder === "string" ? props.placeholder : DEFAULT_PLACEHOLDER;
 
       const options = Array.isArray(props.options)
         ? (props.options as readonly SelectOption[])
         : [];
-      let label = "";
-      for (const opt of options) {
-        if (opt && opt.value === value) {
-          label = opt.label;
-          break;
-        }
-      }
-      if (label.length === 0) label = placeholder;
+      const label = getSelectDisplayText(value, options, placeholder);
 
       const colorTokens = getColorTokens(theme);
       const dsSize = readWidgetSize(props.dsSize) ?? "md";

packages/core/src/runtime/__tests__/widgetMeta.test.ts

@@ -409,6 +409,22 @@ test("widgetMeta: collectAllWidgetMetadata includes accessible focus semantics",
   assert.equal(ageInfo.announcement, "Age — Required");
 });
 
+test("widgetMeta: select visible label falls back to placeholder for unknown value", () => {
+  const vnode = ui.select({
+    id: "theme",
+    value: "missing",
+    placeholder: "Choose a theme",
+    options: [{ value: "dark", label: "Dark" }],
+  });
+
+  const committed = commitTree(vnode);
+  const allMeta = collectAllWidgetMetadata(committed);
+  const info = allMeta.focusInfoById.get("theme");
+  assert.ok(info);
+  assert.equal(info.visibleLabel, "Choose a theme");
+  assert.equal(info.announcement, "Choose a theme");
+});
+
 test("widgetMeta: reusable collector publishes stable snapshots across collects", () => {
   const collector = createWidgetMetadataCollector();
 

packages/core/src/runtime/widgetMeta/focusInfo.ts

@@ -1,3 +1,4 @@
+import { getSelectDisplayText } from "../../widgets/select.js";
 import type { RuntimeInstance } from "../commit.js";
 import { readNonEmptyString } from "./helpers.js";
 
@@ -42,16 +43,13 @@ function readFocusableVisibleLabel(vnode: RuntimeInstance["vnode"]): string | nu
       const options = Array.isArray(props.options)
         ? (props.options as readonly { value?: unknown; label?: unknown }[])
         : [];
-      for (const option of options) {
-        if (
-          typeof option?.value === "string" &&
-          option.value === value &&
-          typeof option.label === "string"
-        ) {
-          return readNonEmptyString(option.label);
-        }
-      }
-      return readNonEmptyString(props.placeholder);
+      return readNonEmptyString(
+        getSelectDisplayText(
+          value,
+          options as readonly { value: string; label: string; disabled?: boolean }[],
+          readNonEmptyString(props.placeholder) ?? undefined,
+        ),
+      );
     }
     case "radioGroup": {
       const props = vnode.props as { value?: unknown; options?: unknown };

packages/core/src/widgets/__tests__/formWidgets.test.ts

@@ -94,9 +94,9 @@ describe("select widget utilities", () => {
     assert.equal(text, "United Kingdom");
   });
 
-  test("getSelectDisplayText returns value for unknown value", () => {
+  test("getSelectDisplayText returns placeholder for unknown value", () => {
     const text = getSelectDisplayText("unknown", options);
-    assert.equal(text, "unknown");
+    assert.equal(text, DEFAULT_PLACEHOLDER);
   });
 
   test("findOptionIndex finds correct index", () => {

packages/core/src/widgets/select.ts

@@ -41,7 +41,7 @@ export function getSelectDisplayText(
   }
 
   const option = options.find((opt) => opt.value === value);
-  return option?.label ?? value;
+  return option?.label ?? placeholder ?? DEFAULT_PLACEHOLDER;
 }
 
 /**

packages/core/src/widgets/types/forms.ts

@@ -48,8 +48,6 @@ export type SelectProps = Readonly<{
   disabled?: boolean;
   /** Placeholder text when no value is selected. */
   placeholder?: string;
-  /** Whether to show the select in an error state. */
-  error?: boolean;
   /** Optional focus appearance configuration. */
   focusConfig?: FocusConfig;
   /** Design system: visual variant (reserved for future select recipes). */