[DST-581]: Revise <DateField> page (#4202)

* Revise datefield page

* Adding anatomy section

* Adding appearance demo

* Adding usage section

* Re-order page sections

* Delete unwanted section of simple datefield

* Deleteing unwatned file

* Revising exmaples

* Adding related section

* Revise props table

* Adding changeset

* Resolving comments

* Remove dup sections

* Adding alt components section

* rem dup words

* Remove unwanted sections

* Delete unwanted files

* Fixing issues

* Resolving comments

* Resolving comments

.changeset/fresh-zoos-vanish.md

@@ -0,0 +1,8 @@
+---
+'@marigold/components': patch
+'@marigold/docs': patch
+---
+
+docs([DST-581]): revise `<DateField>` page according to new component page structure
+
+Revised the `<DateField>` documentation page to our new layout of component pages.

docs/content/components/form/datefield/datefield-appearance.demo.tsx

@@ -0,0 +1,10 @@
+import { CalendarDate } from '@internationalized/date';
+import { DateField } from '@marigold/components';
+
+export default () => (
+  <DateField
+    label="Event Date"
+    defaultValue={new CalendarDate(2023, 10, 15)} // Updated to a future date relevant for ticketing
+    description="Select the date for your ticket event."
+  />
+);

docs/content/components/form/datefield/datefield.mdx

@@ -1,48 +1,93 @@
 ---
 title: DateField
-caption: Component for input forms.
+caption: Component for entering date in forms.
+badge: updated
 ---
 
-The `<DateField>` allows users to enter and edit date values using a keyboard. Each part of a date value is displayed in an individually editable segment.
+The `<DateField>` allows users to enter and edit date values using a keyboard. Each part of a date value is displayed in an individually editable segment. These segments are individually focusable and editable by the user, by typing or using the arrow keys to increment and decrement the value. This approach allows values to be formatted and parsed correctly regardless of the locale or date format, and offers an easy and error-free way to edit dates using the keyboard.
 
-The `<DateField>` segments are individually focusable and editable by the user, by typing or using the arrow keys to increment and decrement the value. This approach allows values to be formatted and parsed correctly regardless of the locale or date format, and offers an easy and error-free way to edit dates using the keyboard.
+## Anatomy
 
-## Import
+A `<DateField>` consists of a label and a group of segments representing each unit of a date and time, such as years, months, days, hours, and minutes.
 
-```tsx
-import { DateField } from '@marigold/components';
-```
+<Image
+  src="/datefield/datefield-anatomy.jpg"
+  alt="Anatomy of datefield"
+  width={800}
+  height={550}
+  className="mx-auto block"
+/>
 
 ## Appearance
 
-<AppearanceTable component={title} />
-
-## Props
-
-<PropsTable component={title} />
-
-## Examples
-
-### Simple DateField
+<AppearanceDemo component={title} />
 
-This example shows a regular `<DateField>` without any special props.
-
-<ComponentDemo file="./date-field-basic.demo.tsx" />
-
-### Disabled DateField
-
-You can disable the `<DateField>` so that the user can't interact with it anymore.
-
-<ComponentDemo file="./date-field-disabled.demo.tsx" />
+<AppearanceTable component={title} />
 
-### Required DateField
+## Usage
 
-If you want a `<DateField>` to be required, you just have to add the property `required`. With that the small required icon appears next to the label.
+The `<DateField>` component is a versatile input element used for selecting dates in forms. It enhances user experience by providing a structured way to input date information, reducing errors associated with manual entry. With features like labels and descriptions, it clearly communicates its purpose to users. The component can also support default values. Overall, the `<DateField>` is essential for applications requiring date selection, ensuring both accessibility and usability.
 
-<ComponentDemo file="./date-field-required.demo.tsx" />
+## Props
 
-### DateField With an Error
+<StorybookHintMessage component={title} />
 
-This example shows how to use the `error` with the `errorMessage`.
+<PropsTable component={title} />
 
-<ComponentDemo file="./date-field-error.demo.tsx" />
+## Alternative components
+
+<ul>
+  <li>
+    [DatePicker](/components/form/datepicker): a user interface element that
+    allows users to select a date from a calendar.
+  </li>
+</ul>
+
+## Related
+
+<TeaserList
+  items={[
+    {
+      title: 'Building forms',
+      href: '../../patterns/building-forms',
+      caption: 'Learn how to build forms.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width={24}
+          height={24}
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M12 3H5a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2v-7" />
+          <path d="M18.375 2.625a2.121 2.121 0 113 3L12 15l-4 1 1-4z" />
+        </svg>
+      ),
+    },
+    {
+      title: 'Form Fields',
+      href: '../../introduction/form-fields',
+      caption: 'Learn how to build forms.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width={24}
+          height={24}
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M12 3H5a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2v-7" />
+          <path d="M18.375 2.625a2.121 2.121 0 113 3L12 15l-4 1 1-4z" />
+        </svg>
+      ),
+    },
+  ]}
+/>

docs/content/patterns/building-forms/validation-zod.demo.tsx

@@ -0,0 +1,109 @@
+import { FormEventHandler, useState } from 'react';
+import { z } from 'zod';
+import { zfd } from 'zod-form-data';
+import {
+  Button,
+  Checkbox,
+  Columns,
+  FieldGroup,
+  Headline,
+  Select,
+  Stack,
+  TextField,
+} from '@marigold/components';
+
+export default () => {
+  const schemaData = z.object({
+    firstname: z.string().min(1),
+    name: z.string().min(1),
+    phone: z.string().min(6),
+    mail: z.string().email(),
+    country: z.string(),
+    terms: zfd.checkbox(),
+  });
+
+  const [error, setError] = useState<string[]>([]);
+  const handleSubmit: FormEventHandler<HTMLFormElement> = e => {
+    e.preventDefault();
+    const errorList: Array<any> = [];
+    const formData = new FormData(e.target as HTMLFormElement);
+    const data = Object.fromEntries(formData);
+    const validatedForm = schemaData.safeParse(data);
+
+    if (!validatedForm.success) {
+      validatedForm.error.issues.map(e => {
+        return errorList.push(e.path.toString());
+      });
+      setError(errorList);
+    } else {
+      alert(JSON.stringify(data));
+    }
+  };
+
+  return (
+    <FieldGroup labelWidth="100px">
+      <Headline level={2}>Account Registration</Headline>
+      <form onSubmit={handleSubmit}>
+        <Stack space={4}>
+          <Columns columns={[2, 2]} space={4}>
+            <TextField
+              name="firstname"
+              label="Firstname:"
+              required
+              description="Please enter your first name."
+              placeholder="Firstname"
+              error={error.includes('firstname')}
+              errorMessage="The field is required. Please enter your firstname."
+            />
+            <TextField
+              name="name"
+              label="Name:"
+              required
+              description="Please enter your name."
+              placeholder="Name"
+              error={error.includes('name')}
+              errorMessage="The field is required. Please enter your name."
+            />
+          </Columns>
+          <Stack space={4}>
+            <TextField
+              name="phone"
+              label="Phone:"
+              required
+              placeholder="Phone"
+              type="tel"
+              description="Please enter your phone number."
+              error={error.includes('phone')}
+              errorMessage="The field is required. Please enter a valid phone number."
+            />
+            <TextField
+              label="E-Mail:"
+              description="Please enter your E-Mail adress"
+              placeholder="E-Mail"
+              name="mail"
+              required
+              error={error.includes('mail')}
+              errorMessage="The field is required. Please enter a valid E-Mail adress."
+            />
+            <Select
+              name="country"
+              label="Country:"
+              description="Please select your country."
+            >
+              <Select.Option key={'none'}>Select an option...</Select.Option>
+              <Select.Option key={'germany'}>Germany</Select.Option>
+              <Select.Option key={'austria'}>Austria</Select.Option>
+              <Select.Option key={'switzerland'}>Switzerland</Select.Option>
+            </Select>
+            <Checkbox name="terms">Agree to the terms</Checkbox>
+          </Stack>
+        </Stack>
+        <Stack alignX="right">
+          <Button variant="primary" size="small" type="submit">
+            Submit
+          </Button>
+        </Stack>
+      </form>
+    </FieldGroup>
+  );
+};

packages/components/src/DateField/DateField.tsx

@@ -20,6 +20,10 @@ export interface DateFieldProps
     Pick<FieldBaseProps<'label'>, 'label' | 'description' | 'errorMessage'> {
   variant?: string;
   size?: string;
+
+  /**
+   * Optional element (e.g., button or icon) rendered inside the DateField.
+   */
   action?: ReactElement;
 
   /**