fix(field): define footer behavior and styling contract (#310)

RtlZeroMemory · web-flow · commit 0d32cbde537a · 2026-03-19T12:49:34.000+04:00
* fix(field): define footer behavior and styling contract

* test(field): address review feedback
diff --git a/docs/widgets/catalog.json b/docs/widgets/catalog.json
@@ -297,7 +297,7 @@
       "name": "field",
       "requiredProps": ["label", "children"],
       "commonProps": ["required", "error", "hint"],
-      "example": "ui.field({ label: 'Email', children: ui.input('email', '') })"
+      "example": "ui.field({ label: 'Email', children: ui.input({ id: 'email', value: '' }) })"
     },
     {
       "name": "select",
diff --git a/docs/widgets/field.md b/docs/widgets/field.md
@@ -33,10 +33,14 @@ form.field("name", { label: "Name", required: true, hint: "Your display name" })
 | `required` | `boolean` | `false` | Show required indicator |
 | `error` | `string` | - | Error message |
 | `hint` | `string` | - | Helper text |
+| `key` | `string` | - | Reconciliation key |
 
 ## Notes
 
 - The wrapped child remains the focusable element.
+- `Field` renders at most one footer line. A non-empty `error` takes precedence; otherwise `hint` is shown.
+- An empty-string `error` is treated as absent, so `hint` still renders when provided.
+- Footer colors come from the active theme. The exported field style helpers are structural presets, not fixed color tokens.
 - Use `Field` to keep label, hint, and error layout consistent across forms.
 
 ## Related
diff --git a/packages/core/etc/core.api.md b/packages/core/etc/core.api.md
@@ -2188,7 +2188,7 @@ export type FgTokens = Readonly<{
 
 // @public
 export const FIELD_ERROR_STYLE: Readonly<{
-    fg: number;
+    bold: true;
 }>;
 
 // @public
@@ -2674,6 +2674,9 @@ export function getDefaultFocusConfig(kind: string): FocusConfig;
 // @public
 export function getExpandIndicator(hasChildren: boolean, isExpanded: boolean, isLoading: boolean): string;
 
+// @public
+export function getFieldFooterText(error: string | undefined, hint: string | undefined): string | undefined;
+
 // @public
 export function getFilteredItems(sources: readonly CommandSource[], query: string): Promise<readonly CommandItem[]>;
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -1055,6 +1055,7 @@ export {
   FIELD_HINT_STYLE,
   FIELD_LABEL_STYLE,
   REQUIRED_INDICATOR,
+  getFieldFooterText,
   shouldShowError,
 } from "./widgets/field.js";
 
diff --git a/packages/core/src/renderer/renderToDrawlist/widgets/renderFormWidgets.ts b/packages/core/src/renderer/renderToDrawlist/widgets/renderFormWidgets.ts
@@ -14,6 +14,14 @@ import {
   sliderRecipe,
 } from "../../../ui/recipes.js";
 import { DEFAULT_PLACEHOLDER, getSelectDisplayText } from "../../../widgets/select.js";
+import {
+  FIELD_ERROR_STYLE,
+  FIELD_HINT_STYLE,
+  FIELD_LABEL_STYLE,
+  buildFieldLabel,
+  getFieldFooterText,
+  shouldShowError,
+} from "../../../widgets/field.js";
 import {
   DEFAULT_SLIDER_TRACK_WIDTH,
   formatSliderValue,
@@ -822,16 +830,22 @@ export function renderFormWidgets(
       const error = typeof props.error === "string" ? props.error : undefined;
       const hint = typeof props.hint === "string" ? props.hint : undefined;
 
-      const labelText = required ? `${label} *` : label;
+      const labelText = buildFieldLabel(label, required);
+      const showError = shouldShowError(error);
+      const footer = getFieldFooterText(error, hint);
+      const labelStyle = mergeTextStyle(parentStyle, FIELD_LABEL_STYLE);
       builder.pushClip(rect.x, rect.y, rect.w, rect.h);
-      builder.drawText(rect.x, rect.y, truncateToWidth(labelText, rect.w), parentStyle);
+      builder.drawText(rect.x, rect.y, truncateToWidth(labelText, rect.w), labelStyle);
       if (rect.h >= 2) {
         const footerY = rect.y + rect.h - 1;
-        const footer = error ?? hint;
         if (footer) {
+          const footerBaseStyle = showError ? FIELD_ERROR_STYLE : FIELD_HINT_STYLE;
+          const footerColorStyle = showError
+            ? { fg: theme.colors.danger }
+            : { fg: theme.colors.muted };
           const footerStyle = mergeTextStyle(
-            parentStyle,
-            error ? { fg: theme.colors.danger } : { fg: theme.colors.muted },
+            mergeTextStyle(parentStyle, footerBaseStyle),
+            footerColorStyle,
           );
           builder.drawText(rect.x, footerY, truncateToWidth(footer, rect.w), footerStyle);
         }
diff --git a/packages/core/src/widgets/__tests__/formWidgets.test.ts b/packages/core/src/widgets/__tests__/formWidgets.test.ts
@@ -5,6 +5,8 @@
  */
 
 import { assert, describe, test } from "@rezi-ui/testkit";
+import { createTestRenderer } from "../../testing/renderer.js";
+import { darkTheme } from "../../theme/presets.js";
 import {
   CHECKBOX_CHECKED,
   CHECKBOX_DISABLED_CHECKED,
@@ -14,7 +16,15 @@ import {
   getCheckboxIndicator,
   toggleCheckbox,
 } from "../checkbox.js";
-import { REQUIRED_INDICATOR, buildFieldLabel, shouldShowError } from "../field.js";
+import {
+  FIELD_ERROR_STYLE,
+  FIELD_HINT_STYLE,
+  FIELD_LABEL_STYLE,
+  REQUIRED_INDICATOR,
+  buildFieldLabel,
+  getFieldFooterText,
+  shouldShowError,
+} from "../field.js";
 import {
   RADIO_SELECTED,
   RADIO_UNSELECTED,
@@ -57,6 +67,52 @@ describe("field widget utilities", () => {
   test("shouldShowError returns true for non-empty string", () => {
     assert.equal(shouldShowError("Required"), true);
   });
+
+  test("getFieldFooterText prefers non-empty error over hint", () => {
+    assert.equal(getFieldFooterText("Required", "Helpful hint"), "Required");
+  });
+
+  test("getFieldFooterText falls back to hint when error is empty", () => {
+    assert.equal(getFieldFooterText("", "Helpful hint"), "Helpful hint");
+  });
+
+  test("field helper styles stay theme-agnostic", () => {
+    assert.deepEqual(FIELD_LABEL_STYLE, { bold: true });
+    assert.deepEqual(FIELD_ERROR_STYLE, { bold: true });
+    assert.deepEqual(FIELD_HINT_STYLE, { dim: true });
+  });
+
+  test("field renderer shows error footer before hint and falls back from empty error to hint", () => {
+    const renderer = createTestRenderer({
+      viewport: { cols: 40, rows: 6 },
+      theme: darkTheme,
+    });
+
+    const withError = renderer.render(
+      ui.field({
+        label: "Name",
+        error: "Required",
+        hint: "Enter your name",
+        children: ui.text("abcdefghijklmnopqrst"),
+      }),
+    );
+    const withEmptyError = renderer.render(
+      ui.field({
+        label: "Name",
+        error: "",
+        hint: "Enter your name",
+        children: ui.text("abcdefghijklmnopqrst"),
+      }),
+    );
+
+    const withErrorText = withError.toText();
+    const withEmptyErrorText = withEmptyError.toText();
+
+    assert.ok(withErrorText.includes("Required"));
+    assert.ok(!withErrorText.includes("Enter your name"));
+    assert.ok(withEmptyErrorText.includes("Enter your name"));
+    assert.ok(!withEmptyErrorText.includes("Required"));
+  });
 });
 
 describe("select widget utilities", () => {
diff --git a/packages/core/src/widgets/field.ts b/packages/core/src/widgets/field.ts
@@ -8,7 +8,6 @@
  * @see docs/widgets/field.md (GitHub issue #119)
  */
 
-import { rgb } from "./style.js";
 import type { FieldProps, VNode } from "./types.js";
 
 /** Character used to indicate required fields. */
@@ -21,7 +20,7 @@ export const FIELD_LABEL_STYLE = Object.freeze({
 
 /** Default styles for field error. */
 export const FIELD_ERROR_STYLE = Object.freeze({
-  fg: rgb(255, 0, 0),
+  bold: true,
 });
 
 /** Default styles for field hint. */
@@ -53,6 +52,17 @@ export function shouldShowError(error: string | undefined): boolean {
   return error !== undefined && error !== "";
 }
 
+/**
+ * Resolve the footer text shown below a field.
+ * Non-empty errors take precedence; otherwise the hint is shown.
+ */
+export function getFieldFooterText(
+  error: string | undefined,
+  hint: string | undefined,
+): string | undefined {
+  return shouldShowError(error) ? error : hint;
+}
+
 /**
  * Create a VNode for a field wrapper.
  * This creates the structure: column(label, children, error?, hint?)

Original file line number	Diff line number	Diff line change
`@@ -297,7 +297,7 @@`
`297`	`297`	`"name": "field",`
`298`	`298`	`"requiredProps": ["label", "children"],`
`299`	`299`	`"commonProps": ["required", "error", "hint"],`
`300`		`- "example": "ui.field({ label: 'Email', children: ui.input('email', '') })"`
	`300`	`+ "example": "ui.field({ label: 'Email', children: ui.input({ id: 'email', value: '' }) })"`
`301`	`301`	`},`
`302`	`302`	`{`
`303`	`303`	`"name": "select",`