Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

fix(form): labels name and focus the field they belong to

Raulb4d0af46de63
diff --git a/packages/react/src/Command.tsx b/packages/react/src/Command.tsx
index 3b44a07cee..8c5a179d75 100644
--- a/packages/react/src/Command.tsx
+++ b/packages/react/src/Command.tsx
@@ -16,6 +16,7 @@ import type {
import { forwardRef } from "react";
import { LuChevronDown } from "react-icons/lu";
import { RxMagnifyingGlass } from "react-icons/rx";
+import { useFormControlLabelledBy } from "./Form/useFormControl";
import { Modal, ModalContent, ModalTitle } from "./Modal";
import { cn } from "./utils/cn";
import { HitArea, useViewport } from "./Viewport";
@@ -370,6 +371,7 @@ const CommandTrigger = forwardRef<ElementRef<"button">, CommandTriggerProps>(
// Only mounted on phones: the trigger's `[&>span]:line-clamp-1` would
// otherwise un-hide the hit-area span on desktop.
const { isPhone } = useViewport();
+ const labelledBy = useFormControlLabelledBy(props);
return (
<button
ref={ref}
@@ -382,6 +384,7 @@ const CommandTrigger = forwardRef<ElementRef<"button">, CommandTriggerProps>(
className
)}
{...props}
+ aria-labelledby={labelledBy}
>
{asButton && isPhone && <HitArea />}
{children}
diff --git a/packages/react/src/Form/FormControl.tsx b/packages/react/src/Form/FormControl.tsx
index 0b2061282d..83b0a245d0 100644
--- a/packages/react/src/Form/FormControl.tsx
+++ b/packages/react/src/Form/FormControl.tsx
@@ -83,6 +83,13 @@ export const useFormControlContext = () => {
return ctx;
};
+/**
+ * The FormControl this element sits in, or `null` outside one. For controls
+ * that are also used on their own, such as the select and combobox triggers.
+ */
+export const useOptionalFormControlContext = () =>
+ useContext(FormControlContext);
+
function useFormControlProvider(props: FormControlContextType) {
const {
id: idProp,
@@ -113,6 +120,13 @@ function useFormControlProvider(props: FormControlContextType) {
*/
const [hasHelpText, setHasHelpText] = useState(false);
+ /**
+ * The id of the rendered `FormLabel`, once it is on screen. Controls that
+ * are not labelable elements (the select and combobox triggers) name
+ * themselves with it through `aria-labelledby`.
+ */
+ const [renderedLabelId, setRenderedLabelId] = useState<string>();
+
// Track whether the form element (e.g, `input`) has focus.
const [isFocused, setFocus] = useState(false);
@@ -141,13 +155,18 @@ function useFormControlProvider(props: FormControlContextType) {
forwardedRef: ForwardedRef<HTMLLabelElement> | null = null
) => ({
...props,
- ref: forwardedRef,
+ ref: mergeRefs(forwardedRef, (node: HTMLLabelElement | null) => {
+ if (!node) return;
+ setRenderedLabelId(node.id);
+ }),
"data-focus": dataAttr(isFocused),
"data-disabled": dataAttr(isDisabled),
"data-invalid": dataAttr(isInvalid),
"data-readonly": dataAttr(isReadOnly),
id: props.id !== undefined ? props.id : labelId,
- htmlFor: id
+ // The field's own id when the caller names it: the form wrappers give
+ // their input `id={name}` and pass `htmlFor={name}`.
+ htmlFor: props.htmlFor ?? id
}),
[id, isDisabled, isFocused, isInvalid, isReadOnly, labelId]
);
@@ -202,6 +221,7 @@ function useFormControlProvider(props: FormControlContextType) {
setHasFeedbackText,
hasHelpText,
setHasHelpText,
+ renderedLabelId,
id,
labelId,
feedbackId,
diff --git a/packages/react/src/Form/FormLabel.tsx b/packages/react/src/Form/FormLabel.tsx
index 2a76a070e2..fa4e926342 100644
--- a/packages/react/src/Form/FormLabel.tsx
+++ b/packages/react/src/Form/FormLabel.tsx
@@ -32,9 +32,7 @@ export const FormLabel = forwardRef<
return (
<label
{...labelProps}
- ref={ref}
className="flex items-center justify-between max-md:gap-2"
- // {...props}
>
<span
className={cn("text-xs font-medium text-muted-foreground", className)}
diff --git a/packages/react/src/Form/useFormControl.tsx b/packages/react/src/Form/useFormControl.tsx
index f217f6c0a2..67d64732e6 100644
--- a/packages/react/src/Form/useFormControl.tsx
+++ b/packages/react/src/Form/useFormControl.tsx
@@ -5,7 +5,10 @@
import { ariaAttr } from "../utils/dom";
import { callAllHandlers } from "../utils/function";
import type { FormControlOptions } from "./FormControl";
-import { useFormControlContext } from "./FormControl";
+import {
+ useFormControlContext,
+ useOptionalFormControlContext
+} from "./FormControl";
export interface UseFormControlProps<T extends HTMLElement>
extends FormControlOptions {
@@ -91,3 +94,19 @@ export function useFormControlProps<T extends HTMLElement>(
onBlur: callAllHandlers(field?.onBlur, onBlur)
};
}
+
+/**
+ * `aria-labelledby` for a control that is not a labelable element, such as a
+ * select or combobox trigger: the FormControl's label, unless the caller
+ * already named the control.
+ */
+export function useFormControlLabelledBy(props: {
+ "aria-label"?: string;
+ "aria-labelledby"?: string;
+}) {
+ const field = useOptionalFormControlContext();
+ if (props["aria-labelledby"] || props["aria-label"]) {
+ return props["aria-labelledby"];
+ }
+ return field?.renderedLabelId;
+}
diff --git a/packages/react/src/Select.tsx b/packages/react/src/Select.tsx
index 87cc6cef23..1560b29f68 100644
--- a/packages/react/src/Select.tsx
+++ b/packages/react/src/Select.tsx
@@ -15,6 +15,7 @@ import {
LuChevronsUpDown,
LuChevronUp
} from "react-icons/lu";
+import { useFormControlLabelledBy } from "./Form/useFormControl";
import { compactPart } from "./MenuSheet";
import {
SelectSheetContent,
@@ -82,6 +83,7 @@ const SelectTrigger = forwardRef<
SelectTriggerProps
>(({ size, className, children, hideIcon, inline, ...props }, ref) => {
const { isPhone } = useViewport();
+ const labelledBy = useFormControlLabelledBy(props);
const Trigger = isPhone ? SelectSheetTrigger : SelectPrimitive.Trigger;
const icon = (
<LuChevronsUpDown className="h-4 w-4 flex-shrink-0 opacity-50" />
@@ -91,6 +93,7 @@ const SelectTrigger = forwardRef<
ref={ref}
className={cn(!inline && selectTriggerVariants({ size }), className)}
{...props}
+ aria-labelledby={labelledBy}
>
{children}
{!hideIcon && !inline ? (
diff --git a/packages/react/src/__tests__/FormControl.test.tsx b/packages/react/src/__tests__/FormControl.test.tsx
new file mode 100644
index 0000000000..656a39a166
--- /dev/null
+++ b/packages/react/src/__tests__/FormControl.test.tsx
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
+// including ports, remain AGPLv3; serving them over a network requires releasing their source.
+
+// @vitest-environment jsdom
+
+import type { ReactElement } from "react";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { CommandTrigger } from "../Command";
+import { FormControl } from "../Form/FormControl";
+import { FormLabel } from "../Form/FormLabel";
+import { Input } from "../Input";
+import { Select, SelectTrigger, SelectValue } from "../Select";
+
+let root: Root | undefined;
+let container: HTMLDivElement | undefined;
+
+beforeAll(() => {
+ (
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+ ).IS_REACT_ACT_ENVIRONMENT = true;
+ // jsdom has no matchMedia; the viewport hook reads it without a provider.
+ window.matchMedia ??= ((query: string) => ({
+ matches: false,
+ media: query,
+ onchange: null,
+ addEventListener: () => undefined,
+ removeEventListener: () => undefined,
+ addListener: () => undefined,
+ removeListener: () => undefined,
+ dispatchEvent: () => false
+ })) as typeof window.matchMedia;
+});
+
+afterEach(() => {
+ act(() => root?.unmount());
+ container?.remove();
+ root = undefined;
+ container = undefined;
+});
+
+function render(ui: ReactElement) {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ act(() => root!.render(ui));
+ return container;
+}
+
+describe("FormLabel", () => {
+ it("points at the field the caller names", () => {
+ const view = render(
+ <FormControl>
+ <FormLabel htmlFor="partId">Part ID</FormLabel>
+ <Input id="partId" />
+ </FormControl>
+ );
+ const label = view.querySelector("label")!;
+ expect(label.getAttribute("for")).toBe("partId");
+ expect(label.control).toBe(view.querySelector("input"));
+ });
+
+ it("points at the FormControl's id when the caller names none", () => {
+ const view = render(
+ <FormControl id="partId">
+ <FormLabel>Part ID</FormLabel>
+ <Input id="partId" />
+ </FormControl>
+ );
+ expect(view.querySelector("label")!.getAttribute("for")).toBe("partId");
+ });
+});
+
+describe("select and combobox triggers", () => {
+ it("take their name from the FormControl's label", () => {
+ const view = render(
+ <>
+ <FormControl>
+ <FormLabel htmlFor="customerId">Customer</FormLabel>
+ <CommandTrigger role="combobox">Select</CommandTrigger>
+ </FormControl>
+ <FormControl>
+ <FormLabel htmlFor="unitOfMeasureCode">Unit</FormLabel>
+ <Select>
+ <SelectTrigger>
+ <SelectValue placeholder="Select" />
+ </SelectTrigger>
+ </Select>
+ </FormControl>
+ </>
+ );
+ const labels = view.querySelectorAll("label");
+ const triggers = view.querySelectorAll('[role="combobox"]');
+ expect(triggers).toHaveLength(2);
+ expect(triggers[0]!.getAttribute("aria-labelledby")).toBe(labels[0]!.id);
+ expect(triggers[1]!.getAttribute("aria-labelledby")).toBe(labels[1]!.id);
+ });
+
+ it("keep a name the caller gave them", () => {
+ const view = render(
+ <FormControl>
+ <FormLabel>Customer</FormLabel>
+ <CommandTrigger role="combobox" aria-label="Pick a customer">
+ Select
+ </CommandTrigger>
+ </FormControl>
+ );
+ const trigger = view.querySelector('[role="combobox"]')!;
+ expect(trigger.getAttribute("aria-label")).toBe("Pick a customer");
+ expect(trigger.hasAttribute("aria-labelledby")).toBe(false);
+ });
+
+ it("are not labelled when the FormControl has no label", () => {
+ const view = render(
+ <FormControl>
+ <CommandTrigger role="combobox">Select</CommandTrigger>
+ </FormControl>
+ );
+ expect(
+ view.querySelector('[role="combobox"]')!.hasAttribute("aria-labelledby")
+ ).toBe(false);
+ });
+});