@estiva-app/ui 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",
@@ -42,12 +42,16 @@
     "@storybook/addon-docs": "^10.5.10",
     "@storybook/react-vite": "^10.5.10",
     "@tabler/icons-react": "^3.41.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "autoprefixer": "^10.4.27",
     "esbuild": "^0.28.0",
+    "jsdom": "^30.0.1",
     "postcss": "^8.5.8",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",

package/src/Field.test.tsx

@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+/**
+ * The label names its control — SHA-17.
+ *
+ * It did not. `Field` rendered a `<label>` with no `htmlFor` and the control as
+ * its *sibling*, so there was neither an explicit nor an implicit association:
+ * a screen reader announced an unlabelled edit box, and clicking the label
+ * focused nothing.
+ *
+ * These are the first DOM tests in this package, and they exist because the
+ * defect cannot be seen without a document. It surfaced in a *consumer's* test
+ * — `getByLabelText(/title/i)` in Peek's ActionFormPanel suite, failing with
+ * "Found a label with the text of: /title/i, however no form control was found
+ * associated to that label". That message is the bug stated precisely, and the
+ * consumer worked around it by querying by role. The guard belongs here, where
+ * the next primitive added under Field will meet it.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import { Field } from './Field'
+import { TextInput } from './TextInput'
+import { Textarea } from './Textarea'
+
+// Testing Library registers its own cleanup only when vitest runs with
+// `globals: true`, and this package does not — so the first two tests passed,
+// the third found two elements labelled "Title", and the failure read like a
+// bug in the component.
+afterEach(cleanup)
+
+describe('Field', () => {
+  it('names a TextInput, so it is reachable by its label', () => {
+    render(
+      <Field label="Title">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    expect(screen.getByLabelText('Title').tagName).toBe('INPUT')
+  })
+
+  it('names a Textarea too', () => {
+    render(
+      <Field label="Description">
+        <Textarea defaultValue="" />
+      </Field>,
+    )
+    expect(screen.getByLabelText('Description').tagName).toBe('TEXTAREA')
+  })
+
+  it('points the label at the control it wraps, not at some other field', () => {
+    // Two Fields on one form is the case a single hardcoded id gets wrong, and
+    // `useId` is what makes it right. Asserted because "it works with one
+    // field" is the version of this that ships broken.
+    const { container } = render(
+      <form>
+        <Field label="Title">
+          <TextInput defaultValue="" />
+        </Field>
+        <Field label="Description">
+          <Textarea defaultValue="" />
+        </Field>
+      </form>,
+    )
+    const labels = [...container.querySelectorAll('label')]
+    const ids = labels.map((l) => l.getAttribute('for'))
+    expect(ids.filter(Boolean)).toHaveLength(2)
+    expect(new Set(ids).size).toBe(2)
+    expect(screen.getByLabelText('Title')).toBe(container.querySelector(`#${CSS.escape(ids[0]!)}`))
+    expect(screen.getByLabelText('Description')).toBe(container.querySelector(`#${CSS.escape(ids[1]!)}`))
+  })
+
+  it('wins over an id the caller put on the control, rather than breaking the pair', () => {
+    // The first version of this asserted the opposite — that a control keeps
+    // its own id inside a Field — and it failed with this ticket's own error
+    // message, because the label went on pointing at the generated id. Two
+    // halves of one association cannot be set from two places.
+    //
+    // So the Field wins, and `htmlFor` below is how a caller chooses. Silently
+    // overriding an id is a smaller surprise than silently unlabelling a
+    // control, and only one of the two is invisible until somebody uses a
+    // screen reader.
+    render(
+      <Field label="Title">
+        <TextInput id="chosen-by-the-caller" defaultValue="" />
+      </Field>,
+    )
+    const input = screen.getByLabelText('Title')
+    expect(input.tagName).toBe('INPUT')
+    expect(input.id).not.toBe('chosen-by-the-caller')
+  })
+
+  it('lets the Field be told the id instead, for the same reason', () => {
+    render(
+      <Field label="Title" htmlFor="named-outside">
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    expect(screen.getByLabelText('Title').id).toBe('named-outside')
+  })
+
+  it('leaves a control outside a Field alone', () => {
+    // `useFieldControlId` returns undefined outside a provider, so nothing
+    // acquires a stray id — a control with an id it did not ask for is its own
+    // small bug.
+    const { container } = render(<TextInput defaultValue="" />)
+    expect(container.querySelector('input')?.getAttribute('id')).toBeNull()
+  })
+
+  it('still marks a required field, which was the only thing it did before', () => {
+    render(
+      <Field label="Title" required>
+        <TextInput defaultValue="" />
+      </Field>,
+    )
+    expect(screen.getByText('*')).toBeTruthy()
+    expect(screen.getByLabelText(/Title/).tagName).toBe('INPUT')
+  })
+})

package/src/Field.tsx

@@ -1,24 +1,78 @@
-import type { ReactNode } from 'react'
+import { createContext, useContext, useId, type ReactNode } from 'react'
 
 /**
- * Peek's Field (2026-08-28), verbatim: a label over a control, 8px apart,
- * with a red asterisk when required. The label is the `input-label` type
- * token as a plain class, never merged.
+ * The id of the control this Field labels.
+ *
+ * **A control has to opt in by calling `useFieldControlId`.** The automatic
+ * alternative is nesting the control inside the `<label>`, which associates
+ * anything by construction and needs no cooperation — and it is not used here,
+ * because a control that is *both* nested in a label and named by its `htmlFor`
+ * can receive two activations from one click. That is a real hazard for a
+ * checkbox and a latent one for everything else, and this library has a
+ * `Checkbox`.
+ *
+ * So: one explicit mechanism, and a test that pins it for every primitive that
+ * uses it (`Field.test.tsx`). A new primitive that renders a labelable element
+ * calls this hook and spreads the result; one that does not is unlabelled, and
+ * the test is where that gets noticed.
+ */
+const FieldControlIdContext = createContext<string | undefined>(undefined)
+
+/**
+ * The id a surrounding `Field` wants this control to have, falling back to the
+ * caller's own outside one.
+ *
+ * **Inside a Field, the Field wins**, which is the opposite of what I wrote
+ * first and the test caught within the minute. Letting a control's own `id`
+ * take precedence leaves the label's `htmlFor` pointing at the id the Field
+ * generated and the control answering to a different one — which is this
+ * ticket's defect exactly, reproduced by the fix for it, and it fails with the
+ * same message: *"Found a label with the text of: Title, however no form
+ * control was found associated to that label."*
+ *
+ * A caller who needs to choose the id names it on the Field (`htmlFor`), which
+ * is the one place that can set both halves. Outside a Field there is nothing
+ * to disagree with, so the caller's id is used.
+ */
+export function useFieldControlId(ownId?: string): string | undefined {
+  const fromField = useContext(FieldControlIdContext)
+  return fromField ?? ownId
+}
+
+/**
+ * Peek's Field (2026-08-28): a label over a control, 8px apart, with a red
+ * asterisk when required. The label is the `input-label` type token as a plain
+ * class, never merged.
+ *
+ * The label names its control (SHA-17). It did not, and the control was a
+ * *sibling* of the label with no `htmlFor`, so there was neither an explicit
+ * nor an implicit association: a screen reader announced an unlabelled edit
+ * box and clicking the label focused nothing.
  */
 export interface FieldProps {
   label: string
   required?: boolean
+  /**
+   * Override the generated id. Only needed when something outside has to name
+   * the control — an `aria-describedby` elsewhere, or a form library.
+   */
+  htmlFor?: string
   children: ReactNode
 }
 
-export function Field({ label, required = false, children }: FieldProps) {
+export function Field({ label, required = false, htmlFor, children }: FieldProps) {
+  const generated = useId()
+  const id = htmlFor ?? generated
   return (
     <div className="flex flex-col gap-2">
-      <label className={`text-input-label text-text-primary${required ? ' flex items-center' : ''}`}>
+      <label
+        htmlFor={id}
+        className={`text-input-label text-text-primary${required ? ' flex items-center' : ''}`}
+      >
         {label}
         {required && <span className="text-error-default ml-0.5">*</span>}
       </label>
-      {children}
+      <FieldControlIdContext.Provider value={id}>{children}</FieldControlIdContext.Provider>
     </div>
   )
 }

package/src/TextInput.tsx

@@ -1,5 +1,6 @@
 import { forwardRef, type InputHTMLAttributes } from 'react'
 import { cn } from './cn'
+import { useFieldControlId } from './Field'
 
 /**
  * Peek's TextInput (2026-08-28): the inset field with a 8px radius, 14px
@@ -10,10 +11,13 @@ import { cn } from './cn'
  */
 export type TextInputProps = InputHTMLAttributes<HTMLInputElement>
 
-export const TextInput = forwardRef<HTMLInputElement, TextInputProps>(function TextInput({ className, type = 'text', ...props }, ref) {
+export const TextInput = forwardRef<HTMLInputElement, TextInputProps>(function TextInput({ className, type = 'text', id, ...props }, ref) {
+  // A surrounding Field names this control (SHA-17); an explicit id still wins.
+  const controlId = useFieldControlId(id)
   return (
     <input
       ref={ref}
+      id={controlId}
       type={type}
       className={cn(
         'bg-bg-inset border border-border-default focus:border-border-focus rounded-lg px-3 py-2',

package/src/Textarea.tsx

@@ -1,5 +1,6 @@
 import { forwardRef, type TextareaHTMLAttributes } from 'react'
 import { cn } from './cn'
+import { useFieldControlId } from './Field'
 
 /**
  * Peek's Textarea (2026-08-28), verbatim: TextInput's look on a textarea
@@ -7,10 +8,13 @@ import { cn } from './cn'
  */
 export type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>
 
-export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea({ className, ...props }, ref) {
+export const Textarea = forwardRef<HTMLTextAreaElement, TextareaProps>(function Textarea({ className, id, ...props }, ref) {
+  // A surrounding Field names this control (SHA-17); an explicit id still wins.
+  const controlId = useFieldControlId(id)
   return (
     <textarea
       ref={ref}
+      id={controlId}
       className={cn(
         'bg-bg-inset border border-border-default focus:border-border-focus rounded-lg px-3 py-2',
         'text-[14px] leading-[1.4] font-normal text-text-primary placeholder:text-text-muted',

package/src/index.ts

@@ -20,7 +20,7 @@ export { ChipInput, InputChip, type ChipInputOption, type ChipInputProps, type I
 export { IconButton, type IconButtonProps, type IconButtonVariant } from './IconButton'
 export { IdentityMenu, IdentityPanel, type Identity, type IdentityMenuProps, type IdentityPanelProps } from './IdentityMenu'
 export { Tooltip, WithTooltip, type TooltipProps, type WithTooltipProps } from './Tooltip'
-export { Field, type FieldProps } from './Field'
+export { Field, useFieldControlId, type FieldProps } from './Field'
 export { Select, type SelectOption, type SelectProps } from './Select'
 export { TextInput, type TextInputProps } from './TextInput'
 export { Textarea, type TextareaProps } from './Textarea'