diff --git a/README.md b/README.md index 68b5003d..951e2650 100644 --- a/README.md +++ b/README.md @@ -143,11 +143,10 @@ This readme file is used mostly to document project dependencies and conventions ## ๐Ÿ“ Commit conventions - ๐Ÿš€ F: major feature implementation -- ๐Ÿ’„ D: UI design - ๐Ÿ”ฅ B: bug fix - ๐Ÿš‘ M: Minor fixes - ๐Ÿ”ง R: refactoring and code improvement -- ๐Ÿ“ I: documentation +- ๐Ÿ“ D: documentation ## ๐Ÿ–ฅ๏ธ Local build (Windows 10+) diff --git a/rsconcept/frontend/src/components/props.d.ts b/rsconcept/frontend/src/components/props.d.ts index 3d8ff80a..1b3dbca7 100644 --- a/rsconcept/frontend/src/components/props.d.ts +++ b/rsconcept/frontend/src/components/props.d.ts @@ -2,47 +2,112 @@ import { HTMLMotionProps } from 'framer-motion'; export namespace CProps { - export interface Titled { - title?: string; - titleHtml?: string; - hideTitle?: boolean; - } - - export type Control = Titled & { - disabled?: boolean; - noBorder?: boolean; - noOutline?: boolean; - }; - + /** + * Represents an object that can have inline styles and CSS class names for styling. + */ export interface Styling { + /** Optional inline styles for the component. */ style?: React.CSSProperties; + + /** Optional CSS class name(s) for the component. */ className?: string; } - export type Editor = Control & { - label?: string; - }; - + /** + * Represents an object that can have a color or set of colors. + */ export interface Colors { + /** Optional color or set of colors applied via classNames. */ colors?: string; } + /** + * Represents an object that can have a title with optional HTML rendering and a flag to hide the title. + */ + export interface Titled { + /** Tooltip: `plain text`. */ + title?: string; + + /** Tooltip: `HTML formatted`. */ + titleHtml?: string; + + /** Indicates whether the `title` should be hidden. */ + hideTitle?: boolean; + } + + /** + * Represents `control` component with optional title and configuration options. + * + * @remarks + * This type extends the {@link Titled} interface, adding properties to control the visual and interactive behavior of a component. + */ + export type Control = Titled & { + /** Indicates whether the control is disabled. */ + disabled?: boolean; + + /** Indicates whether the control should render without a border. */ + noBorder?: boolean; + + /** Indicates whether the control should render without an outline. */ + noOutline?: boolean; + }; + + /** + * Represents `editor` component that includes a label, control features, and optional title properties. + * + * @remarks + * This type extends the {@link Control} type, inheriting title-related properties and additional configuration options, while also adding an optional label. + */ + export type Editor = Control & { + /** Text label. */ + label?: string; + }; + + /** + * Represents `div` component with all standard HTML attributes and React-specific properties. + */ export type Div = React.DetailedHTMLProps, HTMLDivElement>; + + /** + * Represents `button` component with optional title and HTML attributes. + */ export type Button = Titled & Omit< React.DetailedHTMLProps, HTMLButtonElement>, 'children' | 'type' >; + + /** + * Represents `label` component with HTML attributes. + */ export type Label = Omit< React.DetailedHTMLProps, HTMLLabelElement>, 'children' >; + + /** + * Represents `textarea` component with optional title and HTML attributes. + */ export type TextArea = Titled & React.DetailedHTMLProps, HTMLTextAreaElement>; + + /** + * Represents `input` component with optional title and HTML attributes. + */ export type Input = Titled & React.DetailedHTMLProps, HTMLInputElement>; + /** + * Represents `button` component with optional title and animation properties. + */ export type AnimatedButton = Titled & Omit, 'type'>; + + /** + * Represents `div` component with animation properties. + */ export type AnimatedDiv = HTMLMotionProps<'div'>; + /** + * Represents `mouse event` in React. + */ export type EventMouse = React.MouseEvent; } diff --git a/rsconcept/frontend/src/components/ui/Button.tsx b/rsconcept/frontend/src/components/ui/Button.tsx index 1798292c..15d54704 100644 --- a/rsconcept/frontend/src/components/ui/Button.tsx +++ b/rsconcept/frontend/src/components/ui/Button.tsx @@ -5,16 +5,25 @@ import { globals } from '@/utils/constants'; import { CProps } from '../props'; interface ButtonProps extends CProps.Control, CProps.Colors, CProps.Button { - text?: string; + /** Icon to display first. */ icon?: React.ReactNode; + /** Text to display second. */ + text?: string; + + /** Indicates whether to render the button in a dense style. */ dense?: boolean; + + /** Indicates loading state to prevent interactions and change visual style. */ loading?: boolean; } +/** + * Button component that provides a customizable `button` with text, icon, tooltips and various styles. + */ function Button({ - text, icon, + text, title, titleHtml, hideTitle, diff --git a/rsconcept/frontend/src/components/ui/Checkbox.tsx b/rsconcept/frontend/src/components/ui/Checkbox.tsx index e61f8034..ff4b956c 100644 --- a/rsconcept/frontend/src/components/ui/Checkbox.tsx +++ b/rsconcept/frontend/src/components/ui/Checkbox.tsx @@ -7,13 +7,22 @@ import { CheckboxChecked } from '../Icons'; import { CProps } from '../props'; export interface CheckboxProps extends Omit { + /** Label to display next to the checkbox. */ label?: string; + + /** Indicates whether the checkbox is disabled. */ disabled?: boolean; + /** Current value - `true` or `false`. */ value: boolean; + + /** Callback to set the `value`. */ setValue?: (newValue: boolean) => void; } +/** + * Checkbox component that allows users to toggle a boolean value. + */ function Checkbox({ disabled, label, diff --git a/rsconcept/frontend/src/components/ui/CheckboxTristate.tsx b/rsconcept/frontend/src/components/ui/CheckboxTristate.tsx index 46ed3500..6c99f311 100644 --- a/rsconcept/frontend/src/components/ui/CheckboxTristate.tsx +++ b/rsconcept/frontend/src/components/ui/CheckboxTristate.tsx @@ -8,10 +8,16 @@ import { CProps } from '../props'; import { CheckboxProps } from './Checkbox'; export interface CheckboxTristateProps extends Omit { + /** Current value - `null`, `true` or `false`. */ value: boolean | null; + + /** Callback to set the `value`. */ setValue?: (newValue: boolean | null) => void; } +/** + * CheckboxTristate component that allows toggling among three states: `true`, `false`, and `null`. + */ function CheckboxTristate({ disabled, label, diff --git a/rsconcept/frontend/src/components/ui/Divider.tsx b/rsconcept/frontend/src/components/ui/Divider.tsx index 1030cb9e..e8527418 100644 --- a/rsconcept/frontend/src/components/ui/Divider.tsx +++ b/rsconcept/frontend/src/components/ui/Divider.tsx @@ -2,11 +2,17 @@ import clsx from 'clsx'; import { CProps } from '@/components/props'; -interface DividerProps extends CProps.Styling { +export interface DividerProps extends CProps.Styling { + /** Indicates whether the divider is vertical. */ vertical?: boolean; + + /** Margins to apply to the divider `classNames`. */ margins?: string; } +/** + * Divider component that renders a horizontal or vertical divider with customizable margins and styling. + */ function Divider({ vertical, margins = 'mx-2', className, ...restProps }: DividerProps) { return (
diff --git a/rsconcept/frontend/src/components/ui/DropdownButton.tsx b/rsconcept/frontend/src/components/ui/DropdownButton.tsx index 254d9fbb..d8cf0d6b 100644 --- a/rsconcept/frontend/src/components/ui/DropdownButton.tsx +++ b/rsconcept/frontend/src/components/ui/DropdownButton.tsx @@ -7,15 +7,23 @@ import { globals } from '@/utils/constants'; import { CProps } from '../props'; interface DropdownButtonProps extends CProps.AnimatedButton { - text?: string; + /** Icon to display first (not used if children are provided). */ icon?: React.ReactNode; + /** Text to display second (not used if children are provided). */ + text?: string; + + /** Custom children to display. */ children?: React.ReactNode; } +/** + * DropdownButton animated component that renders a `button` with optional text, icon, and click functionality. + * It supports optional children for custom content or the default text/icon display. + */ function DropdownButton({ - text, icon, + text, className, title, titleHtml, diff --git a/rsconcept/frontend/src/components/ui/DropdownCheckbox.tsx b/rsconcept/frontend/src/components/ui/DropdownCheckbox.tsx index 128e3573..e7f41219 100644 --- a/rsconcept/frontend/src/components/ui/DropdownCheckbox.tsx +++ b/rsconcept/frontend/src/components/ui/DropdownCheckbox.tsx @@ -3,21 +3,13 @@ import { motion } from 'framer-motion'; import { animateDropdownItem } from '@/styling/animations'; -import Checkbox from './Checkbox'; +import Checkbox, { CheckboxProps } from './Checkbox'; -interface DropdownCheckboxProps { - value: boolean; - label?: string; - title?: string; - disabled?: boolean; - setValue?: (newValue: boolean) => void; -} - -function DropdownCheckbox({ title, setValue, disabled, ...restProps }: DropdownCheckboxProps) { +/** DropdownCheckbox animated component that renders a {@link Checkbox} inside a {@link Dropdown} item. */ +function DropdownCheckbox({ setValue, disabled, ...restProps }: CheckboxProps) { return ( { + /** Label to display in file upload button. */ label: string; + /** Filter: file types. */ acceptType?: string; + + /** Callback to set the `value`. Value is transmitted as `event.target.files[0]`. */ onChange?: (event: React.ChangeEvent) => void; } +/** + * FileInput component for selecting a `file`, displaying the selected file name. + */ function FileInput({ id, label, acceptType, title, className, style, onChange, ...restProps }: FileInputProps) { const inputRef = useRef(null); const [fileName, setFileName] = useState(''); diff --git a/rsconcept/frontend/src/components/ui/FlexColumn.tsx b/rsconcept/frontend/src/components/ui/FlexColumn.tsx index c5782130..19d66bf2 100644 --- a/rsconcept/frontend/src/components/ui/FlexColumn.tsx +++ b/rsconcept/frontend/src/components/ui/FlexColumn.tsx @@ -2,6 +2,10 @@ import clsx from 'clsx'; import { CProps } from '../props'; +/** + * FlexColumn component that renders a `flex` column container. + * This component is useful for creating vertical layouts with flexbox. + */ function FlexColumn({ className, children, ...restProps }: CProps.Div) { return (
diff --git a/rsconcept/frontend/src/components/ui/Indicator.tsx b/rsconcept/frontend/src/components/ui/Indicator.tsx index c445f996..1e599aac 100644 --- a/rsconcept/frontend/src/components/ui/Indicator.tsx +++ b/rsconcept/frontend/src/components/ui/Indicator.tsx @@ -5,10 +5,16 @@ import { globals } from '@/utils/constants'; import { CProps } from '../props'; interface IndicatorProps extends CProps.Titled, CProps.Styling { + /** Icon to display. */ icon: React.ReactNode; + + /** Indicates whether the indicator should have no padding. */ noPadding?: boolean; } +/** + * Indicator component that displays a status `icon` with a tooltip. + */ function Indicator({ icon, title, titleHtml, hideTitle, noPadding, className, ...restProps }: IndicatorProps) { return (
) : null} - + {user ? ( ) : null} - + {user ? ( - +