From 333446ee14ef25bec3d499381bf4be175a891a9f Mon Sep 17 00:00:00 2001
From: Bruno Henriques <zettca@users.noreply.github.com>
Date: Fri, 22 Nov 2024 14:28:16 +0000
Subject: [PATCH] docs: add DatePicker & TimePicker

---
 .../docs/src/pages/components/date-picker.mdx | 196 ++++++++++++++++++
 .../docs/src/pages/components/time-picker.mdx | 102 +++++++++
 2 files changed, 298 insertions(+)
 create mode 100644 apps/docs/src/pages/components/date-picker.mdx
 create mode 100644 apps/docs/src/pages/components/time-picker.mdx

diff --git a/apps/docs/src/pages/components/date-picker.mdx b/apps/docs/src/pages/components/date-picker.mdx
new file mode 100644
index 0000000000..f57b400916
--- /dev/null
+++ b/apps/docs/src/pages/components/date-picker.mdx
@@ -0,0 +1,196 @@
+import {
+  datePickerClasses,
+  HvDatePicker,
+  theme,
+} from "@hitachivantara/uikit-react-core";
+
+import Playground from "@docs/components/code/Playground";
+import { Description } from "@docs/components/page/Description";
+import { Page } from "@docs/components/page/Page";
+import { getComponentData } from "@docs/utils/component";
+
+export const getStaticProps = async ({ params }) => {
+  const meta = await getComponentData("DatePicker", "core", datePickerClasses);
+  return { props: { ssg: { meta } } };
+};
+
+<Description />
+
+<Page>
+
+<Playground
+  Component={HvDatePicker}
+  componentName="HvDatePicker"
+  controls={{
+    label: { type: "text", defaultValue: "Date" },
+    required: { type: "check", defaultValue: false },
+    readOnly: { type: "check", defaultValue: false },
+    disabled: { type: "check", defaultValue: false },
+  }}
+  componentProps={{
+    placeholder: "Select a date",
+  }}
+/>
+
+### Actions
+
+Use the `showActions` property to display Apply/Cancel buttons at the bottom.
+
+```tsx live
+<HvDatePicker
+  showActions
+  value={new Date("1970-02-03")}
+  placeholder="Select date"
+  label="Date"
+/>
+```
+
+### Custom labels
+
+Use the `labels` object to customize the internal labels of the date picker.
+
+```jsx live
+<HvDatePicker
+  showActions
+  label="This is the title for the date picker"
+  placeholder="Custom placeholder"
+  labels={{
+    applyLabel: "Custom apply",
+    cancelLabel: "Custom cancel",
+    clearLabel: "Custom clear",
+    invalidDateLabel: "Custom invalid",
+  }}
+/>
+```
+
+### Controlled
+
+```tsx live
+import { useState } from "react";
+
+export default function Demo() {
+  const [date, setDate] = useState(new Date("2020-01-02"));
+  const [open, setOpen] = useState(false);
+
+  const addDay = () => {
+    if (!date) return;
+    setDate(new Date(date.setDate(date.getDate() + 1)));
+  };
+
+  const toggleOpen = () => setOpen((o) => !o);
+
+  return (
+    <>
+      <HvDatePicker
+        style={{ flex: 1 }}
+        expanded={open}
+        aria-label="Date"
+        placeholder="Select date"
+        value={date}
+        onChange={(d) => setDate(d!)}
+        onToggle={toggleOpen}
+      />
+      <HvButton variant="secondarySubtle" onClick={addDay}>
+        +1 Day
+      </HvButton>
+      <HvButton variant="secondarySubtle" onClick={toggleOpen}>
+        {open ? "Close" : "Open"}
+      </HvButton>
+    </>
+  );
+}
+```
+
+### Range mode
+
+Use `rangeMode` to enable the selection of a range of dates. When doing so, use `startValue` and `endValue` to set the initial values, instead of the `value` prop.
+
+```jsx live
+<HvDatePicker
+  label="Date"
+  placeholder="Select a range"
+  rangeMode
+  startValue={new Date("2020-02-02")}
+  endValue={new Date("2020-02-10")}
+/>
+```
+
+### Restricted selection
+
+You can restrict the selection of dates by setting the `minimumDate` and `maximumDate` properties.
+
+```jsx live
+<HvDatePicker
+  label="Date"
+  placeholder="Select date"
+  value={new Date("2020-01-15")}
+  calendarProps={{
+    minimumDate: new Date("2020-01-10"),
+    maximumDate: new Date("2020-01-20"),
+  }}
+/>
+```
+
+### Selection list
+
+Custom content can be added to the Date Picker by using the `startAdornment` property. This can be used to display a list of predefined dates, for example.
+
+```tsx live
+import { useState } from "react";
+
+export default function Demo() {
+  const [date, setDate] = useState(new Date("2020-09-05"));
+
+  const options = (
+    <HvListContainer role="menu" style={{ minWidth: 100 }} interactive>
+      <HvListItem role="menuitem" disabled>
+        Today
+      </HvListItem>
+      <HvListItem role="menuitem" disabled>
+        Yesterday
+      </HvListItem>
+      <HvListItem
+        role="menuitem"
+        onClick={() => {
+          setDate((d) => {
+            const newDate = new Date(d);
+            newDate.setDate(1);
+            return newDate;
+          });
+        }}
+      >
+        Start of the month
+      </HvListItem>
+      <HvListItem
+        role="menuitem"
+        onClick={() => {
+          setDate((d) => {
+            const newDate = new Date(d);
+            newDate.setDate(1);
+            newDate.setMonth(0);
+            return newDate;
+          });
+        }}
+      >
+        Start of year
+      </HvListItem>
+    </HvListContainer>
+  );
+
+  return (
+    <HvDatePicker
+      label="Date"
+      startAdornment={<HvPanel>{options}</HvPanel>}
+      value={date}
+      onChange={(newDate) => setDate(newDate)}
+    />
+  );
+}
+```
+
+### Related components
+
+- [`HvInput`](/components/input)
+- [`HvTimePicker`](/components/time-picker)
+
+</Page>
diff --git a/apps/docs/src/pages/components/time-picker.mdx b/apps/docs/src/pages/components/time-picker.mdx
new file mode 100644
index 0000000000..a0d62156f2
--- /dev/null
+++ b/apps/docs/src/pages/components/time-picker.mdx
@@ -0,0 +1,102 @@
+import {
+  HvTimePicker,
+  theme,
+  timePickerClasses,
+} from "@hitachivantara/uikit-react-core";
+
+import Playground from "@docs/components/code/Playground";
+import { Description } from "@docs/components/page/Description";
+import { Page } from "@docs/components/page/Page";
+import { getComponentData } from "@docs/utils/component";
+
+export const getStaticProps = async ({ params }) => {
+  const meta = await getComponentData("TimePicker", "core", timePickerClasses);
+  return { props: { ssg: { meta } } };
+};
+
+<Description />
+
+<Page>
+
+<Playground
+  Component={HvTimePicker}
+  componentName="HvTimePicker"
+  controls={{
+    label: { type: "text", defaultValue: "Time" },
+    required: { type: "check", defaultValue: false },
+    readOnly: { type: "check", defaultValue: false },
+    disabled: { type: "check", defaultValue: false },
+    showSeconds: { type: "check", defaultValue: true },
+    timeFormat: { type: "radio", defaultValue: "24" },
+  }}
+  componentProps={{
+    defaultValue: { hours: 20, minutes: 21, seconds: 22 },
+  }}
+/>
+
+### Form
+
+A Time Picker usage inside a `form` element. Give `HvTimePicker` a `name`, and it will be included in the form data,
+following the time [`input` format](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time) specification.
+
+```jsx live
+<form
+  onSubmit={(event) => {
+    event.preventDefault();
+    const formData = new FormData(event.currentTarget);
+    alert(JSON.stringify(Object.fromEntries(formData)));
+  }}
+>
+  <HvTimePicker
+    name="scheduleTime"
+    label="Time Picker"
+    defaultValue={{ hours: 5, minutes: 30, seconds: 14 }}
+  />
+  <br />
+  <HvButton type="submit" variant="subtle">
+    Submit
+  </HvButton>
+</form>
+```
+
+### Controlled
+
+```tsx live
+import { useState } from "react";
+
+export default function Demo() {
+  const [value, setValue] = useState<HvTimePickerProps["value"]>(null);
+
+  const prettyValue = value
+    ? `${value.hours}h ${value.minutes}'${value.seconds}"`
+    : "—";
+
+  return (
+    <div className="grid gap-sm">
+      <HvTypography variant="title4">Date: {prettyValue}</HvTypography>
+      <HvTimePicker
+        label="Time Picker"
+        placeholder="Select a time"
+        value={value}
+        onChange={setValue}
+      />
+      <HvButton
+        variant="subtle"
+        disabled={!value}
+        onClick={() => {
+          setValue((d) => d && { ...d, minutes: (d.minutes + 1) % 60 });
+        }}
+      >
+        +1 minute
+      </HvButton>
+    </div>
+  );
+}
+```
+
+### Related components
+
+- [`HvInput`](/components/input)
+- [`HvDatePicker`](/components/date-picker)
+
+</Page>