fix(field): don't render an empty label element

.changeset/field-empty-label.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/kumo": patch
+---
+
+`Field` no longer renders a `<label>` when it would be empty: when `label` and `labelTooltip` are each `undefined`, `null`, a boolean or `""`, and there is no "(optional)" indicator. This fixes `Input`, `InputArea` and `TagInput` without a `label` but with a description or error: they no longer show an empty row above the control, and their `aria-label` is no longer replaced by an empty accessible name.

packages/kumo/src/components/field/field.test.tsx

@@ -25,4 +25,57 @@ describe("Field", () => {
       screen.getByRole("button", { name: "Mais informações" }),
     ).toBeTruthy();
   });
+
+  it.each([
+    ["undefined", undefined],
+    ["null", null],
+    ["true", true],
+    ["false", false],
+    ["an empty string", ""],
+  ])("renders no label element when label is %s", (_, label) => {
+    const { container } = render(
+      <Field label={label} description="Help text">
+        <input aria-label="Name" />
+      </Field>,
+    );
+
+    expect(container.querySelector("label")).toBeNull();
+    expect(screen.getByText("Help text")).toBeTruthy();
+    expect(screen.getByRole("textbox", { name: "Name" })).toBeTruthy();
+  });
+
+  it.each([
+    ["text", "Name", {}],
+    ["the number 0", 0, {}],
+    ["only an optional indicator", undefined, { required: false }],
+    ["only a tooltip", undefined, { labelTooltip: "More" }],
+  ])("keeps the label element for %s", (_, label, props) => {
+    const { container } = render(
+      <Field label={label} {...props}>
+        <input />
+      </Field>,
+    );
+
+    expect(container.querySelector("label")).not.toBeNull();
+  });
+
+  it("renders no label element for an empty tooltip", () => {
+    const { container } = render(
+      <Field label={undefined} labelTooltip="">
+        <input />
+      </Field>,
+    );
+
+    expect(container.querySelector("label")).toBeNull();
+  });
+
+  it("still hides the label element with hideLabel", () => {
+    const { container } = render(
+      <Field label="Name" hideLabel>
+        <input />
+      </Field>,
+    );
+
+    expect(container.querySelector("label")).toBeNull();
+  });
 });

packages/kumo/src/components/field/field.tsx

@@ -120,6 +120,11 @@ export interface FieldProps extends KumoFieldVariantsProps {
   hideLabel?: boolean;
 }
 
+/** Values React renders as nothing. */
+function rendersNothing(node: ReactNode) {
+  return node == null || typeof node === "boolean" || node === "";
+}
+
 /**
  * Form field wrapper that provides a label, optional description, and error display
  * around any form control. Built on Base UI Field primitives.
@@ -143,10 +148,14 @@ export function Field({
 }: FieldProps) {
   // Show "(optional)" when required is explicitly false
   const showOptional = required === false;
+  // An empty <label> still takes a grid row and, through aria-labelledby,
+  // overrides the control's own aria-label with an empty name.
+  const hasLabelContent =
+    !rendersNothing(label) || showOptional || !rendersNothing(labelTooltip);
 
   return (
     <FieldBase.Root className={fieldVariants({ controlFirst })}>
-      {!hideLabel && (
+      {!hideLabel && hasLabelContent && (
         <FieldBase.Label className="m-0 text-base font-medium text-kumo-default select-none">
           <Label showOptional={showOptional} tooltip={labelTooltip} asContent>
             {label}

packages/kumo/src/components/input/input.test.tsx

@@ -400,4 +400,23 @@ describe("InputArea", () => {
     render(<InputArea ref={ref} aria-label="Notes" autoResize />);
     expect(ref.current).toBeInstanceOf(HTMLTextAreaElement);
   });
+
+  it.each([
+    ["description", { description: "Help text" }],
+    ["error", { error: "Required" }],
+  ])("keeps its aria-label as the name with only a %s", (_, props) => {
+    const { container } = render(<Input aria-label="Name" {...props} />);
+
+    expect(container.querySelector("label")).toBeNull();
+    expect(screen.getByRole("textbox", { name: "Name" })).toBeTruthy();
+  });
+
+  it("keeps the InputArea aria-label as the name with only a description", () => {
+    const { container } = render(
+      <InputArea aria-label="Notes" description="Help text" />,
+    );
+
+    expect(container.querySelector("label")).toBeNull();
+    expect(screen.getByRole("textbox", { name: "Notes" })).toBeTruthy();
+  });
 });

packages/kumo/src/components/tag-input/tag-input.test.tsx

@@ -199,6 +199,19 @@ describe("TagInput", () => {
     expect(screen.getByText("Tags").closest("label")?.htmlFor).toBe(input.id);
   });
 
+  it("does not render an empty label when only feedback is shown", () => {
+    const { container } = render(
+      <TagInput aria-label="Tags" validateValue={() => false} />,
+    );
+    fireEvent.change(screen.getByLabelText("Tags"), {
+      target: { value: "bad" },
+    });
+    fireEvent.keyDown(screen.getByLabelText("Tags"), { key: "Enter" });
+    expect(screen.getByText('"bad" is not valid.')).toBeTruthy();
+    expect(container.querySelector("label")).toBeNull();
+    expect(screen.getByRole("textbox", { name: "Tags" })).toBeTruthy();
+  });
+
   it("forwards its ref to the input", () => {
     const ref = createRef<HTMLInputElement>();
     render(<TagInput ref={ref} aria-label="Tags" />);

packages/kumo/src/components/tag-input/tag-input.tsx

@@ -284,7 +284,7 @@ export const TagInput = forwardRef<HTMLInputElement, TagInputProps>(
     if (hasField) {
       return (
         <Field
-          label={label ?? ""}
+          label={label}
           labelTooltip={labelTooltip}
           description={description}
           error={fieldError}