@neo4j-ndl/react 4.16.8 → 4.16.9

package/skills/ndl-react/components/date-picker.md

@@ -0,0 +1,652 @@
+# DatePicker
+
+Import: `import { DatePicker } from '@neo4j-ndl/react'`
+
+## Props
+
+### DatePicker
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `isClearable` | `boolean` |  | `false` | Whether to show the clear button. |
+| `isDisabled` | `boolean` |  |  | Whether the date picker is disabled. |
+| `reactDatePickerProps` | `DatePickerProps` | ✅ |  | Props forwarded to underlying `react-datepicker` component. |
+| `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
+| `textInputProps` | `(TextInputProps & BaseProps<"input">)` |  |  | Props for the embedded `TextInput` component. |
+| `timePickerProps` | `TimePickerProps` |  |  | Props for the embedded `TimePicker` component. |
+| `timeZonePickerProps` | `(TimeZonePickerProps & BaseProps<"input">)` |  |  | Props for the embedded `TimeZonePicker` component. |
+
+The `reactDatePickerProps` prop is forwarded to the underlying `react-datepicker` component. See the [react-datepicker documentation](https://reactdatepicker.com/) for more information.
+
+Where `TextInputProps` is defined in the `TextInput` component and `TimePickerProps` is defined in the `TimePicker` component.
+
+## Accessibility
+
+## Implementation guidelines
+
+You must provide an `aria-label` or label via the `textInputProps` prop to the underlying input element for accessibility. Use the `htmlAttributes` prop in the `textInputProps` prop to add additional attributes to the input element, not the `htmlAttributes` prop on the root level of the DatePicker component.
+
+## Examples
+
+### Default
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      reactDatePickerProps={{
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Clearable
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+export const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      isClearable
+      reactDatePickerProps={{
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Clearable date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Disabled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      isDisabled={true}
+      reactDatePickerProps={{
+        onChange: handleOnChange,
+        selected: selectedDate,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Full
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      textInputProps={{
+        helpText: 'With help text',
+        isDisabled: false,
+        isFluid: false,
+        isReadOnly: false,
+        isRequired: false,
+        label: 'This one has a label',
+        moreInformationText: 'With information icon text',
+        showRequiredOrOptionalLabel: false,
+      }}
+      timePickerProps={{
+        format: 'hh:mm aa',
+        isDisabled: false,
+        isFluid: false,
+        isReadOnly: false,
+        isRequired: false,
+        timeInterval: 20,
+      }}
+      reactDatePickerProps={{
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+        showTimeInput: true,
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### In Dialog
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker, Dialog } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <Dialog isOpen={true} aria-label="Dialog">
+      <Dialog.Header>Using Date Picker inside a dialog</Dialog.Header>
+      <Dialog.Description className="n-flex n-flex-col n-gap-token-32">
+        <DatePicker
+          timePickerProps={{
+            timeInterval: 20,
+          }}
+          reactDatePickerProps={{
+            onChange: handleOnChange,
+            selected: selectedDate,
+            showTimeInput: true,
+          }}
+          textInputProps={{
+            htmlAttributes: {
+              'aria-label': 'Date picker input',
+            },
+          }}
+        />
+      </Dialog.Description>
+    </Dialog>
+  );
+};
+
+export default Component;
+```
+
+### Min Max Date
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { addWeeks } from 'date-fns';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('1994-10-03'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      reactDatePickerProps={{
+        maxDate: addWeeks(new Date('1994-10-01'), 1),
+        minDate: new Date('1994-10-01'),
+        onChange: handleOnChange,
+        openToDate: new Date('1994-10-01'),
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Opens To Date
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      reactDatePickerProps={{
+        highlightDates: [new Date('2010-02-01')],
+        onChange: handleOnChange,
+        openToDate: new Date('2010-02-01'),
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Portaled
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <div id="datepicker-portal-root">
+      <DatePicker
+        reactDatePickerProps={{
+          onChange: handleOnChange,
+          popperProps: {
+            strategy: 'fixed',
+          },
+          portalId: 'datepicker-portal-root',
+          selected: selectedDate,
+        }}
+        textInputProps={{
+          htmlAttributes: {
+            'aria-label': 'Date picker input',
+          },
+        }}
+      />
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### Range
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [dates, setDates] = useState<[Date | null, Date | null]>([
+    new Date('2023-05-05'),
+    new Date('2023-05-08'),
+  ]);
+
+  const handleOnChange = (dates: [Date | null, Date | null]) => {
+    setDates(dates);
+  };
+
+  return (
+    <DatePicker
+      reactDatePickerProps={{
+        endDate: dates[1],
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selectsRange: true,
+        startDate: dates[0],
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Starts On Monday
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      reactDatePickerProps={{
+        calendarStartDay: 1,
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### Text Input Props
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      textInputProps={{
+        helpText: 'With help text',
+        label: 'This one has a label',
+      }}
+      reactDatePickerProps={{
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### With Time Picker
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27'),
+  );
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  return (
+    <DatePicker
+      timePickerProps={{
+        format: 'hh:mm',
+        timeInterval: 20,
+      }}
+      reactDatePickerProps={{
+        dateFormat: 'yyyy-MM-dd hh:mm',
+        onChange: handleOnChange,
+        popperProps: {
+          strategy: 'fixed',
+        },
+        selected: selectedDate,
+        showTimeInput: true,
+      }}
+      textInputProps={{
+        htmlAttributes: {
+          'aria-label': 'Date picker input',
+        },
+      }}
+    />
+  );
+};
+
+export default Component;
+```
+
+### With Timezone
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DatePicker } from '@neo4j-ndl/react';
+import { useState } from 'react';
+
+const Component = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    new Date('2023-05-27T14:30:00'),
+  );
+  const [selectedTimeZone, setSelectedTimeZone] = useState<string>('UTC');
+
+  const handleOnChange = (date: Date | null) => {
+    setSelectedDate(date);
+  };
+
+  const handleTimeZoneChange = (timezone: string) => {
+    setSelectedTimeZone(timezone);
+  };
+
+  return (
+    <div>
+      <DatePicker
+        timePickerProps={{
+          format: 'hh:mm',
+          timeInterval: 15,
+        }}
+        timeZonePickerProps={{
+          onChange: handleTimeZoneChange,
+          value: selectedTimeZone,
+        }}
+        reactDatePickerProps={{
+          onChange: handleOnChange,
+          popperProps: {
+            strategy: 'fixed',
+          },
+          selected: selectedDate,
+          showTimeInput: true,
+        }}
+        textInputProps={{
+          htmlAttributes: {
+            'aria-label': 'Date picker input',
+          },
+        }}
+      />
+      <div style={{ marginTop: '1rem' }}>
+        <p>
+          <strong>Selected Date:</strong>{' '}
+          {selectedDate ? selectedDate.toISOString() : 'None'}
+        </p>
+        <p>
+          <strong>Selected Timezone:</strong> {selectedTimeZone}
+        </p>
+      </div>
+    </div>
+  );
+};
+
+export default Component;
+```
+
+### With Timezone Both Mode
+
+```tsx
+import { useState } from 'react';
+
+import { Typography } from '../../typography';
+import { DatePicker } from '../DatePicker';
+
+export const DatePickerWithTimeZoneBothMode = () => {
+  const [selectedDate, setSelectedDate] = useState<Date | null>(
+    // Every day is Christmas in Needle :)
+    new Date('2025-12-24'),
+  );
+  const [selectedTimeZone, setSelectedTimeZone] =
+    useState<string>('America/New_York');
+
+  return (
+    <div style={{ maxWidth: '400px', padding: '20px' }}>
+      <Typography variant="title-4" style={{ marginBottom: '16px' }}>
+        DatePicker with TimeZone (Both Mode)
+      </Typography>
+      <Typography variant="body-medium" style={{ marginBottom: '24px' }}>
+        This example shows the DatePicker with the TimeZonePicker in
+        &quot;both&quot; mode, displaying both UTC offsets and city-based
+        timezones in separate sections.
+      </Typography>
+
+      <DatePicker
+        textInputProps={{
+          label: 'Select Date and Time with Timezone',
+        }}
+        timePickerProps={{
+          format: 'hh:mm',
+        }}
+        timeZonePickerProps={{
+          mode: 'both',
+          onChange: (tz) => {
+            setSelectedTimeZone(tz);
+          },
+          value: selectedTimeZone,
+        }}
+        reactDatePickerProps={{
+          dateFormat: 'yyyy-MM-dd hh:mm',
+          onChange: (date) => {
+            setSelectedDate(date);
+          },
+          selected: selectedDate,
+          showTimeInput: true,
+        }}
+      />
+
+      <div
+        style={{
+          backgroundColor: 'var(--theme-color-neutral-bg-default)',
+          borderRadius: '4px',
+          display: 'flex',
+          flexDirection: 'column',
+          marginTop: '24px',
+          padding: '16px',
+        }}
+      >
+        <Typography variant="label">Selected Values:</Typography>
+        <Typography variant="body-small">
+          <strong>Date: </strong>
+          {selectedDate?.toISOString() ?? 'None'}
+        </Typography>
+        <Typography variant="body-small">
+          <strong>Timezone:</strong> {selectedTimeZone || 'None'}
+        </Typography>
+      </div>
+    </div>
+  );
+};
+
+export default DatePickerWithTimeZoneBothMode;
+```