chore: update documentation for calendar input (#1608)

* chore: update documentation
dhis2 · Sep 26, 2024 · db29b69 · db29b69
1 parent e9c4833
commit db29b69
Show file tree

Hide file tree

Showing 8 changed files with 350 additions and 202 deletions.
diff --git a/collections/forms/i18n/en.pot b/collections/forms/i18n/en.pot
@@ -5,8 +5,8 @@ msgstr ""
 "Content-Type: text/plain; charset=utf-8\n"
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=2; plural=(n != 1)\n"
-"POT-Creation-Date: 2024-09-09T12:09:30.724Z\n"
-"PO-Revision-Date: 2024-09-09T12:09:30.724Z\n"
+"POT-Creation-Date: 2024-09-26T14:15:11.940Z\n"
+"PO-Revision-Date: 2024-09-26T14:15:11.941Z\n"
 
 msgid "Upload file"
 msgstr "Upload file"

diff --git a/collections/ui/API.md b/collections/ui/API.md
@@ -247,7 +247,22 @@ import { CalendarInput } from '@dhis2/ui'
 
 |Name|Type|Default|Required|Description|
 |---|---|---|---|---|
-|dataTest|undefined|`'dhis2-uiwidgets-calendar-inputfield'`|||
+|calendar|any||*|the calendar to use such gregory, ethiopic, nepali - full supported list here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/calendars.ts|
+|onDateSelect|function||*|Called with signature `(null)` \|\| `({ dateCalendarString: string, dateCalendar: Temporal.ZonedDateTime })` with `dateCalendarString` being the stringified date in the specified calendar in the format `yyyy-MM-dd`|
+|cellSize|string|`'32px'`||the size of a single cell in the table forming the calendar|
+|clearable|boolean|||Whether the clear button is displayed|
+|dataTest|string|`'dhis2-uiwidgets-calendar-inputfield'`||'data-test' attribute of `InputField` component|
+|date|string|||the currently selected date using an iso-like format YYYY-MM-DD, in the calendar system provided (not iso8601)|
+|dir|'ltr' │ 'rtl'|||the direction of the library - internally the library will use rtl for rtl-languages but this can be overridden here for more control|
+|format|'YYYY-MM-DD' │ 'DD-MM-YYYY'|||The date format to use either `YYYY-MM-DD` or `DD-MM-YYYY`|
+|locale|string|||any valid locale - if none provided, the internal library will fallback to the user locale (more info here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/hooks/internal/useResolvedLocaleOptions.ts#L15)|
+|maxDate|string|||The maximum selectable date|
+|minDate|string|||The minimum selectable date|
+|numberingSystem|string|||numbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts|
+|strictValidation|boolean|||Whether to use strict validation by showing errors for out-of-range dates when enabled (default), and warnings when disabled|
+|timeZone|string|||the timeZone to use|
+|weekDayFormat|'narrow' │ 'short' │ 'long'|`'narrow'`||the format to display for the week day, i.e. Monday (long), Mon (short), M (narrow)|
+|width|string|`'240px'`||the width of the calendar component|
 
 ### Card
 

diff --git a/components/calendar/API.md b/components/calendar/API.md
@@ -41,4 +41,19 @@ import { CalendarInput } from '@dhis2/ui'
 
 |Name|Type|Default|Required|Description|
 |---|---|---|---|---|
-|dataTest|undefined|`'dhis2-uiwidgets-calendar-inputfield'`|||
+|calendar|any||*|the calendar to use such gregory, ethiopic, nepali - full supported list here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/calendars.ts|
+|onDateSelect|function||*|Called with signature `(null)` \|\| `({ dateCalendarString: string, dateCalendar: Temporal.ZonedDateTime })` with `dateCalendarString` being the stringified date in the specified calendar in the format `yyyy-MM-dd`|
+|cellSize|string|`'32px'`||the size of a single cell in the table forming the calendar|
+|clearable|boolean|||Whether the clear button is displayed|
+|dataTest|string|`'dhis2-uiwidgets-calendar-inputfield'`||'data-test' attribute of `InputField` component|
+|date|string|||the currently selected date using an iso-like format YYYY-MM-DD, in the calendar system provided (not iso8601)|
+|dir|'ltr' │ 'rtl'|||the direction of the library - internally the library will use rtl for rtl-languages but this can be overridden here for more control|
+|format|'YYYY-MM-DD' │ 'DD-MM-YYYY'|||The date format to use either `YYYY-MM-DD` or `DD-MM-YYYY`|
+|locale|string|||any valid locale - if none provided, the internal library will fallback to the user locale (more info here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/hooks/internal/useResolvedLocaleOptions.ts#L15)|
+|maxDate|string|||The maximum selectable date|
+|minDate|string|||The minimum selectable date|
+|numberingSystem|string|||numbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts|
+|strictValidation|boolean|||Whether to use strict validation by showing errors for out-of-range dates when enabled (default), and warnings when disabled|
+|timeZone|string|||the timeZone to use|
+|weekDayFormat|'narrow' │ 'short' │ 'long'|`'narrow'`||the format to display for the week day, i.e. Monday (long), Mon (short), M (narrow)|
+|width|string|`'240px'`||the width of the calendar component|
diff --git a/components/calendar/src/calendar-input/calendar-input.js b/components/calendar/src/calendar-input/calendar-input.js
@@ -1,17 +1,17 @@
 import {
  useDatePicker,
  useResolvedDirection,
- validateDateString
+ validateDateString,
 } from '@dhis2/multi-calendar-dates'
 import { Button } from '@dhis2-ui/button'
 import { Card } from '@dhis2-ui/card'
 import { InputField } from '@dhis2-ui/input'
 import { Layer } from '@dhis2-ui/layer'
 import { Popper } from '@dhis2-ui/popper'
 import cx from 'classnames'
+import PropTypes from 'prop-types'
 import React, { useRef, useState, useMemo, useEffect } from 'react'
 import { CalendarContainer } from '../calendar/calendar-container.js'
-import { CalendarProps } from '../calendar/calendar.js'
 import i18n from '../locales/index.js'
 
 const offsetModifier = {
@@ -29,7 +29,6 @@ export const CalendarInput = ({
  locale,
  numberingSystem,
  weekDayFormat,
- timeZone,
  width,
  cellSize,
  clearable,
@@ -51,11 +50,10 @@ export const CalendarInput = ({
  () => ({
  calendar,
  locale,
- timeZone, // todo: we probably shouldn't have had timezone here in the first place
  numberingSystem,
  weekDayFormat,
  }),
- [calendar, locale, numberingSystem, timeZone, weekDayFormat]
+ [calendar, locale, numberingSystem, weekDayFormat]
  )
 
  const pickerResults = useDatePicker({
@@ -207,7 +205,40 @@ export const CalendarInput = ({
 
 CalendarInput.defaultProps = {
  dataTest: 'dhis2-uiwidgets-calendar-inputfield',
+ cellSize: '32px',
+ width: '240px',
+ weekDayFormat: 'narrow',
 }
+
 CalendarInput.propTypes = {
- ...CalendarProps,
+ /** the calendar to use such gregory, ethiopic, nepali - full supported list here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/calendars.ts */
+ calendar: PropTypes.any.isRequired,
+ /** Called with signature `(null)` \|\| `({ dateCalendarString: string, dateCalendar: Temporal.ZonedDateTime })` with `dateCalendarString` being the stringified date in the specified calendar in the format `yyyy-MM-dd` */
+ onDateSelect: PropTypes.func.isRequired,
+ /** the size of a single cell in the table forming the calendar */
+ cellSize: PropTypes.string,
+ /** Whether the clear button is displayed */
+ clearable: PropTypes.bool,
+ /** 'data-test' attribute of `InputField` component */
+ dataTest: PropTypes.string,
+ /** the currently selected date using an iso-like format YYYY-MM-DD, in the calendar system provided (not iso8601) */
+ date: PropTypes.string,
+ /** the direction of the library - internally the library will use rtl for rtl-languages but this can be overridden here for more control */
+ dir: PropTypes.oneOf(['ltr', 'rtl']),
+ /** The date format to use either `YYYY-MM-DD` or `DD-MM-YYYY` */
+ format: PropTypes.oneOf(['YYYY-MM-DD', 'DD-MM-YYYY']),
+ /** any valid locale - if none provided, the internal library will fallback to the user locale (more info here: https://github.com/dhis2/multi-calendar-dates/blob/main/src/hooks/internal/useResolvedLocaleOptions.ts#L15) */
+ locale: PropTypes.string,
+ /** The maximum selectable date */
+ maxDate: PropTypes.string,
+ /** The minimum selectable date */
+ minDate: PropTypes.string,
+ /** numbering system to use - full list here https://github.com/dhis2/multi-calendar-dates/blob/main/src/constants/numberingSystems.ts */
+ numberingSystem: PropTypes.string,
+ /** Whether to use strict validation by showing errors for out-of-range dates when enabled (default), and warnings when disabled */
+ strictValidation: PropTypes.bool,
+ /** the format to display for the week day, i.e. Monday (long), Mon (short), M (narrow) */
+ weekDayFormat: PropTypes.oneOf(['narrow', 'short', 'long']),
+ /** the width of the calendar component */
+ width: PropTypes.string,
 }
diff --git a/components/calendar/src/stories/calendar-input.prod.stories.js b/components/calendar/src/stories/calendar-input.prod.stories.js
@@ -133,7 +133,6 @@ export function CalendarWithEditiableInput() {
  }}
  width={'700px'}
  inputWidth="900px"
- timeZone={'UTC'}
  minDate={'2020-07-01'}
  maxDate={'2020-07-09'}
  />