From db29b693f809e0c53492a5246c4c046b478030c4 Mon Sep 17 00:00:00 2001 From: Alaa Yahia <6881345+alaa-yahia@users.noreply.github.com> Date: Thu, 26 Sep 2024 21:08:26 +0300 Subject: [PATCH] chore: update documentation for calendar input (#1608) * chore: update documentation --- collections/forms/i18n/en.pot | 4 +- collections/ui/API.md | 17 +- components/calendar/API.md | 17 +- .../src/calendar-input/calendar-input.js | 43 ++- .../stories/calendar-input.prod.stories.js | 1 - docs/docs/components/calendar-input.md | 284 +++++++++++++++++- docs/docs/components/calendar.md | 185 ------------ docs/sidebars.js | 1 - 8 files changed, 350 insertions(+), 202 deletions(-) delete mode 100644 docs/docs/components/calendar.md diff --git a/collections/forms/i18n/en.pot b/collections/forms/i18n/en.pot index dd42956f40..bffb1bd6f0 100644 --- 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 index eb27fb75a0..e9999cb720 100644 --- 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 index 26f8eaac53..3a0af9c70b 100644 --- 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 index f7582ef407..7824d25539 100644 --- a/components/calendar/src/calendar-input/calendar-input.js +++ b/components/calendar/src/calendar-input/calendar-input.js @@ -1,7 +1,7 @@ import { useDatePicker, useResolvedDirection, - validateDateString + validateDateString, } from '@dhis2/multi-calendar-dates' import { Button } from '@dhis2-ui/button' import { Card } from '@dhis2-ui/card' @@ -9,9 +9,9 @@ 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 index 4a55f9b41a..db909a7c52 100644 --- 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'} /> diff --git a/docs/docs/components/calendar-input.md b/docs/docs/components/calendar-input.md index 5aaca0bc2a..a19680abd7 100644 --- a/docs/docs/components/calendar-input.md +++ b/docs/docs/components/calendar-input.md @@ -5,11 +5,11 @@ title: Calendar Input import { Demo } from '@site/src/components/DemoComponent.jsx' import API from '../../../components/calendar/API.md' -# Calendar Input +## Calendar Input -This is an Input wrapper around [calendar](./calendar) to display an input that shows the calendar when in focus. +The CalendarInput is an input field with an integrated calendar picker. It combines the functionality of the [Calendar](./calendar#calendar) component with an input field, allowing users to either type a date or select one from the calendar picker. -## Demo +### Demo Below you'll find a customizable demo of the CalendarInput component. Click "show full demo" to see this and other components. @@ -30,12 +30,286 @@ The Gregorian with initial date is then generated with this code. /> ``` +### MinDate and MaxDate + +This demo shows how to set minimum and maximum allowed dates. + + + +```jsx + +``` + +### StrictValidation + +This demo demonstrates the use of strict validation for date input. + +- When `strictValidation` is set to `true` (default behavior): + The component displays error indicators if a user selects or inputs a date outside the specified minimum and maximum date range. + +- When `strictValidation` is `false`: + The component shows warning indicators for dates outside the allowed range. + + + +```jsx + +``` + +### Format + +This demo illustrates how to use the format prop to specify the date string format +The format prop accepts two possible values: + +- 'YYYY-MM-DD' (default): Year-Month-Day format +- 'DD-MM-YYYY': Day-Month-Year format + + + +```jsx + +``` + +### Clearable + +This demo showcases the use of the `clearable` prop, which adds a button to clear the selected date. + + + +```jsx + +``` + +### Usage + +#### When to use + +Use the CalendarInput component when you need to: + +- Provide users with a flexible method to select a specific date, offering both manual text input and visual calendar picker. +- Implement date selection with validation, including min/max dates validation and format validation. +- Provide users with an easy way to clear a selected date. + +#### When not to use + +- This is just a Day Picker (for now). It does not allow picking periods, date ranges, or date with times. + +## Calendar + +The Calendar is a component to display a calendar to pick a day in multiple calendar systems, such as: Gregorian, Ethiopic, Nepali and many other calendrical systems. + +The component is built on top of [multi-calendar-dates](https://github.com/dhis2/multi-calendar-dates/tree/beta) which is an internal library to abstract date-related operations (i.e. calendars, period selectors, date math etc..). The library itself relies on the [Temporal proposal](https://tc39.es/proposal-temporal/#sec-temporal-intro). The proposal (currently at Stage 3 draft) aims to improve built-in support for dates and times in browsers, addressing challenges such as support for timezones, DST-safe artithemtic, string serialization and interoperability via standardized formats, and full support for non-Gregorian calendars. + +Here are some sample calendars built with this UI component. Check [StoryBook](https://ui.dhis2.nu/demo/?path=/story/calendar--ethiopic) to play with all the options available for building a Calendar. + +### Ethiopic calendar + +Ethiopic calendar with narrow day names, short day names and localised to English. + +#### Narrow day names + + + +To display the calendar with short day names, use the codeblock below. For the narrow day names remove the `weekDayFormat` prop. For the English locale, use the `en` locale and the short `weekDayFormat`. + +```jsx + +``` + +### Nepali calendar + +:::note +Nepali is a custom calendar not natively implemented in Temporal and Nepali locale is not natively supported by browsers' Internationalization standard. We are providing a custom implementation for the calendar, as well as the localised values. The only two locales allowed are: `ne-NP` (nepali) and `en-NP` (nepali transliterated in latin characters). +::: + +Nepali calendar with Napali characters. + + + +```jsx +// Napali + +``` + +Nepali calendar transliterated into latin characters. + + +```jsx +// Nepali transliterated in latin characters + +``` + +### Gregorian calendar + +Gregorian calendar localised in English, Arabic (Tunisia), Arabic (Sudan), Arabic (Iraq) and Amharic. + + + + + + + + + + + + + + + + + + + +To display the calendar with a specific locale, use the codeblock below. Adjust the locale to the desired language. + +```jsx + +``` + +### Other calendars + +Some other calendars: Islamic in Arabic, Indian in English and Persian in Farsi + + + + + + + + + + + + + +Each of the calendars above can be displayed with the following code. + +```jsx + +``` + +:::note +Additionally the component supports a number of other calendars that are not currently used in DHIS2, since they're implemented in the [Temporal API](https://tc39.es/proposal-temporal/)). These other calendars are: `hebrew`, `islamic`, `islamic-umalqura`, `islamic-tbla`, `islamic-civil`, `islamic-rgsa`, `persian`, `ethioaa`, `coptic`, `chinese`, `dangi`, `roc`, `indian`, `buddhist`, `japanese`. +::: + +### Usage + +#### When to use + +To display a calendar for the user to pick a day in any supported calendar system, localised to any of the 90+ languages supported by [The Unicode Common Locale Data Repository (CLDR)](https://cldr.unicode.org/index) supported natively in all modern browsers. Supported DHIS2 calendars are: `iso8601` (i.e. the Gregorian calendar common in most of the world),`ethiopic`, `nepali` (custom implementation). + +#### When not to use + +- This is just a Day Picker (for now). It does not allow picking periods, date ranges, or date with times. + ## API Reference -The component takes the same props as [the calendar](./calendar) component, as well as the props for [InputField](./inputfield) that are relevant to an input of type `text`. +The calendar input takes the same props as [the calendar](./calendar#calendar) component, as well as the props for [InputField](./inputfield) that are relevant to an input of type `text`. It adds one property `clearable` which is a boolean. If set to true, it adds a clear button to delete the selected date. + + ## Links -- [Calendar](./calendar) +- Calendar Input Demo +- Calendar Demo +- [Design document](https://docs.google.com/document/d/19zjyB45oBbqC5KeubaU8E7cw9fGhFc3tOXY0GkzZKqc/edit#) +- [ADR for decision to use Temporal API](https://github.com/dhis2/multi-calendar-dates/blob/beta/doc/architecture/decisions/0002-use-temporal-api-as-the-backbone-for-the-engine.md) +- [multi-calendar-dates](https://github.com/dhis2/multi-calendar-dates) is the library that this component is built on top of. +- [Temporal API standard propsal](https://tc39.es/proposal-temporal/): the standard powering the multi-calendar-dates library diff --git a/docs/docs/components/calendar.md b/docs/docs/components/calendar.md deleted file mode 100644 index 0da47ffcc0..0000000000 --- a/docs/docs/components/calendar.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Calendar ---- - -import { Demo } from '@site/src/components/DemoComponent.jsx' -import Tabs from '@theme/Tabs' -import TabItem from '@theme/TabItem' - -import API from '../../../components/calendar/API.md' - -# Calendar - -The Calendar is a component to display a calendar to pick a day in multiple calendar systems, such as: Gregorian, Ethiopic, Nepali and many other calendrical systems. - -The component is built on top of [multi-calendar-dates](https://github.com/dhis2/multi-calendar-dates/tree/beta) which is an internal library to abstract date-related operations (i.e. calendars, period selectors, date math etc..). The library itself relies on the [Temporal proposal](https://tc39.es/proposal-temporal/#sec-temporal-intro). The proposal (currently at Stage 3 draft) aims to improve built-in support for dates and times in browsers, addressing challenges such as support for timezones, DST-safe artithemtic, string serialization and interoperability via standardized formats, and full support for non-Gregorian calendars. - -Here are some sample calendars built with this UI component. Check [StoryBook]((https://ui.dhis2.nu/demo/?path=/story/calendar--with-ethiopic) to play with all the options available for building a Calendar. - -## Ethiopic calendar - -Ethiopic calendar with narrow day names, short day names and localised to English. - -### Narrow day names - - - -To display the calendar with short day names, use the codeblock below. For the narrow day names remove the `weekDayFormat` prop. For the English locale, use the `en` locale and the short `weekDayFormat`. - -```jsx - -``` - -## Nepali calendar - -:::note -Nepali is a custom calendar not natively implemented in Temporal and Nepali locale is not natively supported by browsers' Internationalization standard. We are providing a custom implementation for the calendar, as well as the localised values. The only two locales allowed are: `ne-NP` (nepali) and `en-NP` (nepali transliterated in latin characters). -::: - -Nepali calendar with Napali characters. - - - -```jsx -// Napali - -``` - -Nepali calendar transliterated into latin characters. - - -```jsx -// Nepali transliterated in latin characters - -``` - -## Gregorian calendar - -Gregorian calendar localised in English, Arabic (Tunisia), Arabic (Sudan), Arabic (Iraq) and Amharic. - - - - - - - - - - - - - - - - - - - -To display the calendar with a specific locale, use the codeblock below. Adjust the locale to the desired language. - -```jsx - -``` - -## Other calendars - -Some other calendars: Islamic in Arabic, Indian in English and Persian in Farsi - - - - - - - - - - - - - -Each of the calendars above can be displayed with the following code. - -```jsx - -``` - -:::note -Additionally the component supports a number of other calendars that are not currently used in DHIS2, since they're implemented in the [Temporal API](https://tc39.es/proposal-temporal/)). These other calendars are: `hebrew`, `islamic`, `islamic-umalqura`, `islamic-tbla`, `islamic-civil`, `islamic-rgsa`, `persian`, `ethioaa`, `coptic`, `chinese`, `dangi`, `roc`, `indian`, `buddhist`, `japanese`. -::: - -## Usage - -### When to use - -To display a calendar for the user to pick a day in any supported calendar system, localised to any of the 90+ languages supported by [The Unicode Common Locale Data Repository (CLDR)](https://cldr.unicode.org/index) supported natively in all modern browsers. Supported DHIS2 calendars are: `iso8601` (i.e. the Gregorian calendar common in most of the world),`ethiopic`, `nepali` (custom implementation). - -### When not to use - -- This is just a Day Picker (for now). It does not allow picking periods, date ranges, or date with times. - -## API Reference - - - -## Links - -- Demo -- [Design document](https://docs.google.com/document/d/19zjyB45oBbqC5KeubaU8E7cw9fGhFc3tOXY0GkzZKqc/edit#) -- [ADR for decision to use Temporal API](https://github.com/dhis2/multi-calendar-dates/blob/beta/doc/architecture/decisions/0002-use-temporal-api-as-the-backbone-for-the-engine.md) -- [multi-calendar-dates](https://github.com/dhis2/multi-calendar-dates) is the library that this component is built on top of. -- [Temporal API standard propsal](https://tc39.es/proposal-temporal/): the standard powering the multi-calendar-dates library diff --git a/docs/sidebars.js b/docs/sidebars.js index 17b9c320ac..13f2e954c7 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -44,7 +44,6 @@ const sidebars = { 'components/alertbar', 'components/button', 'components/card', - 'components/calendar', 'components/calendar-input', 'components/checkbox', 'components/chip',