Field

Field keeps one control's persistent label, requirement, description, and local error in one coherent input unit. It does not add a second interaction model or an unnecessary accessibility group.

InstallTerminal

npm install @a3s-lab/ui@0.4.0

<form data-workspace-name-form novalidate>
<div class="field">
  <label for="workspace-name">
    Workspace display name <span aria-hidden="true">Required</span>
  </label>
  <input
    id="workspace-name"
    name="workspaceName"
    type="text"
    value="Agent Runtime"
    dir="auto"
    minlength="2"
    maxlength="40"
    autocomplete="organization"
    aria-describedby="workspace-name-help"
    required
  >
  <p id="workspace-name-help" data-field-description>Shown in navigation, invitations, and audit history. Use 2 to 40 characters.</p>
  <p id="workspace-name-error" data-field-message role="alert" hidden>Enter a workspace name between 2 and 40 characters.</p>
</div>
<button class="btn" type="submit">Save name</button>
</form>
<script type="module">
const form = document.querySelector("[data-workspace-name-form]");
const input = form.querySelector("#workspace-name");
const field = input.closest(".field");
const error = form.querySelector("#workspace-name-error");
let composing = false;

const setInvalid = (invalid) => {
  if (invalid) {
    field.dataset.invalid = "true";
    input.setAttribute("aria-invalid", "true");
  } else {
    field.removeAttribute("data-invalid");
    input.removeAttribute("aria-invalid");
  }

  input.setAttribute(
    "aria-describedby",
    invalid
      ? "workspace-name-help workspace-name-error"
      : "workspace-name-help",
  );
  error.hidden = !invalid;
};

form.addEventListener("submit", (event) => {
  event.preventDefault();
  if (composing) {
    input.focus();
    return;
  }

  const length = input.value.trim().length;
  const invalid = length < 2 || length > 40;
  setInvalid(invalid);
  if (invalid) input.focus();
});

input.addEventListener("compositionstart", () => {
  composing = true;
});
input.addEventListener("compositionend", () => {
  composing = false;
});
input.addEventListener("input", (event) => {
  const length = input.value.trim().length;
  if (!event.isComposing && length >= 2 && length <= 40) {
    setInvalid(false);
  }
});
</script>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

Usage

Import Tailwind and one complete A3S UI style bundle:

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

For component-level loading, import the base styles, Field structure, the control structure you use, and one visual style in that order:

@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/field.css";
@import "@a3s-lab/ui/components/input.css";
@import "@a3s-lab/ui/styles/a3s.css";

Use one ordinary <div class="field"> for one control. The native control keeps focus, editing, validation, and form behavior; Field owns only the relationships around it.

<div class="field">
  <label for="workspace-name">Workspace display name</label>
  <input
    id="workspace-name"
    name="workspaceName"
    dir="auto"
    aria-describedby="workspace-name-help"
    required
  />
  <p id="workspace-name-help" data-field-description>
    Shown in navigation and invitations.
  </p>
  <p id="workspace-name-error" data-field-message role="alert" hidden>
    Enter a workspace name.
  </p>
</div>

Do not add role="group" to a single Field. It does not improve the control's name or description and adds an unnamed group to the accessibility tree. When several controls form one question, use native <fieldset> and <legend>.

Parameters

Contract	Purpose
`.field`	Structural root for exactly one control and its supporting relationships
`<label for>`	Persistent visible name; `for` must match the control `id`
`required` or visible optional copy	Communicates whether omission is allowed; decoration alone is insufficient
`data-field-description`	Persistent guidance associated through `aria-describedby`
`data-field-message`	Current local error; reveal only after validation and associate it while visible
`data-invalid="true"`	Visual state on Field after validation has failed
`data-disabled="true"`	Visual availability state paired with native `disabled` on the control
`data-readonly="true"`	Visual availability state paired with native `readonly` on a supported control
`data-orientation="horizontal"`	Aligns one control with its label content when the relationship remains readable
`data-orientation="responsive"`	Stacks first and changes to a horizontal arrangement in a wide Field container

States and variants

Empty and populated are neutral value states. Invalid begins only after validation has run. Disabled and read-only are different availability contracts and must not be reduced to one faded visual treatment.

Required and optional

State the requirement once, next to the label. Native required remains the machine-readable contract; visible copy helps users plan before submission.

Workspace owner

Receives recovery and billing notices.

Internal referenceOptional

Visible only to workspace administrators.

<div class="grid w-full gap-5 sm:grid-cols-2">
    <div class="field">
      <label for="field-required-owner-en">
        Workspace owner
        <span
          class="ms-auto text-xs font-normal text-muted-foreground"
          aria-hidden="true"
        >
          Required
        </span>
      </label>
      <input
        id="field-required-owner-en"
        type="email"
        name="ownerEmail"
        autocomplete="email"
        aria-describedby="field-required-owner-help-en"
        required
      />
      <p id="field-required-owner-help-en" data-field-description>
        Receives recovery and billing notices.
      </p>
    </div>
    <div class="field">
      <label for="field-optional-reference-en">
        Internal reference
        <span class="ms-auto text-xs font-normal text-muted-foreground">
          Optional
        </span>
      </label>
      <input
        id="field-optional-reference-en"
        name="internalReference"
        aria-describedby="field-optional-reference-help-en"
      />
      <p id="field-optional-reference-help-en" data-field-description>
        Visible only to workspace administrators.
      </p>
    </div>
  </div>

Disabled and read-only

Disabled removes a control from focus and form submission. Read-only preserves focus, selection, copying, and form submission. Both states retain their value and explain why editing is unavailable.

<form class="grid w-full gap-5" data-field-availability="en">
    <div class="field" data-disabled="true">
      <label for="field-disabled-slug-en">Archived workspace slug</label>
      <input
        id="field-disabled-slug-en"
        name="archivedSlug"
        value="legacy-runtime"
        aria-describedby="field-disabled-slug-reason-en"
        disabled
      />
      <p id="field-disabled-slug-reason-en" data-field-description>
        Archived identifiers remain visible for audit history and cannot be
        submitted.
      </p>
    </div>
    <div class="field" data-readonly="true">
      <label for="field-readonly-owner-en">Organization owner</label>
      <input
        id="field-readonly-owner-en"
        name="organizationOwner"
        value="owner@example.com"
        aria-describedby="field-readonly-owner-reason-en"
        readonly
      />
      <p id="field-readonly-owner-reason-en" data-field-description>
        This value remains selectable and submitted; only an organization
        transfer can change it.
      </p>
    </div>
  </form>

Use one native Fieldset when several controls answer one question. Each child remains an ordinary Field with one control; no unnamed role="group" wrappers are needed.

Release window

Used to schedule the production handoff.

Date

Local time

<fieldset class="fieldset" aria-describedby="field-release-window-help-en">
    <legend>Release window</legend>
    <p id="field-release-window-help-en">
      Used to schedule the production handoff.
    </p>
    <div class="grid w-full gap-5 sm:grid-cols-2">
      <div class="field">
        <label for="field-release-date-en">Date</label>
        <input
          id="field-release-date-en"
          name="releaseDate"
          type="date"
          required
        />
      </div>
      <div class="field">
        <label for="field-release-time-en">Local time</label>
        <input
          id="field-release-time-en"
          name="releaseTime"
          type="time"
          required
        />
      </div>
    </div>
  </fieldset>

Responsive orientation

Use responsive orientation only when the label, explanation, and control remain one readable relationship. The semantic order never changes.

Artifact retention

Enter the number of days completed task artifacts remain available.

<div class="fieldset">
    <div class="field" data-orientation="responsive">
      <section>
        <label for="field-retention-en">Artifact retention</label>
        <p id="field-retention-help-en" data-field-description>
          Enter the number of days completed task artifacts remain available.
        </p>
      </section>
      <input
        id="field-retention-en"
        name="retentionDays"
        type="number"
        min="1"
        max="365"
        value="30"
        aria-describedby="field-retention-help-en"
        required
      />
    </div>
  </div>

RTL

Layout direction belongs on Field or an ancestor. Machine-oriented values such as email addresses and URLs keep their authored text direction.

البريد الإلكتروني للمالك

يُستخدم لإشعارات الاسترداد وإدارة مساحة العمل.

<div class="field" dir="rtl">
    <label for="field-owner-email-rtl">البريد الإلكتروني للمالك</label>
    <input
      id="field-owner-email-rtl"
      name="ownerEmail"
      type="email"
      value="owner@example.com"
      aria-describedby="field-owner-email-help-rtl"
      dir="ltr"
    />
    <p id="field-owner-email-help-rtl" data-field-description>
      يُستخدم لإشعارات الاسترداد وإدارة مساحة العمل.
    </p>
  </div>

Accessibility

Use one persistent visible label and connect it with for and id. Placeholder text is never the only name.
Keep ordinary guidance in aria-describedby. Append the visible error ID after failed validation and remove it after recovery or reset.
Keep an invalid Field's attempted value, focus the actionable control, name the problem, and give a concrete correction. Color alone is insufficient.
Do not put role="group" on a single Field. Use <fieldset> and <legend> only when multiple controls form one question.
Use disabled only when the value must leave focus and submission. Use readonly when users still need to inspect, select, copy, or submit the value.
Use dir="auto" for user-authored free text whose direction is not known ahead of time. Keep machine-oriented values in their authored direction.
Do not validate, trim, or submit while an IME composition is active. Wait until composition ends.
Verify long localized labels and errors, 390px layouts, 200% zoom, dark mode, RTL, forced colors, coarse pointers, and screen-reader/browser combinations before release.

Field does not own domain validation, server responses, authorization, persistence, submission, or error-summary focus. Form and the host application coordinate those concerns while preserving Field's local relationships.

#Field

#Usage

#Parameters

#States and variants

#Required and optional

#Disabled and read-only

#Related fields

#Responsive orientation

#RTL

#Accessibility