# DateField

A form control wrapper for `Temporal.PlainDate` values, default `DateInput` composition, and date validation.

## Usage

Use standalone, or wrap `DateInput` to share field state and validation.

```svelte
<DateField {...props} />

<DateField {...props}>
  <DateInput {...props} />
</DateField>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<div class="whole" role="group" aria-*>
  <div class="top" conditional>
    <label class="label" conditional>
      {label}
      <span class="extra" conditional>{extra}</span>
    </label>
    <span class="aux" conditional>{aux}</span>
  </div>
  <div class="middle">
    <span class="left" conditional>{left}</span>
    {#if children}{@render children()}{:else if native}<input class="main" type="date" aria-* />{:else}<DateInput />{/if}
    <span class="right" conditional>{right}</span>
    <input hidden conditional />
  </div>
  <div class="bottom" conditional>{bottom}</div>
</div>
```

## Props

| Name          | Type                  | Default   | Description                                                                  |
| ------------- | --------------------- | --------- | ---------------------------------------------------------------------------- |
| `label`       | `string`              | -         | Field label                                                                  |
| `extra`       | `string`              | -         | Extra text shown with the label                                              |
| `aux`         | `Snippet`             | -         | Auxiliary content; receives value, variant, and input element                |
| `left`        | `Snippet`             | -         | Content before the control                                                   |
| `right`       | `Snippet`             | -         | Content after the control                                                    |
| `bottom`      | `string`              | -         | Bottom message                                                               |
| `reserve`     | `boolean`             | `false`   | Renders the bottom element even without a message to prevent layout shift    |
| `value`       | `Temporal.PlainDate`  | -         | Bindable selected date                                                       |
| `min`         | `Temporal.PlainDate`  | -         | Minimum allowed date                                                         |
| `max`         | `Temporal.PlainDate`  | -         | Maximum allowed date                                                         |
| `required`    | `boolean`             | `false`   | Standard date required constraint owned by the field                         |
| `disabled`    | `boolean`             | `false`   | Standard disabled constraint owned by the field                              |
| `validations` | `DateFieldValidation` | -         | Field-level validation functions for the selected date                       |
| `name`        | `string`              | -         | Form submission name for the hidden canonical ISO input                      |
| `native`      | `boolean`             | `false`   | Uses a browser `<input type="date">`; `dateInput` options do not apply       |
| `element`     | `HTMLInputElement`    | -         | Bindable input element                                                       |
| `styling`     | `SVSClass`            | -         | Styling override                                                             |
| `variant`     | `SVSVariant`          | `NEUTRAL` | Bindable variant                                                             |
| `dateInput`   | `Omit`                | -         | Props for the default inner `DateInput`; ignored when `children` is supplied |
| `children`    | `Snippet`             | -         | Compound form child `DateInput` that shares the field state                  |
## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

In the initial state or while no value is set, `neutral` is applied. After a value is set, the variant switches to `active` if validation succeeds or `inactive` if validation fails. If the `variant` prop is specified, the specified value is used instead of `neutral`.

### Default Class Name

`svs-date-field`

## Behavior

- In the default path, one hidden attribute input carries the canonical ISO form value and all constraint validation, including when `DateInput` is readonly.
- `native` uses a browser-provided `<input type="date">`; `dateInput` options do not apply in that mode.

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Field (`whole` `<div>`): `role="group"` and `aria-labelledby` pointing to the label part when label text is present.
- Date control: `aria-describedby`, `aria-invalid`, and `aria-errormessage` from the validation message wiring. In the default mode, `DateInput` also receives `aria-required` when `required` is set; in `native` mode, the date input uses the native `required` attribute.

Provide `label` text for the field's accessible name; the component wires that label to the group and control instead of requiring an author-passed `aria-label`. In the default non-native mode, picker keyboard and ARIA behavior come from [DateInput](/docs/date-input).

### Standards Basis

When `native` is set, DateField is built on a native `<input type="date">`, so keyboard and assistive-technology support follows the browser standard for date inputs. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
type DateFieldValidation = SVSFieldValidation<Temporal.PlainDate | undefined>;
interface DateFieldProps {
  label?: string;
  extra?: string;
  aux?: Snippet<[Temporal.PlainDate | undefined, string, HTMLInputElement | undefined]>;
  left?: Snippet<[Temporal.PlainDate | undefined, string, HTMLInputElement | undefined]>;
  right?: Snippet<[Temporal.PlainDate | undefined, string, HTMLInputElement | undefined]>;
  bottom?: string;
  reserve?: boolean; // (false)
  value?: Temporal.PlainDate; // bindable
  min?: Temporal.PlainDate;
  max?: Temporal.PlainDate;
  required?: boolean; // (false)
  disabled?: boolean; // (false)
  validations?: DateFieldValidation[];
  name?: string;
  native?: boolean; // (false)
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  dateInput?: Omit<
    DateInputProps,
    DateInputReqdProps | DateInputBindProps | "name" | "min" | "max" | "required" | "disabled" | "variant" | "styling"
  >;
  children?: Snippet;
}
type DateFieldReqdProps = never;
type DateFieldBindProps = "value" | "variant" | "element";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=DateFieldBasic.svelte
<script lang="ts">
  import { DateField } from "svseeds";

  let value = $state<Temporal.PlainDate>();

  const pickerStyle = {
    whole: "relative flex justify-center items-center rounded-md bg-white dark:bg-black",
    left: "absolute inset-y-0 inset-x-1 my-auto h-7 rounded-md opacity-30 bg-black dark:bg-white pointer-events-none",
  };
  const yearStyle = {
    whole: "w-20 h-30 overflow-hidden rounded-md",
    middle: "h-full",
    label: {
      base: "flex h-8 items-center justify-end",
      active: "font-bold",
    },
    aux: "hidden",
    extra: "inset-0 bg-linear-to-b from-white via-transparent to-white dark:from-black dark:to-black",
  };
  const monthStyle = {
    ...yearStyle,
    label: {
      base: "flex ps-4 h-8 items-center justify-start",
      active: "font-bold",
    },
  };
  const pickerProps = {
    styling: pickerStyle,
    left: preserve,
    yearLabel: (y: number) => String(y),
    monthLabel: (m: number) => String(m).padStart(2, "0"),
    year: { styling: yearStyle },
    month: { styling: monthStyle },
  };
  const calendarStyle = {
    whole: "w-full bg-white dark:bg-black",
    top: "mb-1 flex items-center gap-2",
    left: "px-1.5 py-0.5 rounded-md border text-sm cursor-pointer",
    label: "px-1 py-0.5 min-w-0 flex-1 cursor-pointer rounded-md border text-sm font-bold",
    right: "px-1.5 py-0.5 rounded-md border text-sm cursor-pointer",
    middle: "overflow-hidden",
    aux: "grid grid-cols-7 gap-1",
    main: "grid gap-1 outline-hidden select-none",
    extra: {
      base: "flex size-6 items-center justify-center rounded-md text-sm data-header:data-[weekday=0]:text-red-500 data-outside:text-gray-400 data-today:font-bold data-today:not-data-selected:bg-gray-400",
      active: "bg-teal-500 font-bold",
      inactive: "text-gray-400",
    },
  };
  const calendarProps = {
    left,
    right,
    outsideDays: true,
    monthPicker: pickerProps,
    styling: calendarStyle,
  };
  const dateStyle = {
    whole: "flex! w-50 flex-col items-center rounded-sm border bg-white dark:bg-black",
    main: "px-3 py-2 w-full outline-hidden",
    bottom: "my-2 p-3 w-full rounded-sm border bg-white shadow-lg dark:bg-black",
  };
  const dateProps = {
    placeholder: "Pick a date",
    openOnFocus: true,
    calendar: calendarProps,
    styling: dateStyle,
  };
  const styling = {
    label: "font-bold",
    middle: "mt-1",
    bottom: "mt-1 text-xs",
  };
  const myProps = {
    label: "Date Field",
    bottom: "Choose a your date",
    required: true,
    reserve: true,
    dateInput: dateProps,
    styling,
  };
</script>

<div class="flex flex-col items-start gap-3">
  <DateField bind:value {...myProps} />
  <div class="text-sm">Selected: {value?.toString() ?? "Pick a day"}</div>
</div>
{#snippet preserve()}{/snippet}
{#snippet left()}{"<"}{/snippet}
{#snippet right()}{">"}{/snippet}
```
### With Interactive Variant

**Code**

```svelte src=DateFieldPract.svelte
<script lang="ts">
  import { DateField, DateInput, Calendar, MonthPicker, type DateFieldValidation } from "svseeds";

  let { variant = $bindable() } = $props();
  let value = $state<Temporal.PlainDate>();
  const min = Temporal.Now.plainDateISO().with({ month: 1, day: 1 });
  const max = Temporal.Now.plainDateISO().with({ month: 12, day: 31 });
  const validations: DateFieldValidation[] = [({ value }) => (value === undefined ? "Choose a date" : "")];
  const parse = (text: string) => {
    try {
      if (!text) return;
      return Temporal.PlainDate.from(new Date(text).toISOString().split("T")[0]);
    } catch {
      return undefined;
    }
  };

  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const pickerStyle = {
    whole: "relative flex justify-center items-center rounded-md bg-white dark:bg-black",
    left: "absolute inset-y-0 inset-x-1 my-auto h-7 rounded-md opacity-30 bg-black dark:bg-white pointer-events-none",
  };
  const yearStyle = {
    whole: "w-20 h-30 overflow-hidden rounded-md",
    middle: "h-full",
    label: {
      base: "flex h-8 items-center justify-end",
      active: "font-bold",
    },
    aux: "hidden",
    extra: "inset-0 bg-linear-to-b from-white via-transparent to-white dark:from-black dark:to-black",
  };
  const monthStyle = {
    ...yearStyle,
    label: {
      base: "flex ps-4 h-8 items-center justify-start",
      active: "font-bold",
    },
  };
  const pickerProps = {
    styling: pickerStyle,
    left: preserve,
    yearLabel: (y: number) => String(y),
    monthLabel: (m: number) => String(m).padStart(2, "0"),
    year: { styling: yearStyle },
    month: { styling: monthStyle },
  };
  const calendarStyle = {
    whole: "w-full bg-white dark:bg-black",
    top: "mb-1 flex items-center gap-2",
    left: "px-1.5 py-0.5 rounded-md border text-sm cursor-pointer",
    label: "px-1 py-0.5 min-w-0 flex-1 cursor-pointer rounded-md border text-sm font-bold",
    right: "px-1.5 py-0.5 rounded-md border text-sm cursor-pointer",
    middle: "overflow-hidden",
    aux: "grid grid-cols-7 gap-1",
    main: "grid gap-1 outline-hidden select-none",
    extra: {
      base: "flex size-6 items-center justify-center rounded-md text-sm data-header:data-[weekday=0]:text-red-500 data-outside:text-gray-400 data-today:font-bold data-today:not-data-selected:bg-gray-400",
      active: "bg-teal-500 font-bold",
      inactive: "text-gray-400",
    },
  };
  const calendarProps = {
    left,
    right,
    outsideDays: true,
    fixedWeeks: true,
    styling: calendarStyle,
  };
  const dateStyle = {
    whole: {
      base: "flex! items-center rounded-sm border bg-white dark:bg-black",
      ...variantStyle,
    },
    main: "p-2 w-50 outline-hidden",
    bottom: "my-2 p-3 rounded-sm border bg-white shadow-lg dark:bg-black",
  };
  const dateProps = {
    min,
    max,
    parse,
    format: (d: Temporal.PlainDate) => d.toString(),
    placeholder: "YYYY-MM-DD",
    openOnFocus: true,
    styling: dateStyle,
  };
  const styling = {
    label: {
      base: "font-bold",
      inactive: "text-red-500",
    },
    middle: "mt-1",
    bottom: {
      base: "mt-1 text-xs",
      inactive: "text-red-500",
    },
  };
  const myProps = {
    label: "Launch Date",
    bottom: "Use an ISO date in this year",
    name: "launchDate",
    min,
    max,
    required: true,
    reserve: true,
    validations,
    styling,
  };
</script>

<div class="flex flex-col items-start gap-3">
  <DateField bind:value bind:variant {...myProps}>
    <DateInput {...dateProps}>
      <Calendar {...calendarProps}>
        <MonthPicker {...pickerProps} />
      </Calendar>
    </DateInput>
  </DateField>
  <div class="text-sm">Selected: {value?.toString() ?? "Pick a day"}</div>
</div>
{#snippet preserve()}{/snippet}
{#snippet left()}{"<"}{/snippet}
{#snippet right()}{">"}{/snippet}
```