{
  "_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": "Datepicker",
  "description": "A datepicker is a text input paired with a calendar dropdown that lets users type or pick a single date.",
  "structure": {
    "name": "root",
    "restrict": [
      "div"
    ],
    "description": "Initiates a datepicker component.",
    "children": [
      {
        "name": "label",
        "restrict": [
          "label"
        ],
        "description": "Visible label for the date input.",
        "attributes": {
          "bound": {
            "for": {
              "prop": "inputId"
            }
          }
        }
      },
      {
        "name": "requiredIndicator",
        "restrict": [
          "abbr"
        ],
        "description": "Asterisk marker rendered inside the label when the field is required.",
        "renderWhen": {
          "prop": "required",
          "eq": "true"
        }
      },
      {
        "name": "helpTooltip",
        "restrict": [
          "div"
        ],
        "description": "Optional help-icon button with a popover tooltip describing the expected date format.",
        "children": [
          {
            "name": "helpButton",
            "restrict": [
              "button"
            ],
            "description": "Help icon button that toggles the tooltip."
          },
          {
            "name": "helpPopover",
            "restrict": [
              "div"
            ],
            "description": "Tooltip popover associated with the help button.",
            "attributes": {
              "static": {
                "role": "tooltip"
              }
            },
            "children": [
              {
                "name": "helpPopoverBody",
                "restrict": [
                  "div"
                ],
                "description": "Body text of the help tooltip."
              }
            ]
          }
        ]
      },
      {
        "name": "control",
        "restrict": [
          "div"
        ],
        "description": "Form-element control wrapper that holds the input and the trigger icon button.",
        "children": [
          {
            "name": "input",
            "restrict": [
              "input"
            ],
            "description": "Text input where the user types or sees the selected date.",
            "attributes": {
              "static": {
                "type": "text"
              },
              "bound": {
                "id": {
                  "prop": "inputId"
                },
                "value": {
                  "prop": "value"
                },
                "placeholder": {
                  "prop": "placeholder"
                }
              }
            }
          },
          {
            "name": "triggerButton",
            "restrict": [
              "button"
            ],
            "description": "Icon button that opens the calendar dropdown.",
            "attributes": {
              "bound": {
                "title": {
                  "prop": "openCalendarLabel"
                }
              }
            },
            "children": [
              {
                "name": "triggerIcon",
                "restrict": [
                  "svg"
                ],
                "description": "Calendar event icon inside the trigger button."
              },
              {
                "name": "triggerAssistiveText",
                "restrict": [
                  "span"
                ],
                "description": "Visually-hidden label announcing the trigger action."
              }
            ]
          }
        ]
      },
      {
        "name": "help",
        "restrict": [
          "div"
        ],
        "description": "Format-hint or error text rendered below the input."
      },
      {
        "name": "dropdown",
        "restrict": [
          "div"
        ],
        "description": "Calendar dropdown dialog (popover) anchored to the input.",
        "attributes": {
          "static": {
            "role": "dialog"
          },
          "bound": {
            "aria-hidden": {
              "prop": "isClosed"
            },
            "aria-label": {
              "prop": "dialogLabel"
            }
          }
        },
        "children": [
          {
            "name": "header",
            "restrict": [
              "div"
            ],
            "description": "Month/year navigation header at the top of the calendar.",
            "children": [
              {
                "name": "monthNav",
                "restrict": [
                  "div"
                ],
                "description": "Inline group containing the previous-month button, the current month heading, and the next-month button.",
                "children": [
                  {
                    "name": "prevButtonWrapper",
                    "restrict": [
                      "div"
                    ],
                    "description": "Alignment wrapper around the previous-month button."
                  },
                  {
                    "name": "prevButton",
                    "restrict": [
                      "button"
                    ],
                    "description": "Previous month button.",
                    "attributes": {
                      "bound": {
                        "title": {
                          "prop": "prevMonthLabel"
                        }
                      }
                    },
                    "children": [
                      {
                        "name": "prevIcon",
                        "restrict": [
                          "svg"
                        ],
                        "description": "Left chevron icon inside the previous-month button."
                      },
                      {
                        "name": "prevAssistiveText",
                        "restrict": [
                          "span"
                        ],
                        "description": "Visually-hidden label for the previous-month button."
                      }
                    ]
                  },
                  {
                    "name": "monthYear",
                    "restrict": [
                      "h2"
                    ],
                    "description": "Current month label, announced as a live region when the month changes.",
                    "attributes": {
                      "static": {
                        "aria-atomic": "false",
                        "aria-live": "polite"
                      }
                    }
                  },
                  {
                    "name": "nextButtonWrapper",
                    "restrict": [
                      "div"
                    ],
                    "description": "Alignment wrapper around the next-month button."
                  },
                  {
                    "name": "nextButton",
                    "restrict": [
                      "button"
                    ],
                    "description": "Next month button.",
                    "attributes": {
                      "bound": {
                        "title": {
                          "prop": "nextMonthLabel"
                        }
                      }
                    },
                    "children": [
                      {
                        "name": "nextIcon",
                        "restrict": [
                          "svg"
                        ],
                        "description": "Right chevron icon inside the next-month button."
                      },
                      {
                        "name": "nextAssistiveText",
                        "restrict": [
                          "span"
                        ],
                        "description": "Visually-hidden label for the next-month button."
                      }
                    ]
                  }
                ]
              },
              {
                "name": "yearGroup",
                "restrict": [
                  "div"
                ],
                "description": "Year picker group at the right side of the calendar header.",
                "children": [
                  {
                    "name": "yearLabel",
                    "restrict": [
                      "label"
                    ],
                    "description": "Visually-hidden label for the year select."
                  },
                  {
                    "name": "yearSelectWrapper",
                    "restrict": [
                      "div"
                    ],
                    "description": "Native-select wrapper providing the visual chevron affordance."
                  },
                  {
                    "name": "yearSelect",
                    "restrict": [
                      "select"
                    ],
                    "description": "Native select listing selectable years.",
                    "children": [
                      {
                        "name": "yearOption",
                        "restrict": [
                          "option"
                        ],
                        "description": "A single year choice.",
                        "slot": {
                          "name": "yearOptions"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "name": "calendar",
            "restrict": [
              "table"
            ],
            "description": "Calendar grid.",
            "attributes": {
              "static": {
                "role": "grid"
              },
              "bound": {
                "aria-multiselectable": {
                  "prop": "multiSelectable"
                }
              }
            },
            "children": [
              {
                "name": "weekdayHeaders",
                "restrict": [
                  "thead"
                ],
                "description": "Weekday column headers.",
                "children": [
                  {
                    "name": "weekdayRow",
                    "restrict": [
                      "tr"
                    ],
                    "description": "Single row of weekday names."
                  },
                  {
                    "name": "weekdayHeader",
                    "restrict": [
                      "th"
                    ],
                    "description": "Column header for one weekday.",
                    "attributes": {
                      "static": {
                        "scope": "col"
                      }
                    },
                    "children": [
                      {
                        "name": "weekdayAbbr",
                        "restrict": [
                          "abbr"
                        ],
                        "description": "Abbreviation expanding the short weekday name to the full name."
                      }
                    ]
                  }
                ]
              },
              {
                "name": "days",
                "restrict": [
                  "tbody"
                ],
                "description": "Calendar day cells, organized by week.",
                "slot": {
                  "name": "default"
                },
                "children": [
                  {
                    "name": "weekRow",
                    "restrict": [
                      "tr"
                    ],
                    "description": "One week of date cells."
                  },
                  {
                    "name": "dayCell",
                    "restrict": [
                      "td"
                    ],
                    "description": "A single date cell in the grid.",
                    "attributes": {
                      "static": {
                        "role": "gridcell"
                      },
                      "bound": {
                        "aria-selected": {
                          "prop": "isSelected"
                        },
                        "aria-label": {
                          "prop": "dateLabel"
                        },
                        "aria-current": {
                          "prop": "isToday"
                        }
                      }
                    },
                    "children": [
                      {
                        "name": "dayLabel",
                        "restrict": [
                          "span"
                        ],
                        "description": "Visible day-of-month number inside the cell."
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "name": "footer",
            "restrict": [
              "button"
            ],
            "description": "Today link button rendered below the grid.",
            "renderWhen": "slotFilled",
            "slot": {
              "name": "footer"
            }
          }
        ]
      }
    ]
  },
  "states": [
    {
      "name": "open",
      "type": "boolean",
      "description": "Whether the calendar dropdown is currently visible."
    },
    {
      "name": "disabled",
      "type": "boolean",
      "aria": "aria-disabled",
      "description": "Whether the datepicker is disabled."
    },
    {
      "name": "required",
      "type": "boolean",
      "aria": "aria-required",
      "description": "Whether a value is required."
    },
    {
      "name": "hasError",
      "type": "boolean",
      "description": "Whether the datepicker has a validation error."
    },
    {
      "name": "selectedDate",
      "type": "enum",
      "aria": "aria-selected",
      "description": "Currently selected date.",
      "options": []
    },
    {
      "name": "focusedDate",
      "type": "enum",
      "description": "Currently focused date in the grid.",
      "options": []
    },
    {
      "name": "today",
      "type": "boolean",
      "aria": "aria-current",
      "description": "Whether a date cell represents today."
    },
    {
      "name": "adjacentMonth",
      "type": "boolean",
      "description": "Whether a date belongs to an adjacent (previous/next) month."
    },
    {
      "name": "multiRowSelection",
      "type": "boolean",
      "description": "Whether a week row contains multiple selected dates spanning a range."
    },
    {
      "name": "multiSelection",
      "type": "boolean",
      "description": "Whether a row contains a single selected cell that participates in a range."
    },
    {
      "name": "selectedMulti",
      "type": "boolean",
      "description": "Whether a cell is part of a multi-cell range selection."
    }
  ],
  "accessibility": {
    "requirements": [
      {
        "id": "dialog-role",
        "description": "Calendar dropdown must use role='dialog' with an aria-label naming the visible month."
      },
      {
        "id": "grid-role",
        "description": "Calendar must have role='grid' and announce multi-selectability via aria-multiselectable."
      },
      {
        "id": "live-month",
        "description": "Month heading must use aria-live='polite' so screen readers announce month changes."
      },
      {
        "id": "keyboard-navigation",
        "description": "Arrow keys navigate dates; Enter selects; Esc closes the dropdown."
      },
      {
        "id": "aria-selected",
        "description": "Every date cell must carry aria-selected (true/false)."
      },
      {
        "id": "aria-current-date",
        "description": "The cell representing today must have aria-current='date'."
      },
      {
        "id": "trigger-assistive-text",
        "description": "The trigger icon button must include visually-hidden text announcing 'Select a date'."
      }
    ]
  }
}