feat(antares): add DateField component

.changeset/date-field-component.md

@@ -0,0 +1,5 @@
+---
+'@godaddy/antares': minor
+---
+
+feat(antares): add DateField component

packages/@godaddy/antares/components/_internal/field-frame/src/index.module.css

@@ -26,8 +26,10 @@
 
 .frame {
   border-radius: var(--field-frame-br);
-  min-height: 40.5px;
   box-sizing: border-box;
+  font-family: inherit;
+  font-size: var(--font-body-size-md, var(--ux-cxbe8g, 1rem));
+  line-height: var(--ux-jw5s9j, 1.375);
 
   & > :first-child {
     border-start-start-radius: var(--field-frame-br);
@@ -74,6 +76,7 @@
 }
 
 .input {
+  font: inherit;
   background: transparent;
   border: none;
   outline: none;
@@ -86,10 +89,6 @@
   }
 }
 
-input.input {
+.input {
   padding-block: var(--sp-md);
 }
-
-textarea.input {
-  padding-block: var(--sp-sm);
-}

packages/@godaddy/antares/components/date-field/README.mdx

@@ -0,0 +1,132 @@
+---
+title: DateField
+description: DateField is a segmented date input with editable Year, Month, and Day segments. Use it when users only need to type a date. If you also want a calendar popover, use `DatePicker` (or `DateRangePicker` for ranges) instead.
+---
+
+import { ArgTypes, Meta, Source, Story } from '@storybook/addon-docs/blocks';
+import * as Stories from './date-field.stories.tsx';
+
+import SourceBasic from './examples/basic.tsx?raw';
+import SourceWithDefaultValue from './examples/with-default-value.tsx?raw';
+import SourceControlled from './examples/controlled.tsx?raw';
+import SourceWithDescription from './examples/with-description.tsx?raw';
+import SourceWithError from './examples/with-error.tsx?raw';
+import SourceMinMax from './examples/min-max.tsx?raw';
+import SourceDisabledRequiredReadOnly from './examples/disabled-required-readonly.tsx?raw';
+import SourceForm from './examples/form.tsx?raw';
+import SourceWithI18n from './examples/with-i18n.tsx?raw';
+
+<Meta of={Stories} name="Overview" />
+
+## Features
+
+- **Segmented input**: Editable Year, Month, and Day segments with arrow-key adjustment
+- **Label, description, error**: Optional label, helper text, and error message with proper accessibility
+- **Controlled or uncontrolled**: Use `value` and `onChange`, or `defaultValue`
+- **Range bounds**: `minValue` and `maxValue` reject out-of-range entry
+- **Form integration**: Submits an ISO date string when given a `name` prop
+- **Accessible by default**: Full keyboard support, ARIA semantics, and locale-aware segment handling
+
+## Installation
+
+```bash
+npm install --save @godaddy/antares
+```
+
+## Working with dates
+
+Date components in Antares are typed for `CalendarDate` from `@internationalized/date` — a
+date-only type with no time and no timezone.
+
+### Why `@internationalized/date`?
+
+JavaScript's built-in `Date` is a single timestamp that conflates calendar date, time of day,
+and timezone. That's the wrong shape for "a calendar date" (e.g. a birthday or a booking date),
+and round-tripping it through string parsers and `toISOString()` is the source of countless
+off-by-one timezone bugs. [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/index.html)
+separates these concepts cleanly. Antares date components only deal with `CalendarDate`.
+
+### Installation
+
+Install `@internationalized/date` alongside `@godaddy/antares`:
+
+```bash
+npm install --save @internationalized/date
+```
+
+### Locale and i18n
+
+Locale comes from the host app's `<I18nProvider>`, which Antares exports from
+`@godaddy/antares`. If no `<I18nProvider>` is found, the date will be formatted in the default locale.
+
+## Props
+
+The DateField component accepts the following props:
+
+<ArgTypes of={Stories.Props} />
+
+## Examples
+
+### Default
+
+Minimal usage with a label.
+
+<Source language="tsx" code={SourceBasic} />
+<Story of={Stories.Default} inline />
+
+### With default value
+
+Pass a `CalendarDate` to `defaultValue` to initialize the segments.
+
+<Source language="tsx" code={SourceWithDefaultValue} />
+<Story of={Stories.WithDefaultValue} inline />
+
+### Controlled
+
+Use `value` and `onChange` for controlled state.
+
+<Source language="tsx" code={SourceControlled} />
+<Story of={Stories.Controlled} inline />
+
+### With description
+
+Provide helper text via `description`.
+
+<Source language="tsx" code={SourceWithDescription} />
+<Story of={Stories.WithDescription} inline />
+
+### With error
+
+Use `isInvalid` with `errorMessage` for validation feedback.
+
+<Source language="tsx" code={SourceWithError} />
+<Story of={Stories.WithError} inline />
+
+### Min and max
+
+Constrain typed entry with `minValue` and `maxValue`.
+
+<Source language="tsx" code={SourceMinMax} />
+<Story of={Stories.MinMax} inline />
+
+### Disabled, required, read-only
+
+`isDisabled` blocks all interaction. `isRequired` marks the field for form validation. `isReadOnly`
+allows focus and copy but blocks edits.
+
+<Source language="tsx" code={SourceDisabledRequiredReadOnly} />
+<Story of={Stories.DisabledRequiredReadOnly} inline />
+
+### Form
+
+Pass `name` to integrate with native `<form>` submission. The submitted value is a date string with the format `YYYY-MM-DD`.
+
+<Source language="tsx" code={SourceForm} />
+<Story of={Stories.Form} inline />
+
+### With I18nProvider
+
+Wrap the `DateField` in an `<I18nProvider locale="…">` to override the locale used for segment ordering, formatting, and writing direction. Compare an English locale to an RTL Arabic locale below.
+
+<Source language="tsx" code={SourceWithI18n} />
+<Story of={Stories.WithI18n} inline />

packages/@godaddy/antares/components/date-field/date-field.stories.tsx

@@ -0,0 +1,60 @@
+'use client';
+import { getComponentDocs, getMeta, getStory } from '@bento/storybook-addon-helpers';
+import { DateFieldBasicExample } from './examples/basic.tsx';
+import { DateFieldControlledExample } from './examples/controlled.tsx';
+import { DateFieldDisabledRequiredReadOnlyExample } from './examples/disabled-required-readonly.tsx';
+import { DateFieldFormExample } from './examples/form.tsx';
+import { DateFieldMinMaxExample } from './examples/min-max.tsx';
+import {
+  DateFieldPlaygroundExample,
+  type DateFieldPlaygroundExampleProps
+} from './examples/date-field-playground.tsx';
+import { DateFieldWithDefaultValueExample } from './examples/with-default-value.tsx';
+import { DateFieldWithDescriptionExample } from './examples/with-description.tsx';
+import { DateFieldWithErrorExample } from './examples/with-error.tsx';
+import { DateFieldWithI18nExample } from './examples/with-i18n.tsx';
+import { DateField } from './src/index.tsx';
+
+export default getMeta({
+  title: 'components/DateField'
+});
+
+export const Props = getComponentDocs(DateField);
+
+export const Default = getStory(DateFieldBasicExample);
+
+export const WithDefaultValue = getStory(DateFieldWithDefaultValueExample);
+
+export const Controlled = getStory(DateFieldControlledExample);
+
+export const WithDescription = getStory(DateFieldWithDescriptionExample);
+
+export const WithError = getStory(DateFieldWithErrorExample);
+
+export const MinMax = getStory(DateFieldMinMaxExample);
+
+export const DisabledRequiredReadOnly = getStory(DateFieldDisabledRequiredReadOnlyExample);
+
+export const Form = getStory(DateFieldFormExample);
+
+export const WithI18n = getStory(DateFieldWithI18nExample);
+
+export const Playground = {
+  render: (args: DateFieldPlaygroundExampleProps) => <DateFieldPlaygroundExample {...args} />,
+  args: {
+    label: 'Start date',
+    isDisabled: false,
+    isInvalid: false,
+    isReadOnly: false,
+    isRequired: false
+  },
+  argTypes: {
+    label: { control: 'text', description: 'Label text shown above the frame' },
+    description: { control: 'text', description: 'Helper text shown below the frame' },
+    errorMessage: { control: 'text', description: 'Error message when invalid' },
+    isDisabled: { control: 'boolean', description: 'Disable the input' },
+    isInvalid: { control: 'boolean', description: 'Show invalid state' },
+    isReadOnly: { control: 'boolean', description: 'Make the input read-only' },
+    isRequired: { control: 'boolean', description: 'Mark as required' }
+  }
+};

packages/@godaddy/antares/components/date-field/examples/basic.tsx

@@ -0,0 +1,5 @@
+import { DateField, type DateFieldProps } from '@godaddy/antares';
+
+export function DateFieldBasicExample(props: DateFieldProps) {
+  return <DateField label="Start date" {...props} />;
+}

packages/@godaddy/antares/components/date-field/examples/controlled.tsx

@@ -0,0 +1,16 @@
+import { type CalendarDate, parseDate } from '@internationalized/date';
+import { useState } from 'react';
+import { DateField, Text } from '@godaddy/antares';
+
+export function DateFieldControlledExample() {
+  const [value, setValue] = useState<CalendarDate | null>(parseDate('2024-03-15'));
+
+  return (
+    <>
+      <DateField label="Start date" value={value} onChange={setValue} />
+      <Text>
+        <strong>Value:</strong> {value ? value.toString() : '(empty)'}
+      </Text>
+    </>
+  );
+}

packages/@godaddy/antares/components/date-field/examples/date-field-playground.tsx

@@ -0,0 +1,33 @@
+import { DateField } from '@godaddy/antares';
+
+export interface DateFieldPlaygroundExampleProps {
+  description?: string;
+  errorMessage?: string;
+  isDisabled?: boolean;
+  isInvalid?: boolean;
+  isReadOnly?: boolean;
+  isRequired?: boolean;
+  label?: string;
+}
+
+export function DateFieldPlaygroundExample({
+  description,
+  errorMessage,
+  isDisabled,
+  isInvalid,
+  isReadOnly,
+  isRequired,
+  label
+}: DateFieldPlaygroundExampleProps) {
+  return (
+    <DateField
+      description={description}
+      errorMessage={errorMessage}
+      isDisabled={isDisabled}
+      isInvalid={isInvalid}
+      isReadOnly={isReadOnly}
+      isRequired={isRequired}
+      label={label}
+    />
+  );
+}

packages/@godaddy/antares/components/date-field/examples/disabled-required-readonly.tsx

@@ -0,0 +1,12 @@
+import { parseDate } from '@internationalized/date';
+import { Flex, DateField } from '@godaddy/antares';
+
+export function DateFieldDisabledRequiredReadOnlyExample() {
+  return (
+    <Flex direction="column" gap="md">
+      <DateField label="Disabled" defaultValue={parseDate('2024-03-15')} isDisabled />
+      <DateField label="Required" isRequired />
+      <DateField label="Read-only" defaultValue={parseDate('2024-03-15')} isReadOnly />
+    </Flex>
+  );
+}

packages/@godaddy/antares/components/date-field/examples/form.tsx

@@ -0,0 +1,26 @@
+import { type FormEvent, useState } from 'react';
+import { Button, DateField, Flex, Text } from '@godaddy/antares';
+
+export function DateFieldFormExample() {
+  const [submitted, setSubmitted] = useState<string | null>(null);
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const formData = new FormData(event.currentTarget);
+    setSubmitted(String(formData.get('startDate') ?? ''));
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Flex direction="column" gap="md" alignItems="flex-start">
+        <DateField label="Start date" name="startDate" isRequired />
+        <Button type="submit">Submit</Button>
+        {submitted !== null && (
+          <Text>
+            <strong>Submitted:</strong> {submitted || '(empty)'}
+          </Text>
+        )}
+      </Flex>
+    </form>
+  );
+}

packages/@godaddy/antares/components/date-field/examples/min-max.tsx

@@ -0,0 +1,14 @@
+import { parseDate } from '@internationalized/date';
+import { DateField } from '@godaddy/antares';
+
+export function DateFieldMinMaxExample() {
+  return (
+    <DateField
+      label="Booking date"
+      description="Must fall within 2024."
+      minValue={parseDate('2024-01-01')}
+      maxValue={parseDate('2024-12-31')}
+      defaultValue={parseDate('2024-06-15')}
+    />
+  );
+}

packages/@godaddy/antares/components/date-field/examples/with-default-value.tsx

@@ -0,0 +1,6 @@
+import { parseDate } from '@internationalized/date';
+import { DateField } from '@godaddy/antares';
+
+export function DateFieldWithDefaultValueExample() {
+  return <DateField label="Start date" defaultValue={parseDate('2024-03-15')} />;
+}

packages/@godaddy/antares/components/date-field/examples/with-description.tsx

@@ -0,0 +1,5 @@
+import { DateField } from '@godaddy/antares';
+
+export function DateFieldWithDescriptionExample() {
+  return <DateField label="Start date" description="The date your subscription begins." />;
+}

packages/@godaddy/antares/components/date-field/examples/with-error.tsx

@@ -0,0 +1,5 @@
+import { DateField } from '@godaddy/antares';
+
+export function DateFieldWithErrorExample() {
+  return <DateField label="Start date" errorMessage="Please enter a valid date." isInvalid isRequired />;
+}

packages/@godaddy/antares/components/date-field/examples/with-i18n.tsx

@@ -0,0 +1,15 @@
+import { parseDate } from '@internationalized/date';
+import { DateField, Flex, I18nProvider } from '@godaddy/antares';
+
+export function DateFieldWithI18nExample() {
+  return (
+    <Flex direction="column" gap="md">
+      <I18nProvider locale="en-US">
+        <DateField label="Start date (en-US)" defaultValue={parseDate('2024-03-15')} />
+      </I18nProvider>
+      <I18nProvider locale="ar-AE">
+        <DateField label="Start date (ar-AE)" defaultValue={parseDate('2024-03-15')} />
+      </I18nProvider>
+    </Flex>
+  );
+}