From 157b97950d0f0a36c853ecf76d9a69a3cb058dec Mon Sep 17 00:00:00 2001 From: Benson Cho <100653148+bcho892@users.noreply.github.com> Date: Sat, 27 Jul 2024 21:14:20 +1200 Subject: [PATCH] add docs (#690) --- .../AlertsComponent/AlertsComponent.tsx | 10 +++++ .../components/generic/Checkbox/Checkbox.tsx | 3 ++ .../generic/ContactDetail/ContactDetail.tsx | 15 +++++++ .../components/generic/Dropdown/Dropdown.tsx | 10 +++++ .../ExcitmentSlider/ExcitementSlider.tsx | 11 +++++ .../components/generic/MenuList/MenuList.tsx | 11 +++++ .../components/generic/MenuTab/MenuTab.tsx | 5 +++ .../PasswordSetupForm/PasswordSetupForm.tsx | 41 ++++++++++++++++++- .../generic/PricingBanner/PricingBanner.tsx | 9 ++++ .../generic/PricingCard/PricingCard.tsx | 14 +++++++ .../ProfileInformationPanel.tsx | 15 ++++++- .../generic/SignUpNotif/SignUpNotif.tsx | 6 +++ .../generic/StepperButtons/StepperButton.tsx | 7 ++++ .../StepperComponent/StepperComponent.tsx | 18 ++++++++ .../generic/TextInputComponent/TextInput.tsx | 5 +++ 15 files changed, 177 insertions(+), 3 deletions(-) diff --git a/client/src/components/generic/AlertsComponent/AlertsComponent.tsx b/client/src/components/generic/AlertsComponent/AlertsComponent.tsx index 65d395b67..b5b17da9e 100644 --- a/client/src/components/generic/AlertsComponent/AlertsComponent.tsx +++ b/client/src/components/generic/AlertsComponent/AlertsComponent.tsx @@ -7,8 +7,18 @@ import WarningIcon from "@/assets/icons/warning.svg" import XIcon from "@/assets/icons/x.svg" type AlertsInputProp = { + /** + * What should be displayed to the user inside the alert + */ message: string + /** + * Controls what the styling of the alert will be + */ variant?: "success" | "notification" | "error" + /** + * If there should be an embedded button into the alert to allow + * for the user to close it + */ isButton?: boolean } diff --git a/client/src/components/generic/Checkbox/Checkbox.tsx b/client/src/components/generic/Checkbox/Checkbox.tsx index d46a5bbca..55c13f54b 100644 --- a/client/src/components/generic/Checkbox/Checkbox.tsx +++ b/client/src/components/generic/Checkbox/Checkbox.tsx @@ -1,4 +1,7 @@ interface ICheckboxProps { + /** + * The text that appears for the checkbox + */ label: string } diff --git a/client/src/components/generic/ContactDetail/ContactDetail.tsx b/client/src/components/generic/ContactDetail/ContactDetail.tsx index 54720a96e..3b50d9424 100644 --- a/client/src/components/generic/ContactDetail/ContactDetail.tsx +++ b/client/src/components/generic/ContactDetail/ContactDetail.tsx @@ -1,6 +1,21 @@ export interface IContactDetail { + /** + * The main description of the contact + * + * @example "Admin" + */ title: string + /** + * The extended description of the contact + * + * @example "For all payment issues and queries" + */ description?: string + /** + * The email that is associated with the contact + * + * @example "mail@mail.com" + */ email?: string } diff --git a/client/src/components/generic/Dropdown/Dropdown.tsx b/client/src/components/generic/Dropdown/Dropdown.tsx index f28e3e21c..9c54b5076 100644 --- a/client/src/components/generic/Dropdown/Dropdown.tsx +++ b/client/src/components/generic/Dropdown/Dropdown.tsx @@ -1,7 +1,17 @@ import React from "react" type DropdownProps = React.SelectHTMLAttributes & { + /** + * The main text that appears above the dropdown + * + * @example "Favourite sport" + */ label?: string + /** + * The subheading of the textbox, i.e if the label was "Favourite sport": + * + * @example "Only include ones you have played in the last year" + */ description?: string } diff --git a/client/src/components/generic/ExcitmentSlider/ExcitementSlider.tsx b/client/src/components/generic/ExcitmentSlider/ExcitementSlider.tsx index 718788f6d..0fdb12687 100644 --- a/client/src/components/generic/ExcitmentSlider/ExcitementSlider.tsx +++ b/client/src/components/generic/ExcitmentSlider/ExcitementSlider.tsx @@ -3,7 +3,18 @@ import React, { useState } from "react" interface ExcitementSliderProps { + /** + * The lowest value the slider should go to + * + * @example -69 + */ min: number + + /** + * The lowest value the slider should go to + * + * @example 69 + */ max: number } diff --git a/client/src/components/generic/MenuList/MenuList.tsx b/client/src/components/generic/MenuList/MenuList.tsx index 278756ef4..23f164645 100644 --- a/client/src/components/generic/MenuList/MenuList.tsx +++ b/client/src/components/generic/MenuList/MenuList.tsx @@ -1,6 +1,17 @@ import { ReactNode } from "react" interface IMenuListProps { + /** + * Which side the children should start, + * + * e.g for `left`: + * + * /-start here--------------/ + * + * e.g for `right`: + * + * /------------start here--/ + */ anchor?: "left" | "right" children?: ReactNode } diff --git a/client/src/components/generic/MenuTab/MenuTab.tsx b/client/src/components/generic/MenuTab/MenuTab.tsx index 6f10a61de..a422d6bd0 100644 --- a/client/src/components/generic/MenuTab/MenuTab.tsx +++ b/client/src/components/generic/MenuTab/MenuTab.tsx @@ -3,6 +3,11 @@ import DownArrow from "@/assets/icons/downarrow.svg" import MenuList from "../MenuList/MenuList" interface IMenuTabProps { + /** + * What should be shown for the text on the tab + * + * @example "Home" + */ displayText: string } type props = IMenuTabProps & React.ButtonHTMLAttributes diff --git a/client/src/components/generic/PasswordSetupForm/PasswordSetupForm.tsx b/client/src/components/generic/PasswordSetupForm/PasswordSetupForm.tsx index fa25d1c72..034e883ac 100644 --- a/client/src/components/generic/PasswordSetupForm/PasswordSetupForm.tsx +++ b/client/src/components/generic/PasswordSetupForm/PasswordSetupForm.tsx @@ -5,27 +5,66 @@ import AlertsComponent from "../AlertsComponent/AlertsComponent" import { FormEvent, useState } from "react" export type HandlerResponse = { + /** + * If the setup worked + */ success: boolean + /** + * *Custom* message to display to the user on successful signup + */ successMessage?: string error?: { + /** + * The reason for the sign up failing + */ message: string } } type MessageTypes = { + /** + * Message to display on successful signup + */ success?: string + /** + * Message to display on failed signup + */ error?: string + /** + * Misc messages + */ other?: string } type FormState = { + /** + * The password that the user enters (wants to change their password to) + */ firstPassword: string + + /** + * The *confirm* password that the user enters, which should be checked + * against `firstPassword` + */ secondPassword: string } interface IPasswordSetupForm { - passwordSetUpHandler?: (firstPassword: string) => Promise + /** + * Called when the user requests a password change. Should return a + * promise with the results of the attempted password change + * + * @param password the *confirmed* password that the user wants to use + * as the new password + */ + passwordSetUpHandler?: (password: string) => Promise + /** + * A react `ref` + */ formRef?: React.RefObject + /** + * Callback to use if the password setup was successful + */ successHandler?: () => void } diff --git a/client/src/components/generic/PricingBanner/PricingBanner.tsx b/client/src/components/generic/PricingBanner/PricingBanner.tsx index be9a83d23..9984328be 100644 --- a/client/src/components/generic/PricingBanner/PricingBanner.tsx +++ b/client/src/components/generic/PricingBanner/PricingBanner.tsx @@ -1,6 +1,15 @@ export interface IPricingBanner { + /** + * @example "Great nightly rates" + */ headline: string + /** + * @example "$40 per night" + */ priceInformation: string + /** + * @example "*$60 for a single saturday" + */ disclaimer?: string } const PricingBanner = ({ diff --git a/client/src/components/generic/PricingCard/PricingCard.tsx b/client/src/components/generic/PricingCard/PricingCard.tsx index 5d74dac13..280701dc1 100644 --- a/client/src/components/generic/PricingCard/PricingCard.tsx +++ b/client/src/components/generic/PricingCard/PricingCard.tsx @@ -1,9 +1,23 @@ import tick from "@/assets/selectedtick.png" import Image from "next/image" interface IPricingCardDefault { + /** + * @example "UoA Member" + */ title: string + /** + * The **pre-formatted** string indicating the price of the item + * + * @example "$60" + */ priceString: string + /** + * @example "was $60 before!" + */ extraInfo?: string + /** + * If the card has been clicked on + */ selected?: boolean onClick?: () => void } diff --git a/client/src/components/generic/ProfileInformationPanel/ProfileInformationPanel.tsx b/client/src/components/generic/ProfileInformationPanel/ProfileInformationPanel.tsx index 81064225a..510b9d107 100644 --- a/client/src/components/generic/ProfileInformationPanel/ProfileInformationPanel.tsx +++ b/client/src/components/generic/ProfileInformationPanel/ProfileInformationPanel.tsx @@ -1,9 +1,20 @@ import { ReactNode } from "react" import EditIcon from "@/assets/icons/edit.svg" interface IProfileInformationPanel { - title: string // The title field + /** + * The main heading of the panel + */ + title: string children?: ReactNode - onEdit?: () => void // The edit button + /** + * Handler to be called when the user requests an edit for their profile + * + * @example + * () => { + * openEditPanel() + * } + */ + onEdit?: () => void } const ProfileInformationPanel = ({ diff --git a/client/src/components/generic/SignUpNotif/SignUpNotif.tsx b/client/src/components/generic/SignUpNotif/SignUpNotif.tsx index c5fcdcd72..330ac4b45 100644 --- a/client/src/components/generic/SignUpNotif/SignUpNotif.tsx +++ b/client/src/components/generic/SignUpNotif/SignUpNotif.tsx @@ -2,9 +2,15 @@ import { useRouter } from "next/navigation" import Button from "../FigmaButtons/FigmaButton" interface ISignUpNotif { + /** + * If there is a currently signed in user which determines the view to be shown + */ signedIn?: boolean } +/** + * For use in the bookings page when a non-signed in/guest member tries to view + */ export const SignUpNotif = ({ signedIn }: ISignUpNotif) => { const router = useRouter() function goToRegister() { diff --git a/client/src/components/generic/StepperButtons/StepperButton.tsx b/client/src/components/generic/StepperButtons/StepperButton.tsx index c27280ee0..cf6f9af1c 100644 --- a/client/src/components/generic/StepperButtons/StepperButton.tsx +++ b/client/src/components/generic/StepperButtons/StepperButton.tsx @@ -1,6 +1,10 @@ type buttonVariants = "normal" | "first" interface IStepperButtonProps { children?: React.ReactNode + /** + * `normal` or `first`. The `first` is special as it does not have the + * pointed edges. + */ variant?: buttonVariants } @@ -32,6 +36,9 @@ const First = ({ ) } +/** + * Used for displaying the navigation status of a paginated form + */ const StepperButton = ({ children, variant, diff --git a/client/src/components/generic/StepperComponent/StepperComponent.tsx b/client/src/components/generic/StepperComponent/StepperComponent.tsx index 6f0b5ab9c..d253a6d73 100644 --- a/client/src/components/generic/StepperComponent/StepperComponent.tsx +++ b/client/src/components/generic/StepperComponent/StepperComponent.tsx @@ -1,13 +1,31 @@ import StepperButton from "../StepperButtons/StepperButton" export type StepProps = { + /** + * The display name of the step + * + * @example "Confirm" + */ name: string + /** + * The current value from a set of `enum`s that determines which step should + * be highlighted on the stepper + */ index: number + /** + * Handler for if a button is clicked + */ onClick?: () => void } interface IStepperProps { + /** + * An `enum` value that defines what step should be active + */ currentStep: number + /** + * @example steps={["Details", "Confirmation"]} + */ steps: StepProps[] } diff --git a/client/src/components/generic/TextInputComponent/TextInput.tsx b/client/src/components/generic/TextInputComponent/TextInput.tsx index 5f72b584d..ea3958212 100644 --- a/client/src/components/generic/TextInputComponent/TextInput.tsx +++ b/client/src/components/generic/TextInputComponent/TextInput.tsx @@ -2,6 +2,11 @@ import React from "react" type TextInputProps = React.InputHTMLAttributes & { variant?: "success" | "error" + /** + * The description of the text box + * + * @example "First Name" + */ label?: string description?: string }