From 17533927e0a42b7a196518eb54b828f72e137122 Mon Sep 17 00:00:00 2001 From: Quek Ruo Ling Date: Thu, 18 May 2023 16:01:19 +0800 Subject: [PATCH] [MISC][RL] Update props documentation --- src/time-range-picker/time-range-picker.tsx | 24 +++++----- src/time-range-picker/types.ts | 30 +++++++++---- src/timepicker/timepicker.tsx | 6 +-- src/timepicker/types.ts | 21 ++++++--- .../form-time-range-picker.stories.mdx | 37 ++++++++++++--- .../form-time-range-picker/props-table.tsx | 45 ++++++++++--------- stories/form/form-timepicker/props-table.tsx | 21 --------- 7 files changed, 107 insertions(+), 77 deletions(-) diff --git a/src/time-range-picker/time-range-picker.tsx b/src/time-range-picker/time-range-picker.tsx index e46380281..9af01fe6d 100644 --- a/src/time-range-picker/time-range-picker.tsx +++ b/src/time-range-picker/time-range-picker.tsx @@ -8,7 +8,7 @@ import { TimeContainer, Wrapper, } from "./time-range-picker.styles"; -import { TimeRangeInputValue, TimeRangePickerProps } from "./types"; +import { TimeRangePickerProps, TimeRangePickerValue } from "./types"; export const TimeRangePicker = ({ id, @@ -28,21 +28,21 @@ export const TimeRangePicker = ({ useState(false); const [showEndTimeSelector, setShowEndTimeSelector] = useState(false); - const [startTimeVal, setStartTimeVal] = useState(""); - const [endTimeVal, setEndTimeVal] = useState(""); + const [startTimeVal, setStartTimeVal] = useState(""); + const [endTimeVal, setEndTimeVal] = useState(""); const nodeRef = useRef(); // ============================================================================= // EFFECTS // ============================================================================= - useEffect(() => { if (value) { - setStartTimeVal(value.startTime); - setEndTimeVal(value.endTime); + setStartTimeVal(value.start); + setEndTimeVal(value.end); } }, []); + useEffect(() => { document.addEventListener("mousedown", handleMouseDownEvent); document.addEventListener("keyup", handleKeyUpEvent); @@ -96,9 +96,9 @@ export const TimeRangePicker = ({ setShowEndTimeSelector(true); setStartTimeVal(value); - const timeValue: TimeRangeInputValue = { - startTime: value, - endTime: endTimeVal, + const timeValue: TimeRangePickerValue = { + start: value, + end: endTimeVal, }; onChange && onChange(timeValue); @@ -112,9 +112,9 @@ export const TimeRangePicker = ({ setShowStartTimeSelector(true); } - const timeValue: TimeRangeInputValue = { - startTime: startTimeVal, - endTime: value, + const timeValue: TimeRangePickerValue = { + start: startTimeVal, + end: value, }; onChange && onChange(timeValue); diff --git a/src/time-range-picker/types.ts b/src/time-range-picker/types.ts index 3e983ae58..ef5f52429 100644 --- a/src/time-range-picker/types.ts +++ b/src/time-range-picker/types.ts @@ -1,8 +1,8 @@ export type TimeRangePickerFormat = "12hr" | "24hr"; -export interface TimeRangeInputValue { - startTime: string; - endTime: string; +export interface TimeRangePickerValue { + start: string; + end: string; } export interface TimeRangePickerProps { @@ -10,15 +10,29 @@ export interface TimeRangePickerProps { className?: string | undefined; id?: string | undefined; style?: React.CSSProperties | undefined; - readOnly?: boolean | undefined; - "data-testid"?: string | undefined; // Input-specific attributes - - value?: TimeRangeInputValue | undefined; + "data-testid"?: string | undefined; + /** + * An object with `start` and `end` values. Can be an empty string or a + * string based format. 24 hour uses "hh:mm", while 12 hour uses "hh:mma" + */ + value?: TimeRangePickerValue | undefined; + /** + * The time input format in `12hr` or `24hr`. Defaults to `24hr` + */ format?: TimeRangePickerFormat | undefined; disabled?: boolean | undefined; + readOnly?: boolean | undefined; error?: boolean | undefined; - onChange?: ((value: TimeRangeInputValue) => void) | undefined; + /** + * Called when a selection is made. Returns an object with `start` and + * `end` values. Can be an empty string or a string based format. + * 24 hour uses "hh:mm", while 12 hour uses "hh:mma" + */ + onChange?: ((value: TimeRangePickerValue) => void) | undefined; + /** + * Called when a defocus is made on the field + */ onBlur?: (() => void) | undefined; } diff --git a/src/timepicker/timepicker.tsx b/src/timepicker/timepicker.tsx index 41c25f29d..77be18ab9 100644 --- a/src/timepicker/timepicker.tsx +++ b/src/timepicker/timepicker.tsx @@ -11,7 +11,6 @@ export const Timepicker = ({ readOnly = false, error, value, - defaultValue, placeholder, format = "24hr", onChange, @@ -105,10 +104,9 @@ export const Timepicker = ({ void) | undefined; + /** + * Called when a defocus is made on the field + */ onBlur?: (() => void) | undefined; + /** + * Called when the "Cancel" button is clicked + */ onSelectionCancel?: (() => void) | undefined; } diff --git a/stories/form/form-time-range-picker/form-time-range-picker.stories.mdx b/stories/form/form-time-range-picker/form-time-range-picker.stories.mdx index 48d457911..80cae2f0c 100644 --- a/stories/form/form-time-range-picker/form-time-range-picker.stories.mdx +++ b/stories/form/form-time-range-picker/form-time-range-picker.stories.mdx @@ -28,16 +28,16 @@ import { Form } from "@lifesg/react-design-system/form"; {() => { const [time1, setTime1] = useState({ - startTime: "", - endTime: "", + start: "", + end: "", }); const [time2, setTime2] = useState({ - startTime: "", - endTime: "", + start: "", + end: "", }); const [time3] = useState({ - startTime: "12:00am", - endTime: "12:30am", + start: "12:00am", + end: "12:30am", }); return ( @@ -69,6 +69,31 @@ import { Form } from "@lifesg/react-design-system/form"; +12 hour format + + + + {() => { + const [time, setTime] = useState({ + start: "12:00am", + end: "", + }); + return ( + + + setTime(value)} + /> + + + ); + }} + + + Using the field as a standalone In the case that you require the timepicker field as a standalone, you can do this. diff --git a/stories/form/form-time-range-picker/props-table.tsx b/stories/form/form-time-range-picker/props-table.tsx index 178dd7cce..ccce0bba3 100644 --- a/stories/form/form-time-range-picker/props-table.tsx +++ b/stories/form/form-time-range-picker/props-table.tsx @@ -9,20 +9,14 @@ const DATA: ApiTableSectionProps[] = [ attributes: [ { name: "value", - description: ( - <> - The value of the time in string based format. 24 hour - will be hh:mm, while 12 hour will be{" "} - hh:mma - - ), - propTypes: ["string"], + description: "The time range values in the format specified", + propTypes: ["TimeRangePickerValue"], }, { name: "format", description: "The time input format", - propTypes: [`"12hr"`], - defaultValue: `"12hr"`, + propTypes: [`"12hr"`, `"24hr"`], + defaultValue: `"24hr"`, }, { name: "disabled", @@ -69,30 +63,39 @@ const DATA: ApiTableSectionProps[] = [ { name: "onChange", description: - "Called when the user clicks on the 'Done' button in the time selection box. Returns the time value in the format specified", - propTypes: ["(value: TimeRangeInputValue) => void"], + "Called when the user clicks on the 'Done' button in the time selection box. Returns the time range values in the format specified", + propTypes: ["(value: TimeRangePickerValue) => void"], }, { name: "onBlur", - description: - "Called when a defocus happens. Any changes in the time selection box will not be applied", + description: "Called when a defocus happens", propTypes: ["() => void"], }, ], }, { - name: "TimeRangeInputValue", + name: "TimeRangePickerValue", attributes: [ { - name: "startTime", - description: - "The selected start time value in the format specified", + name: "start", + description: ( + <> + The selected start time value as an empty string or a + string-based format. 24 hour uses hh:mm, + while 12 hour uses hh:mma + + ), propTypes: ["string"], }, { - name: "endTime", - description: - "The selected end time value in the format specified", + name: "end", + description: ( + <> + The selected start time value as an empty string or a + string-based format. 24 hour uses hh:mm, + while 12 hour uses hh:mma + + ), propTypes: ["string"], }, ], diff --git a/stories/form/form-timepicker/props-table.tsx b/stories/form/form-timepicker/props-table.tsx index b8d6b283c..f36051bc1 100644 --- a/stories/form/form-timepicker/props-table.tsx +++ b/stories/form/form-timepicker/props-table.tsx @@ -18,17 +18,6 @@ const DATA: ApiTableSectionProps[] = [ ), propTypes: ["string"], }, - { - name: "defaultValue", - description: ( - <> - The default value of the time in string based format. 24 - hour will be hh:mm, while 12 hour will be{" "} - hh:mma - - ), - propTypes: ["string"], - }, { name: "placeholder", description: ( @@ -71,21 +60,11 @@ const DATA: ApiTableSectionProps[] = [ description: "The unique identifier of the component", propTypes: ["string"], }, - { - name: "name", - description: "The name of the component", - propTypes: ["string"], - }, { name: "style", description: "Allows for inline styling of the component", propTypes: ["React.CSSProperties"], }, - { - name: "tabIndex", - description: "Specifies the tab order of the component", - propTypes: ["number"], - }, { name: "data-testid", description: "The test identifier of the component",