{
  "_copyright": "Copyright (c) 2026, Salesforce, Inc., All rights reserved. For full license text, see the LICENSE.txt file",
  "$schema": "https://slds.lightningdesignsystem.com/schemas/uif-foundation.v1.json",
  "apiVersion": "1.0.0",
  "name": "FormElement",
  "description": "Creates layout for a form element",
  "structure": {
    "name": "root",
    "restrict": [
      "div",
      "fieldset"
    ],
    "description": "Creates layout for a form element",
    "children": [
      {
        "name": "label",
        "restrict": [
          "label",
          "span"
        ],
        "description": "Creates label styles for our form elements",
        "slot": {
          "name": "label",
          "required": true
        },
        "children": [
          {
            "name": "labelRequiredIndicator",
            "restrict": [
              "abbr"
            ],
            "description": "Required asterisk"
          }
        ]
      },
      {
        "name": "legend",
        "restrict": [
          "legend"
        ],
        "description": "The form element label when applied to a legend element",
        "children": [
          {
            "name": "legendRequiredIndicator",
            "restrict": [
              "abbr"
            ],
            "description": "Required asterisk"
          }
        ]
      },
      {
        "name": "helpIcon",
        "restrict": [
          "div"
        ],
        "description": "When an icon sits within a form element wrapper and adjacent to another element inside that wrapper such as a .form-element__label",
        "renderWhen": "slotFilled",
        "slot": {
          "name": "helpIcon"
        },
        "children": [
          {
            "name": "helpIconButton",
            "restrict": [
              "button"
            ],
            "description": "Help-icon trigger button.",
            "children": [
              {
                "name": "helpIconSvg",
                "description": "Help icon svg glyph.",
                "component": "PrimitiveIcon"
              },
              {
                "name": "helpIconAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually hidden label for the help button."
              }
            ]
          },
          {
            "name": "helpTooltip",
            "restrict": [
              "div"
            ],
            "description": "Tooltip popover that surfaces help text on hover/focus of the help button.",
            "children": [
              {
                "name": "helpTooltipBody",
                "restrict": [
                  "div"
                ],
                "description": "Help tooltip body content."
              }
            ]
          }
        ]
      },
      {
        "name": "control",
        "restrict": [
          "div"
        ],
        "description": "Wrapper to any form display element",
        "slot": {
          "name": "default",
          "required": true
        },
        "children": [
          {
            "name": "staticContent",
            "restrict": [
              "div"
            ],
            "description": "Read-only components are used to display immutable data within a form. Initializes read-only form element"
          },
          {
            "name": "editAction",
            "restrict": [
              "button"
            ],
            "description": "Inline-edit trigger button rendered in the read-only view.",
            "renderWhen": {
              "prop": "readonly",
              "eq": "true"
            },
            "children": [
              {
                "name": "editActionSvg",
                "description": "Edit icon svg.",
                "component": "PrimitiveIcon"
              },
              {
                "name": "editActionAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually hidden label for the edit button."
              }
            ]
          }
        ]
      },
      {
        "name": "help",
        "restrict": [
          "div"
        ],
        "description": "Creates inline help styles, sits below .form-element__control",
        "renderWhen": "slotFilled",
        "slot": {
          "name": "help"
        }
      },
      {
        "name": "group",
        "restrict": [
          "div"
        ],
        "description": "Inner wrapper used by deprecated compound layouts to group a stack of compound rows together.",
        "renderWhen": {
          "prop": "layout",
          "eq": "compoundDeprecated"
        }
      },
      {
        "name": "row",
        "restrict": [
          "div"
        ],
        "description": "Single row inside a compound or address form element; lays out sibling form-elements side by side.",
        "children": [
          {
            "name": "rowItem",
            "restrict": [
              "div"
            ],
            "description": "Sizing wrapper around a child form-element inside a compound row.",
            "repeats": true
          }
        ]
      }
    ]
  },
  "states": [
    {
      "name": "required",
      "type": "boolean",
      "aria": "aria-required",
      "description": "Whether the field is required."
    },
    {
      "name": "hasError",
      "type": "boolean",
      "description": "Whether the field has a validation error. When true, the control sets aria-invalid and the help text becomes the error message referenced via aria-describedby."
    },
    {
      "name": "readonly",
      "type": "boolean",
      "aria": "aria-readonly",
      "description": "Whether the field is in read-only display mode (renders staticContent instead of a control)."
    },
    {
      "name": "disabled",
      "type": "boolean",
      "aria": "aria-disabled",
      "description": "Whether the form element is disabled."
    },
    {
      "name": "editing",
      "type": "boolean",
      "description": "Whether the form element is in inline-edit mode (control replaces staticContent)."
    },
    {
      "name": "open",
      "type": "boolean",
      "aria": "aria-expanded",
      "description": "Whether an attached overlay (datepicker, dropdown) is currently open. Adds the slds-is-open hook on the form element."
    },
    {
      "name": "layout",
      "type": "enum",
      "options": [
        "default",
        "compoundDeprecated"
      ],
      "description": "Layout flavor. `compoundDeprecated` renders the inner `group` wrapper used by legacy compound/address blueprints."
    }
  ],
  "accessibility": {
    "requirements": [
      {
        "id": "label-association",
        "description": "Label must be associated with input via for/id, aria-labelledby, or a fieldset+legend wrapper."
      },
      {
        "id": "error-association",
        "description": "When hasError is true, the control must set aria-invalid=\"true\" and aria-describedby pointing at the help/error element id."
      },
      {
        "id": "required-indicator",
        "description": "Required indicator (asterisk) is decorative; mark with aria-hidden=\"true\" so screen readers rely on aria-required on the control instead."
      },
      {
        "id": "help-icon-affordance",
        "description": "Help-icon button must have an accessible name (visually hidden label) and reference the popover via aria-describedby."
      }
    ]
  },
  "componentRefs": {
    "PrimitiveIcon": {
      "description": "Bare SVG icon composed directly inside the component. The host node supplies the SVG class (e.g. slds-button__icon, slds-menu__item-icon) via componentProps; PrimitiveIcon contributes the sprite-href binding.",
      "props": {
        "iconName": {
          "type": "string",
          "required": true,
          "description": "Sprite reference for the icon glyph"
        }
      }
    }
  }
}