# Calendar

> A month-grid calendar surface composed from a navigable header and a native `<table>` of day cells, styled through the platform's own semantics.

```ts
import { Calendar } from "@sdxc/ui";
```

Renders a rounded, padded surface around whichever children a consumer
composes; `children` left unset renders a native `<input type="date">`
through Input, the one part the platform itself operates.

## Examples

```tsx
<Calendar aria-label={t("form.startDate.label")} name="startDate" />
```

```tsx
<Calendar aria-label={t("calendar.label")}>
	<Calendar.Header>
		<Calendar.PreviousButton aria-label={t("calendar.previous")} />
		<Calendar.Heading>{monthLabel}</Calendar.Heading>
		<Calendar.NextButton aria-label={t("calendar.next")} />
	</Calendar.Header>
	<Calendar.Grid aria-label={monthLabel}>
		<Calendar.GridHeader>
			<Calendar.Row>
				{weekdayLabels.map((day) => (
					<Calendar.HeaderCell key={day}>{day}</Calendar.HeaderCell>
				))}
			</Calendar.Row>
		</Calendar.GridHeader>
		<Calendar.GridBody>
			{weeks.map((week) => (
				<Calendar.Row key={week[0].iso}>
					{week.map((day) => (
						<Calendar.Cell
							key={day.iso}
							aria-selected={day.iso === selected ? "true" : undefined}
							data-outside-month={day.outsideMonth ? "" : undefined}
						>
							{day.label}
						</Calendar.Cell>
					))}
				</Calendar.Row>
			))}
		</Calendar.GridBody>
	</Calendar.Grid>
</Calendar>
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `color?` | `"brand" \| "neutral" \| "success" \| "warning" \| "danger"` | Semantic color role for the bare fallback control's focus ring. Defaults to DEFAULT_COLOR. |
| `name?` | `string` | Native `name` submitted with an enclosing form, read only by the bare fallback control. |
| `value?` | `string` | Current value, in `YYYY-MM-DD` form, for a bare fallback control a consumer tracks itself. |
| `defaultValue?` | `string` | Initial value, in `YYYY-MM-DD` form, for a bare fallback control left to the platform's own uncontrolled state. |
| `min?` | `string` | Earliest accepted date, in `YYYY-MM-DD` form, read only by the bare fallback control. |
| `max?` | `string` | Latest accepted date, in `YYYY-MM-DD` form, read only by the bare fallback control. |
| `step?` | `number` | Granularity, in days, the bare fallback control's value must fall on. |
| `required?` | `boolean` | Marks the bare fallback control required for its enclosing form. |
| `disabled?` | `boolean` | Marks the bare fallback control inert and excluded from the tab order. |
| `readOnly?` | `boolean` | Marks the bare fallback control's value fixed, while keeping it focusable and included in form submission. |
| `autoComplete?` | `string` | Native autofill hint for the bare fallback control, e.g. `"bday"`. |

Also accepts everything in `TagProps<"div">`.


### Calendar.Header

Renders Calendar's nav row: a flex row spacing Calendar.PreviousButton, Calendar.Heading, and Calendar.NextButton apart, the heading centered between the controls.

Also accepts everything in `TagProps<"header">`.


### Calendar.PreviousButton

Renders a round icon control standing for "show the previous month", sized to match Calendar.NextButton.

Also accepts everything in `TagProps<"button">`.


### Calendar.NextButton

Renders a round icon control standing for "show the following month", with the rendering, focus, and disabled-state contract of Calendar.PreviousButton and a trailing chevron by default.

Also accepts everything in `TagProps<"button">`.


### Calendar.Heading

Renders the consumer-formatted month/year caption through Heading, centered between the nav controls at a small semibold size layered after Heading's own defaults, so this size and alignment win over them.

Also accepts everything in `Heading.Props`.


### Calendar.Grid

Renders the day grid's native `<table>` host, rows and cells set apart by a small gap on every side.

Also accepts everything in `TagProps<"table">`.


### Calendar.GridHeader

Renders the grid's `<thead>` host: a plain wrapper for the weekday Calendar.Row.

Also accepts everything in `TagProps<"thead">`.


### Calendar.Row

Renders a native `<tr>` host: one row of Calendar.HeaderCell inside Calendar.GridHeader, or one week of Calendar.Cell inside Calendar.GridBody.

Also accepts everything in `TagProps<"tr">`.


### Calendar.HeaderCell

Renders a weekday abbreviation inside a native `<th scope="col">`, sized small and muted beneath Calendar.Cell's own larger day numbers.

Also accepts everything in `TagProps<"th">`.


### Calendar.GridBody

Renders the grid's `<tbody>` host: a plain wrapper for one Calendar.Row per week.

Also accepts everything in `TagProps<"tbody">`.


### Calendar.Cell

Renders one calendar day inside a native `<td>`, a fixed round pill around its number.

Also accepts everything in `TagProps<"td">`.


## Types

| Name | Values | What it decides |
| --- | --- | --- |
| `Color` | `"brand" \| "neutral" \| "success" \| "warning" \| "danger"` | Semantic color role for the bare `<input type="date">` fallback's keyboard focus ring, each mapped to its matching `--ui-*` variables. |