diff --git a/.changeset/hip-regions-deny.md b/.changeset/hip-regions-deny.md new file mode 100644 index 0000000000..95230a5709 --- /dev/null +++ b/.changeset/hip-regions-deny.md @@ -0,0 +1,5 @@ +--- +"@cloudoperators/juno-ui-components": patch +--- + +Improve component descriptions and prop documentation in editor for better developer experience diff --git a/packages/ui-components/src/components/AppBody/AppBody.component.tsx b/packages/ui-components/src/components/AppBody/AppBody.component.tsx index c120ea2e2f..86fade750e 100644 --- a/packages/ui-components/src/components/AppBody/AppBody.component.tsx +++ b/packages/ui-components/src/components/AppBody/AppBody.component.tsx @@ -12,8 +12,16 @@ const containerStyles = ` ` /** - * Only needed if you want to build your app's scaffold manually. In most cases it is better to use the AppShell component instead. - * Body of the app. Treat this like the body tag of an html page. + * The `AppBody` component serves as the main container for the body of your application. + * It is specifically useful when you require manual setup of the app's layout, providing + * flexibility and control over the structure of the application body. For most cases, + * consider using the `AppShell` component which encompasses more features suitable for + * typical application scaffolding. + * + * @component + * @param {string} [className] Add custom class name to style the component. + * @param {React.ReactNode} [children] The content to be rendered inside the AppBody. + * @returns {React.ReactElement} A JSX element containing the app's body structure. */ export const AppBody: React.FC = ({ className = "", children, ...props }) => { return ( @@ -24,8 +32,14 @@ export const AppBody: React.FC = ({ className = "", children, ...p } export interface AppBodyProps extends React.HTMLAttributes { - /** Add custom class name */ + /** + * Add custom class name to style the component. + * @default "" + */ className?: string - /** Pass children nodes */ + + /** + * The content to be rendered inside the AppBody component. + */ children?: React.ReactNode } diff --git a/packages/ui-components/src/components/AppBody/AppBody.stories.tsx b/packages/ui-components/src/components/AppBody/AppBody.stories.tsx index 516dd1a7b5..e7db1295b6 100644 --- a/packages/ui-components/src/components/AppBody/AppBody.stories.tsx +++ b/packages/ui-components/src/components/AppBody/AppBody.stories.tsx @@ -21,13 +21,6 @@ export default meta type Story = StoryObj export const Body: Story = { - parameters: { - docs: { - description: { - story: - "Only needed if you want to build your app's scaffold manually. In most cases it is better to use the AppShell component instead. Body of the app. Treat this like the body tag of an html page.", - }, - }, - }, + parameters: {}, args: {}, } diff --git a/packages/ui-components/src/components/AppShell/AppShell.component.tsx b/packages/ui-components/src/components/AppShell/AppShell.component.tsx index 4ee2cee3e3..6a0489a882 100644 --- a/packages/ui-components/src/components/AppShell/AppShell.component.tsx +++ b/packages/ui-components/src/components/AppShell/AppShell.component.tsx @@ -13,7 +13,27 @@ import { PageFooter } from "../PageFooter/index" import { HeaderContainer } from "../HeaderContainer/index" /** - * Body of the app. Treat this like the body tag of an html page. + * The `AppShell` component provides the foundational layout structure for the application. + * It acts similarly to an HTML `body` element, organizing pages with headers, footers, + * navigation, and content areas. For simpler manual layout setup, consider using `AppBody`. + * + * @component + * @param {React.ReactNode} [children] The main content to be rendered within the shell. + * @param {string} [className] Add custom class name to style the component. + * @param {boolean} [embedded] Determines if the app should be rendered in embedded mode, + * reducing layout components to core content. Only the content area and children are rendered + * along with a TopNavigation if provided, excluding header, footer, and remaining layout components. + * @default false + * @param {React.ReactNode} [pageHeader] Pass either a `` component or a string to be used + * as the application name in the standard page header. + * @default `` + * @param {React.ReactNode} [pageFooter] If specified, a `` component; otherwise, defaults to ``. + * @default `` + * @param {React.ReactNode} [topNavigation] Optional `` component. Only rendered if provided. + * @param {React.ReactNode} [sideNavigation] Optional `` component. Only rendered if provided. + * @param {boolean} [fullWidthContent] Indicates whether the main content should span the full viewport width. + * Defaults to `false` unless embedded, allowing content to occupy full width. + * @returns {React.ReactElement} A structured shell containing various sections of the app. */ export const AppShell: React.FC = ({ children, @@ -26,9 +46,9 @@ export const AppShell: React.FC = ({ topNavigation, ...props }) => { - // Determine whether to pass set fullWidth to true in embedded mode or not: - // In embedded mode (i.e. embedded == true), fullWidthContent should default to true, unless explicitly passed as false. - // In non-embedded mode, fullWidthContent should default to false, unless explicitly set to true. + // Determine whether to set fullWidth to true in embedded mode or not: + // In embedded mode (i.e., embedded === true), fullWidthContent defaults to true unless explicitly set to false. + // In non-embedded mode, fullWidthContent defaults to false unless explicitly set to true. const fullWidthOrDefault = embedded ? fullWidthContent !== false : fullWidthContent === true return ( @@ -38,7 +58,7 @@ export const AppShell: React.FC = ({ {topNavigation && {topNavigation}} - {sideNavigation && sideNavigation} + {sideNavigation} {children} @@ -65,21 +85,48 @@ export const AppShell: React.FC = ({ } export interface AppShellProps extends React.HTMLAttributes { - /** The main content of the app. */ + /** + * The main content of the app. + */ children?: ReactNode - /** Pass either the `` component or if you don't need to add any content to the page header pass a string to be used as the app name in the standard page header. */ + + /** + * Add a custom class name to style the component. + * @default "" + */ + className?: string + + /** + * Determines if the app should be rendered in embedded mode, reducing layout components to core content. + * @default false + */ + embedded?: boolean + + /** + * Pass either a `` component or a string to be used as the application name in the standard page header. + * @default `` + */ pageHeader?: ReactNode - /** Optional. If specified pass a `` component. If undefined will use default PageFooter */ + + /** + * An optional `` component if specified. Uses the default `` if undefined. + * @default `` + */ pageFooter?: ReactNode - /** Optional. If specified expects a `` component. If undefined no top navigation is rendered. */ + + /** + * Optional `` component. Only rendered if provided. + */ topNavigation?: ReactNode - /** Optional. If specified expects a `` component. If undefined no side navigation is rendered. */ + + /** + * Optional `` component. Only rendered if provided. + */ sideNavigation?: ReactNode - /** Optional: Defaults to false. Set embedded to true if app is to be rendered embedded in another app/page. - * In this case only the content area and children are rendered, a TopNavigation if passed, but no header/footer or remaining layout components */ - embedded?: boolean - /** Whether the main page / view content can spread over the full available width of the viewport or not. Default is `false` (resulting in a width-constrained, centred content column on very wide screens) UNLESS the AppShell is rendered with embedded as true, then the main content will be full-width by default. In embedded mode, `fullWidthContent` can still be passed as `false` explicitly. */ + + /** + * Indicates whether the main content should span the full viewport width. + * Defaults to `false` unless embedded, allowing content to occupy full width. + */ fullWidthContent?: boolean - /** Add a custom class name */ - className?: string } diff --git a/packages/ui-components/src/components/AppShellProvider/AppShellProvider.component.tsx b/packages/ui-components/src/components/AppShellProvider/AppShellProvider.component.tsx index 0c4ceb2ce4..59957912d4 100644 --- a/packages/ui-components/src/components/AppShellProvider/AppShellProvider.component.tsx +++ b/packages/ui-components/src/components/AppShellProvider/AppShellProvider.component.tsx @@ -21,7 +21,23 @@ const Wrapper: React.FC = ({ children, shadowRoot, shadowRootMode } /** - * This provider acts as a wrapper for Juno apps. It renders a StyleProvider and PortalProvider + * The `AppShellProvider` component serves as a wrapper for Juno apps. It integrates both + * `StyleProvider` and `PortalProvider`, offering consistent theming and managing portals across the app. + * This provider can optionally render within a `ShadowRoot` to encapsulate styles independently. + * + * @component + * @param {boolean} [shadowRoot] Determines if the app should be encapsulated within a `ShadowRoot`. + * This is useful for isolating styles and components, especially when embedding the app. + * Defaults to `true`. + * @param {string} [shadowRootMode] Sets the mode of the `ShadowRoot`. Common values are `"open"` or `"closed"`. + * Defaults to `"open"`. + * @param {AppShellStyleWrapper} [stylesWrapper] Specifies where stylesheets are imported. + * Relevant only if `shadowRoot` is `false`. Must be `"inline"` if using a `ShadowRoot`. + * Defaults to `"inline"`. + * @param {string} [theme] Chooses between light or dark theme variants: `"theme-dark"` or `"theme-light"`. + * Uses the globally defined default theme if none specified. + * @param {React.ReactNode} [children] React nodes or a collection of nodes to be rendered within the provider. + * @returns {React.ReactElement} A JSX element wrapping provided children with style and portal management configurations. */ export const AppShellProvider: React.FC = ({ shadowRoot = true, @@ -42,17 +58,37 @@ export const AppShellProvider: React.FC = ({ export type AppShellStyleWrapper = "head" | "inline" interface WrapperProps { - /** React nodes or a collection of React nodes to be rendered as content. */ + /** + * React nodes or a collection of React nodes to be rendered as content. + */ children?: React.ReactNode - /** Whether the app is rendered inside a ShadowRoot. Only choose false if the app is meant to run as a stand-alone application. */ + + /** + * Determines whether the app is rendered inside a `ShadowRoot`. + * Only set to `false` if the app runs as a standalone application. + * @default true + */ shadowRoot?: boolean - /** Shadow root mode */ + + /** + * Specifies the mode of the `ShadowRoot`. + * @default "open" + */ shadowRootMode?: ShadowRootMode } export interface AppShellProviderProps extends WrapperProps { - /** Where app stylesheets are imported. This is only relevant if shadowRoot === false. If you use a ShadowRoot the styles must be inline. */ + /** + * Specifies where app stylesheets are imported. + * This is relevant only if `shadowRoot` is `false`. Must be `"inline"` if using a `ShadowRoot`. + * @default "inline" + */ stylesWrapper?: AppShellStyleWrapper - /** theme: theme-dark or theme-light */ + + /** + * Determines the theme of the application, choosing between `"theme-dark"` or `"theme-light"`. + * Defaults to the global default theme name. + * @default DEFAULT_THEME_NAME + */ theme?: "theme-dark" | "theme-light" } diff --git a/packages/ui-components/src/components/Badge/Badge.component.tsx b/packages/ui-components/src/components/Badge/Badge.component.tsx index 3c52fbf444..fccbf0a43a 100644 --- a/packages/ui-components/src/components/Badge/Badge.component.tsx +++ b/packages/ui-components/src/components/Badge/Badge.component.tsx @@ -31,32 +31,33 @@ export type BadgeVariantType = "default" | "info" | "success" | "warning" | "dan export interface BadgeProps extends React.HTMLAttributes { /** - * Specify an optional semantic variant that determines the appearance of a badge. + * Specify a semantic variant that determines the appearance of the badge. + * @default "default" */ variant?: BadgeVariantType /** - * Optional. - * If true, an icon corresponding to the variant will be displayed. - * If a string is provided and it's a valid icon name, that icon will be displayed. + * Determines whether to display an icon. If set to `true`, an icon related + * to the variant will be used. If a valid string representing a known icon + * is provided, that icon will be displayed. + * @default false */ icon?: boolean | KnownIcons /** - * Pass an optional string of text to be rendered as content. - * Alternatively, content can be passed as children (see below). - * If children are provided, they will take precedence. + * The optional text content of the badge. If children are provided, they take precedence. */ text?: string /** - * Pass an optional CSS class to apply to the message. + * Additional CSS class to apply to the badge. + * @default "" */ className?: string /** - * Pass optional React nodes or a collection of React nodes to be rendered as content. - * Takes precedence over the text property. + * React nodes or a collection of React nodes to be rendered as content, taking + * precedence over the `text` property. */ children?: React.ReactNode } @@ -83,9 +84,17 @@ const isValidIcon = (icon: string): icon is KnownIcons => { } /** - * A Badge is used to visually represent properties or states of an entity. - * It supports multiple semantic versions, each with distinct styling. - * Optionally, an icon can be included to further emphasize the meaning. + * The `Badge` component visually represents properties or states of an entity. + * It supports multiple semantic variants, each with distinct styling. An optional + * icon can be included to further emphasize meaning. + * + * @component + * @param {BadgeVariantType} [variant="default"] A semantic variant for the badge style. + * @param {boolean | KnownIcons} [icon=false] When true, displays an icon related to the variant. Accepts a valid icon string. + * @param {string} [text] String content to display within the badge. Children take precedence. + * @param {string} [className] Additional class names for styling the badge. + * @param {React.ReactNode} [children] Nodes to render inside the badge, taking precedence over `text`. + * @returns {React.ReactElement} A styled badge element indicating a property or state. */ export const Badge: React.FC = ({ variant = "default", diff --git a/packages/ui-components/src/components/Box/Box.component.tsx b/packages/ui-components/src/components/Box/Box.component.tsx index 51e7f0e8d5..56cae97791 100644 --- a/packages/ui-components/src/components/Box/Box.component.tsx +++ b/packages/ui-components/src/components/Box/Box.component.tsx @@ -21,23 +21,35 @@ const boxPadding = ` export interface BoxProps extends React.HTMLAttributes { /** - * Child elements to be rendered inside the Box. + * The child elements to be rendered inside the Box. */ children?: React.ReactNode + /** - * If true, padding is removed. + * Determines whether the Box should render without padding. + * When true, padding is removed. + * @default false */ unpad?: boolean + /** - * Additional CSS styles to apply to the Box. + * Additional CSS classes to apply to the Box component. + * @default "" */ className?: string } /** - * A generic Box component with optional padding and a light border. - * Ideal for annotations, additional explanations, and remarks where a Message or InfoBox would be too visually emphasized. - * Typically used for small text but can contain any child elements, as required. + * The `Box` component is a versatile container with optional padding and a subtle border. + * It is perfect for annotations, supplementary explanations, and remarks where more visually + * pronounced components like a MessageBox or InfoBox would be excessive. + * This component typically displays small text but can contain any child elements as required. + * + * @component + * @param {React.ReactNode} [children] Content to be rendered within the Box. + * @param {boolean} [unpad=false] If true, padding is removed from the Box. + * @param {string} [className=""] Custom class names for additional styling of the Box. + * @returns {React.ReactElement} A flexible Box component with optional padding. */ export const Box: React.FC = ({ children, unpad = false, className = "", ...props }) => { const combinedClassName = `juno-box ${boxStyles} ${!unpad ? boxPadding : ""} ${className}` diff --git a/packages/ui-components/src/components/Breadcrumb/Breadcrumb.component.tsx b/packages/ui-components/src/components/Breadcrumb/Breadcrumb.component.tsx index a667284685..0c0e52e876 100644 --- a/packages/ui-components/src/components/Breadcrumb/Breadcrumb.component.tsx +++ b/packages/ui-components/src/components/Breadcrumb/Breadcrumb.component.tsx @@ -11,23 +11,29 @@ import { BreadcrumbItem, BreadcrumbItemProps } from "../BreadcrumbItem/Breadcrum export interface BreadcrumbProps extends React.HTMLAttributes { /** - * Additional CSS styles to apply to the breadcrumb for custom styling. + * Additional CSS classes for styling the breadcrumb component. + * @default "" */ className?: string + /** * Optional React nodes or a collection of React nodes to be rendered as custom content. - * The BreadcrumbItem component is typically used. + * The `BreadcrumbItem` component is typically used. */ children?: React.ReactNode } /** - * Breadcrumb is a component that structures navigational links in a breadcrumb trail. + * The `Breadcrumb` component structures navigational links in a breadcrumb trail, providing a way to display + * hierarchical navigation paths. It efficiently manages: + * - Wrapping `BreadcrumbItem` or other custom components to form breadcrumb navigation. + * - Automatic insertion of separator icons between items, enhancing visibility. + * - Filtering out invalid React elements to prevent rendering errors. * - * This component: - * - Wraps around BreadcrumbItem or other custom components to create breadcrumb navigation. - * - Automatically inserts separator icons between items. - * - Filters out invalid React elements to prevent rendering errors. + * @component + * @param {string} [className=""] Additional CSS classes for custom styling of the breadcrumb. + * @param {React.ReactNode} [children] React nodes or elements that compose the breadcrumb trail. `BreadcrumbItem` is recommended. + * @returns {React.ReactElement} A structured breadcrumb navigation component with separators. */ export const Breadcrumb: React.FC = ({ children, className = "", ...props }) => { const childrenArray = Children.toArray(children).filter(React.isValidElement) // Filter out invalid elements diff --git a/packages/ui-components/src/components/BreadcrumbItem/BreadcrumbItem.component.tsx b/packages/ui-components/src/components/BreadcrumbItem/BreadcrumbItem.component.tsx index 1c803360dc..ce43c11064 100644 --- a/packages/ui-components/src/components/BreadcrumbItem/BreadcrumbItem.component.tsx +++ b/packages/ui-components/src/components/BreadcrumbItem/BreadcrumbItem.component.tsx @@ -21,45 +21,73 @@ const breadcrumbLinkBaseStyles = ` export interface BreadcrumbItemProps extends React.HTMLAttributes { /** - * The icon type to display in the breadcrumb item. + * The type of icon to display within the breadcrumb item. */ icon?: KnownIcons + /** - * A URL the breadcrumb item points to for navigation. + * The URL that the breadcrumb item points to for navigation. + * @default "#" */ href?: string + /** - * The text to display inside the breadcrumb item. + * The text to display within the breadcrumb item. + * @default "Item" */ label?: string + /** - * The value for the aria-label attribute, used to improve accessibility. + * The value for the `aria-label` attribute, enhancing accessibility by providing a textual description. */ ariaLabel?: string + /** - * Determines if this item is the last or currently active breadcrumb. + * Specifies whether this item is the last or currently active breadcrumb. + * @default false */ active?: boolean + /** - * The click event handler for the breadcrumb item. + * The click event handler for the breadcrumb item, called when the item is clicked. */ onClick?: React.MouseEventHandler + /** - * If true, disables the breadcrumb item. + * If `true`, disables the breadcrumb item, preventing interaction. + * @default false */ disabled?: boolean + /** - * Additional CSS class names to apply to the breadcrumb item for custom styling. + * Additional CSS class names to apply for custom styling of the breadcrumb item. + * @default "" */ className?: string + /** - * Custom content to render within the breadcrumb item, replacing the default content. + * Custom content to be rendered inside the breadcrumb item, replacing default content. + * This takes precedence over other content. */ children?: React.ReactNode } /** - * BreadcrumbItem represents an individual item within a Breadcrumb component. + * The `BreadcrumbItem` component represents an individual item within a Breadcrumb component. + * It can render as either a static label or a navigable link, depending on the `active` + * and `disabled` states. It supports custom icons, labels, and click functionality. + * + * @component + * @param {KnownIcons} [icon] Type of icon to display within the breadcrumb item. + * @param {string} [href="#"] URL the breadcrumb item points to for navigation. + * @param {string} [label="Item"] Text to display inside the breadcrumb item. + * @param {string} [ariaLabel] String for the `aria-label` attribute to aid accessibility. + * @param {boolean} [active=false] Specifies if the item is the last or actively displayed breadcrumb. + * @param {React.MouseEventHandler} [onClick] Handler for click events on the breadcrumb item. + * @param {boolean} [disabled=false] If `true`, disables interaction with the breadcrumb item while rendering it visually distinct. + * @param {string} [className=""] Additional custom CSS class names for styling. + * @param {React.ReactNode} [children] Custom content to be rendered, taking precedence over standard content. + * @returns {React.ReactElement} A navigable or static breadcrumb item with optional icon and styling. */ export const BreadcrumbItem: React.FC = ({ href = "#", @@ -73,7 +101,8 @@ export const BreadcrumbItem: React.FC = ({ icon, ...props }) => { - if (children) return <>{children} + if (children) return <>{children} // Render custom content if provided + const iconElement = icon ? ( ) : null @@ -97,7 +126,7 @@ export const BreadcrumbItem: React.FC = ({ if (onClick && !disabled) onClick(event) } - // Render the breadcrumb item as a link if neither active or disabled + // Render the breadcrumb item as a link if neither active nor disabled return ( diff --git a/packages/ui-components/src/components/Button/Button.component.tsx b/packages/ui-components/src/components/Button/Button.component.tsx index b00fd3fac8..30b173d85c 100644 --- a/packages/ui-components/src/components/Button/Button.component.tsx +++ b/packages/ui-components/src/components/Button/Button.component.tsx @@ -156,7 +156,23 @@ const spinnerColorClass = (variant: ButtonVariant) => { } /** - * The basic button component. Use this for `onClick` interactions. + * The `Button` component provides an interactive element for user actions, supporting various sizes, + * styles, and states such as disabled or in-progress. + * + * @component + * @param {ButtonVariant} [variant="default"] Selects the button variant for styling purposes. + * @param {ButtonSize} [size="default"] Chooses the button size. + * @param {boolean} [disabled] Indicates if the button is disabled, preventing interaction. + * @param {string} [href] If specified, renders the button as an `` element with this URL. + * @param {string} [label] Text to display on the button. Can also be passed as children. + * @param {string} [title] Accessibility title. Defaults to the label if not specified. + * @param {KnownIcons} [icon] Name of an icon to display within the button. + * @param {string} [className=""] Additional CSS class names for styling the button. + * @param {React.MouseEventHandler} [onClick] Event handler for click events. + * @param {boolean} [progress=false] If true, a loading spinner is shown instead of the icon. + * @param {string} [progressLabel] Text to display when the button action is in progress. + * @param {React.ReactNode} [children] Content to display inside the button. + * @returns {React.ReactElement} An interactive button component with customizable styles and behaviors. */ export const Button = React.forwardRef( ( @@ -257,27 +273,67 @@ type ButtonSize = "small" | "default" export interface ButtonProps extends Omit | React.HTMLProps, "size"> { + /** + * Child elements or text to be rendered inside the button. + */ children?: React.ReactNode - /** Choose a variant for your purpose. May leave empty to get default button. */ + + /** + * Choose a variant for your button style. Defaults to "default" if unspecified. + * @default "default" + */ variant?: ButtonVariant - /** Leave empty for default size */ + + /** + * Chooses the button size. Defaults to "default" if unspecified. + * @default "default" + */ size?: ButtonSize - /** Whether the button is disabled */ + + /** + * Indicates if the button is disabled. + */ disabled?: boolean - /** Optionally specify an href. This will turn the Button into an element */ + + /** + * Optionally specify an href. This renders the Button as an `` element. + */ href?: string - /** Button label can be passed like this or as children */ + + /** + * Button label can be passed directly or as children. + */ label?: string - /** Specify title for accessibility. Gets value of label if no title specified */ + + /** + * Specify a title for accessibility purposes. Defaults to the label if not specified. + */ title?: string - /** Pass the name of an icon the button should show. Can be any icon included with Juno. */ + + /** + * Pass the name of an icon that the button should display. Can be any icon included with Juno. + */ icon?: KnownIcons - /** Pass a className */ + + /** + * Additional class names for styling. + * @default "" + */ className?: string - /** Click handler */ + + /** + * Click event handler for the button. + */ onClick?: React.MouseEventHandler - /** Whether the button action is in progress */ + + /** + * Indicates whether the button's action is in progress. + * @default false + */ progress?: boolean - /** Display an alternative label while the button action is in progress */ + + /** + * Display an alternative label while the button's action is in progress. + */ progressLabel?: string } diff --git a/packages/ui-components/src/components/ButtonRow/ButtonRow.component.tsx b/packages/ui-components/src/components/ButtonRow/ButtonRow.component.tsx index b6d6eb345b..c9231a0ca2 100644 --- a/packages/ui-components/src/components/ButtonRow/ButtonRow.component.tsx +++ b/packages/ui-components/src/components/ButtonRow/ButtonRow.component.tsx @@ -6,7 +6,19 @@ import React from "react" import { Stack } from "../Stack/Stack.component" -/** A container to hold one or multiple buttons and space and align them. */ +/** + * The `ButtonRow` component is designed to contain one or several buttons, + * providing them with structured spacing and alignment. It uses the `Stack` + * component for consistent gap management and alignment, ensuring that + * button elements are neatly organized within a row. This is particularly + * useful in dialogs, forms, or any interface requiring a uniform presentation + * for multiple actions. + * + * @component + * @param {string} [className] Additional class to apply custom styles to the `ButtonRow`. + * @param {React.ReactNode} [children] Elements to be rendered within the `ButtonRow`, typically button elements. + * @returns {React.ReactElement} A row container component for buttons, with spacing and alignment applied. + */ export const ButtonRow: React.FC = ({ children, className = "", ...props }) => { return ( @@ -14,10 +26,15 @@ export const ButtonRow: React.FC = ({ children, className = "", ) } - export interface ButtonRowProps extends React.HTMLAttributes { - /** Add a class to the ButtonRow */ + /** + * Add a class to the ButtonRow for additional styling. + * @default "" + */ className?: string - /** Children to render in the ButtonRow */ + + /** + * Children to render within the ButtonRow. + */ children?: React.ReactNode } diff --git a/packages/ui-components/src/components/Card/Card.component.tsx b/packages/ui-components/src/components/Card/Card.component.tsx index a315fb460d..e6c15bbd61 100644 --- a/packages/ui-components/src/components/Card/Card.component.tsx +++ b/packages/ui-components/src/components/Card/Card.component.tsx @@ -21,18 +21,30 @@ export interface CardProps extends React.HTMLAttributes { * Components or elements to be rendered as content. */ children?: React.ReactNode + /** - * Optional padding. + * Optional padding for the Card component. + * @default false */ padding?: boolean + /** - * Additional CSS styles. + * Additional CSS styles to apply. + * @default "" */ className?: string } /** - * A generic Card component with optional padding. + * The `Card` component acts as a versatile container for various types of content, providing + * an optional padding feature for additional layout flexibility. It is commonly used for + * displaying information or grouping elements, allowing for consistent styling and shadow effects. + * + * @component + * @param {React.ReactNode} [children] Components or elements to be rendered within the Card. + * @param {boolean} [padding=false] Determines if padding should be applied to the Card. + * @param {string} [className] Additional CSS classes for custom styling. + * @returns {React.ReactElement} A customizable Card component for content display. */ export const Card: React.FC = ({ children, padding = false, className = "", ...props }) => { const combinedClassName = `juno-card ${cardStyles} ${padding ? cardPadding : ""} ${className}` diff --git a/packages/ui-components/src/components/Checkbox/Checkbox.component.tsx b/packages/ui-components/src/components/Checkbox/Checkbox.component.tsx index d60cb0daa7..22b2725040 100644 --- a/packages/ui-components/src/components/Checkbox/Checkbox.component.tsx +++ b/packages/ui-components/src/components/Checkbox/Checkbox.component.tsx @@ -94,6 +94,32 @@ const hintStyles = ` jn:ml-6 ` +/** + * The `Checkbox` component is a versatile form element that allows users to + * select one or multiple options. It can display states such as checked, + * indeterminate, invalid, and valid, and integrates with a checkbox group context + * for collective state management. This component supports labels, icons, + * error/success indicators, and custom event handlers. + * + * @component + * @param {boolean} [checked=false] Specifies if the Checkbox is checked. + * @param {string} [className] Custom CSS classes for styling the Checkbox. + * @param {boolean} [disabled=false] Specifies if the Checkbox is disabled. + * @param {ReactNode} [errortext] Text displayed when there is an error or validation issue. + * @param {ReactNode} [helptext] Additional text to explain the purpose and importance of the Checkbox. + * @param {string} [id] The Checkbox's ID. Automatically generated if not provided. + * @param {boolean} [indeterminate=false] Specifies if the Checkbox is in an indeterminate state. + * @param {boolean} [invalid=false] Indicates if the Checkbox has failed validation. + * @param {string} [label] The label text for the Checkbox. + * @param {string} [name] The name attribute of the Checkbox. + * @param {function} [onChange] Event handler for when the Checkbox value changes. + * @param {function} [onClick] Event handler for when the Checkbox is clicked. + * @param {boolean} [required=false] Sets if the Checkbox is a required field. + * @param {ReactNode} [successtext] Text displayed when the Checkbox passes validation. + * @param {boolean} [valid=false] Indicates if the Checkbox has successfully passed validation. + * @param {string} [value] The value attribute of the Checkbox. + * @returns {React.ReactElement} A standard Checkbox component with custom behavior and styling. + */ export const Checkbox: React.FC = ({ checked = false, className = "", @@ -319,36 +345,90 @@ export const Checkbox: React.FC = ({ } export interface CheckboxProps extends React.HTMLAttributes { - /** Whether the Checkbox is checked */ + /** + * Specifies if the Checkbox is checked. + * @default false + */ checked?: boolean - /** Pass a custom className */ + + /** + * Custom CSS class for styling the Checkbox. + * @default "" + */ className?: string - /** Whether the Checkbox is disabled */ + + /** + * Specifies if the Checkbox is disabled. + * @default false + */ disabled?: boolean - /** A text to render when the Checkbox has an error or could not be validated */ + + /** + * Text to display when the Checkbox has an error. + */ errortext?: ReactNode - /** A helptext to render to explain meaning and significance of the Checkbox */ + + /** + * Help text explaining the significance of the Checkbox. + */ helptext?: ReactNode - /** The id of the Radio. An id will be automatically generated if not passed. */ + + /** + * The ID of the Checkbox. Auto-generated if not provided. + */ id?: string - /** Whether the Checkbox is indeterminate. Applicable ONLY if the Checkbox represents multiple child Checkboxes with non--identical checked state. */ + + /** + * Specifies if the Checkbox is in an indeterminate state; used for mixed states. + * @default false + */ indeterminate?: boolean - /** Whether the Checkbox was validated unsuccessfully */ + + /** + * Indicates whether the Checkbox validation failed. + * @default false + */ invalid?: boolean - /** The label of the Checkbox */ + + /** + * The label text for the Checkbox. + */ label?: string - /** The name of the Checkbox */ + + /** + * The name attribute of the Checkbox. + */ name?: string - /** handler to be executed when the Checkbox changes. */ + + /** + * Event handler for change events on the Checkbox. + */ onChange?: React.ChangeEventHandler - /** handler to be executed when the Checkbox is clicked. */ + + /** + * Event handler for click events on the Checkbox. + */ onClick?: React.MouseEventHandler - /** Whether the Checkbox is required */ + + /** + * Specifies if the Checkbox is required for form validation. + * @default false + */ required?: boolean - /** A text to render when the Checkbox was successfully validated */ + + /** + * Text to display when the Checkbox passes validation. + */ successtext?: ReactNode - /** Whether the Checkbox was successfully validated */ + + /** + * Indicates whether the Checkbox validation succeeded. + * @default false + */ valid?: boolean - /** The value of the Checkbox */ + + /** + * The value attribute of the Checkbox. + */ value?: string } diff --git a/packages/ui-components/src/components/CheckboxGroup/CheckboxGroup.component.tsx b/packages/ui-components/src/components/CheckboxGroup/CheckboxGroup.component.tsx index a039c0ef41..1cfe2609c6 100644 --- a/packages/ui-components/src/components/CheckboxGroup/CheckboxGroup.component.tsx +++ b/packages/ui-components/src/components/CheckboxGroup/CheckboxGroup.component.tsx @@ -53,6 +53,29 @@ export interface CheckboxGroupContextProps { export const CheckboxGroupContext = createContext(undefined) +/** + * The `CheckboxGroup` component provides a context-managed grouping of checkbox elements. + * It manages the collective state for checkboxes, allowing for individual or batch validation + * and selection. It supports states such as disabled, valid, and invalid, and offers customization + * for error and success messages. It also furnishes a grouped label and help text for a unified UI. + * + * @component + * @param {ReactNode} [children] The Checkbox components contained within this group. + * @param {string} [className] Custom CSS classes for styling the CheckboxGroup. + * @param {boolean} [disabled=false] Disables all checkboxes within the group. + * @param {ReactNode} [errortext] Message displayed when validation fails or an error is present. + * @param {ReactNode} [helptext] Additional text providing explanation of the group's purpose. + * @param {string} [id] The unique group ID. Generated automatically if unspecified. + * @param {boolean} [invalid=false] Whether the CheckboxGroup is currently invalidated. + * @param {string} [label] The label associated with the CheckboxGroup. + * @param {string} [name] Name attribute for the entire group. A unique identifier is generated if unspecified. + * @param {function} [onChange] Event handler for changes in selection. + * @param {boolean} [required=false] Indicates if selection is mandatory in the group. + * @param {string[]} [selected] Array of selected option values within the group. + * @param {ReactNode} [successtext] Message displayed when validation is successful. + * @param {boolean} [valid=false] Whether the CheckboxGroup has been successfully validated. + * @returns {React.ReactElement} A context-enabled CheckboxGroup component with built-in state management. + */ export const CheckboxGroup: React.FC = ({ children, className = "", @@ -183,31 +206,63 @@ export const CheckboxGroup: React.FC = ({ } export interface CheckboxGroupProps extends Omit, "onChange"> { - /** The Checkbox children of the CheckboxGroup */ + /** The Checkbox children of the CheckboxGroup. */ children?: ReactNode - /** Pass a custom className */ + + /** + * Custom class names for styling the CheckboxGroup. + * @default "" + */ className?: string - /** Whether all Checkboxes in the group are disabled */ + + /** + * Disables all checkboxes in the group. + * @default false + */ disabled?: boolean - /** Text to display in case validation failed or there is an error. Will set the whole group to invalid when passed. */ + + /** Text displayed if validation fails or there is an error. Indicates group invalidity when set. */ errortext?: ReactNode - /** A text to render to further explain meaning and significance of the group */ + + /** Additional text explaining the significance of this group. */ helptext?: ReactNode - /** The id of the group. If not passed, a unique id will be created and used for the group as a whole. */ + + /** The group's ID. Automatically generated if not provided. */ id?: string + + /** + * Indicates if the CheckboxGroup is marked as invalid. + * @default false + */ invalid?: boolean - /** The label of the whole group. */ + + /** The label text for the CheckboxGroup. */ label?: string - /** The name of all checkboxes in the group. If not passed, a unique name identifier will be created and used for the group as a whole. */ + + /** + * Name for all checkboxes in the group. Generated if not supplied. + * @default A unique identifier + */ name?: string - /** An onChange handler to execute when the selection of options changes */ + + /** Event handler triggered when any checkbox selection changes. */ onChange?: EventUpdateHandler - /** Whether a selection in the group is required */ + + /** + * Specifies if a selection is required in this group. + * @default false + */ required?: boolean - /** Array of values of individual selected options in the group */ + + /** Array of values representing the initially selected checkboxes in the group. */ selected?: string[] - /** Text to display in case validation is successful. When passed, will set the whole group to valid. */ + + /** Text displayed upon successful validation, which marks the group as valid. */ successtext?: ReactNode - /** Whether the CheckboxGroup was successfully validated */ + + /** + * Specifies if the CheckboxGroup has been successfully validated. + * @default false + */ valid?: boolean } diff --git a/packages/ui-components/src/components/Code/Code.component.tsx b/packages/ui-components/src/components/Code/Code.component.tsx index 4bb166c1f8..60948cf8ac 100644 --- a/packages/ui-components/src/components/Code/Code.component.tsx +++ b/packages/ui-components/src/components/Code/Code.component.tsx @@ -10,8 +10,15 @@ const codeStyles = ` jn:text-sm ` -/** A basic inline `` component. - * Accepts "content" prop or renders children as passed. +/** + * The `Code` component is a lightweight inline `` element used for displaying code snippets or text. + * It can accept content directly through the `content` prop or render children encapsulated within it. + * + * @component + * @param {string} [content] Text content to display within the code element. Defaults to an empty string. + * @param {React.ReactNode} [children] Elements or text to render inside the code element. + * @param {string} [className] Additional CSS classes for styling the code element. Defaults to an empty string. + * @returns {React.ReactElement} A styled inline code element. */ export const Code: React.FC = ({ content = "", children, className = "", ...props }) => { return ( @@ -22,7 +29,17 @@ export const Code: React.FC = ({ content = "", children, className = } export interface CodeProps extends React.ComponentPropsWithoutRef<"code"> { + /** + * Text content to render within the code element. Overrides `children`. + * @default "" + */ content?: string + + /** Additional CSS class names for styling the code element. + * @default "" + */ className?: string + + /** Elements or text to render inside the code element. */ children?: React.ReactNode } diff --git a/packages/ui-components/src/components/CodeBlock/CodeBlock.component.tsx b/packages/ui-components/src/components/CodeBlock/CodeBlock.component.tsx index c6697756c6..d5ba1688cb 100644 --- a/packages/ui-components/src/components/CodeBlock/CodeBlock.component.tsx +++ b/packages/ui-components/src/components/CodeBlock/CodeBlock.component.tsx @@ -105,7 +105,20 @@ const jsonTheme = { base0F: "var(--color-syntax-highlight-base0F)", // integer value } -/** A basic CodeBlock component. Accepts a content prop or children. Will render a pre-wrapped code element. */ +/** + * The `CodeBlock` component renders a block of preformatted code or content. It offers features such + * as optional wrapping, copying to clipboard, and syntax highlighting for JSON content via a custom viewer. + * + * @component + * @param {string | object} [content] The content displayed when `lang` is "json". It overrides `children` if specified. Defaults to an empty string or object. + * @param {React.ReactNode} [children] Elements or text to render inside the code block. + * @param {boolean} [wrap] Determines if the code content should wrap. The default is `true`. + * @param {CodeBlockSize} [size] Specifies the height of the code block. The default is `"auto"`. + * @param {boolean} [copy] Enables or disables the copy-to-clipboard functionality. The default is `true`. + * @param {string} [lang] Indicates the coding language. Passing "json" will render a JsonView and adds a language data attribute. + * @param {string} [className] Additional CSS classes for styling the code block. Defaults to an empty string. + * @returns {React.ReactElement} A formatted block of code with options for display and interaction. + */ export const CodeBlock: React.FC = ({ content = "", children, @@ -181,20 +194,48 @@ export const CodeBlock: React.FC = ({ type CodeBlockSize = "auto" | "small" | "medium" | "large" export interface CodeBlockProps extends Omit, "content" | "children"> { - /** The content to render. Used when `lang` is "json". Otherwise, if children are not provided. */ + /** + * The content to render. Used when `lang` is "json". Overrides children if not specified. + * Defaults to an empty string or object. + */ content?: string | object - /** The children to render. Used when `lang` is NOT "json", overriding `content`. */ + + /** + * Elements or text to render inside the code block. Used when `lang` is not "json", overriding `content`. + */ children?: React.ReactNode - /** Pass at title to render. Will look like a single tab. */ + + /** + * Optional caption or title to render, styled like a tab. + */ heading?: string - /** Set whether the code should wrap or not. Default is true. */ + + /** + * Determines whether the code should wrap. + * @default true + */ wrap?: boolean - /** Set the size of the CodeBlock. Default is "auto" */ + + /** + * Specifies the size of the CodeBlock. + * @default "auto" + */ size?: CodeBlockSize - /** Render a button to copy the code to the clipboard. Defaults to true */ + + /** + * Enables or disables the copy-to-clipboard option. + * @default true + */ copy?: boolean - /** Pass a lang prop. Passing "json" will render a fully-featured JsonView. Will also add a data-lang attribute to the codeblock */ + + /** + * Language for the content. "json" will render a structured JsonView. Adds a data-lang attribute. + */ lang?: string - /** Add a custom className to the wrapper of the CodeBlock */ + + /** + * Additional CSS classes for customizing the CodeBlock styling. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/ComboBox/ComboBox.component.tsx b/packages/ui-components/src/components/ComboBox/ComboBox.component.tsx index 20b187fab6..6e6861146d 100644 --- a/packages/ui-components/src/components/ComboBox/ComboBox.component.tsx +++ b/packages/ui-components/src/components/ComboBox/ComboBox.component.tsx @@ -156,6 +156,40 @@ type OptionValuesAndLabelsValue = { children: ReactNode } +/** + * The `ComboBox` component is a customizable, accessible, and interactive dropdown component, allowing users to select from a list of options. + * It features dynamic filtering and optional asynchronous loading for extended functionality. + * + * @component + * @param {string} [ariaLabel] ARIA label, defaults to the `label` if provided. + * @param {ReactNode} [children] Use with `ComboBox.Option` to render dropdown options. + * @param {string} [className] CSS classes applied to the combo box. Defaults to an empty string. + * @param {string} [defaultValue] Uncontrolled initial value for internal state handling. + * @param {boolean} [disabled] Specifies if the combobox is disabled. The default is `false`. + * @param {boolean} [error] Internal error indicator; differs from validation `invalid`. The default is `false`. + * @param {ReactNode} [errortext] Text displayed on validation failure or internal error. + * @param {ReactNode} [helptext] Informative text explaining the ComboBox's purposes. + * @param {string} [id] ID assigned to the Text Input, auto-generated if unspecified. + * @param {boolean} [invalid] Validation state identifying invalidities. The default is `false`. + * @param {string} [label] ComboBox label text. + * @param {boolean} [loading] Loading indicator for asynchronous data fetching. The default is `false`. + * @param {string} [name] Form attribute representing the ComboBox. + * @param {function} [onBlur] Event handler for input losing focus. + * @param {function} [onChange] Handler for changing selection. + * @param {function} [onFocus] Event handler for input focus event. + * @param {function} [onInputChange] Handler for text input alterations. + * @param {string} [placeholder] Placeholder for the input field. Defaults to `"Select…"`. + * @param {boolean} [required] Whether a value selection is required. The default is `false`. + * @param {ReactNode} [successtext] Text displayed upon successful validation. + * @param {boolean} [truncateOptions] Sets whether to truncate options when space is limited. The default is `false`. + * @param {boolean} [valid] Specifies successful validation. The default is `false`. + * @param {string} [value] Controlled mode selected value. + * @param {string} [valueLabel] Label for value or defaultValue. + * @param {ComboBoxWidth} [width] Specifies input width: "full" or "auto". The default is `"full"`. + * @param {string} [wrapperClassName] Custom class for styling the outermost wrapper. Defaults to an empty string. + * @returns {React.ReactElement} An interactive ComboBox component with advanced behaviors. + */ + export const ComboBox: React.FC = ({ ariaLabel, children, @@ -513,57 +547,112 @@ export const ComboBox: React.FC = ({ export type ComboBoxWidth = "full" | "auto" export interface ComboBoxProps extends Omit, "onChange" | "onInput" | "children"> { - /** The aria-label of the ComboBox. Defaults to the label if label was passed. */ + /** ARIA label for accessibility. Defaults to label if provided. */ ariaLabel?: string - /** The children to Render. Use `ComboBox.Option` elements. */ + + /** Children to render, typically using `ComboBox.Option`. */ children?: ReactNode - /** A custom className. Will be passed to the internal text input element of the ComboBox */ + + /** + * Additional class names for styling. + * @default "" + */ className?: string - /** Pass a defaultValue to use as an uncontrolled Component that will handle its state internally */ + + /** Default value for ComboBox, applicable in uncontrolled mode. */ defaultValue?: string - /** Whether the ComboBox is disabled */ + + /** + * Indicates if ComboBox is disabled. + * @default false + */ disabled?: boolean - /** Whether the ComboBox has an error. Note this refers to an internal error like failing to load options etc., to indicate failed validation use `invalid` instead. */ + + /** + * Indicates internal ComboBox error. Use `invalid` for validation failures. + * @default false + */ error?: boolean - /** An errortext to display when the ComboBox failed validation or an internal error occurred. */ + + /** Text displayed for validation errors or internal issues. */ errortext?: ReactNode - /** A helptext to render to explain meaning and significance of the ComboBox */ + + /** Additional context or instructions displayed below the ComboBox. */ helptext?: ReactNode - /** The Id of the ComboBox. Will be assigned to the text input part of the ComboBox. If not passed, an id will be auto-generated. */ + + /** ID for ComboBox. If unspecified, auto-generated. */ id?: string - /** Whether the ComboBox failed validation */ + + /** + * Identifies invalid ComboBox state. + * @default false + */ invalid?: boolean - /** The label of the ComboBox */ + + /** ComboBox label text. */ label?: string - /** Whether the ComboBox is busy loading options */ + + /** + * Loading state for asynchronous actions. + * @default false + */ loading?: boolean - /** The name attribute of the ComboBox when used as part of a form */ + + /** Name attribute when used within a form. */ name?: string - /** A handler to execute when the ComboBox looses focus */ + + /** Handler for when the ComboBox loses focus. */ onBlur?: React.FocusEventHandler - /** A handler to execute when the ComboBox' selected value changes */ - // eslint-disable-next-line no-unused-vars - onChange?: (value: string) => void - /** A handler to execute when the ComboBox input receives focus */ + + /** Handler for changes in the ComboBox selection. */ + onChange?: (_value: string) => void + + /** Handler for when the ComboBox input gains focus. */ onFocus?: React.FocusEventHandler - /** Handler to execute when the ComboBox text input value changes */ + + /** Handler for changes in the ComboBox's text input value. */ onInputChange?: React.ChangeEventHandler - /** A placeholder to render in the text input */ + + /** Placeholder text for ComboBox input. + * @default "Select…" + */ placeholder?: string - /** Whether the ComboBox is required */ + + /** + * Flags the ComboBox as a required field. + * @default false + */ required?: boolean - /** A text to display in case the ComboBox was successfully validated. Will set the ComboBox to `valid` when passed. */ + + /** Text shown upon successful validation of the ComboBox. */ successtext?: ReactNode - /** Whether the option labels should be truncated in case they are longer/wider than the available space in an option or not. Default is FALSE. */ + + /** + * Controls option text truncation in the dropdown. + * @default false + */ truncateOptions?: boolean - /** Whether the ComboBox was successfully validated */ + + /** + * Specifies successful validation state. + * @default false + */ valid?: boolean - /** The selected value of the ComboBox in Controlled Mode. */ + + /** Controlled value for ComboBox in managed state. */ value?: string - /** The label of the passed value or defaultValue. If you want to use controlled mode or pass as defaultValue in uncontrolled mode and additionally use labels for human-readable SelectOptions, you need to also pass the matching label for the passed value/defaultValue so that the Select component can render itself properly */ + + /** Label corresponding to the selected or default value for display. */ valueLabel?: string - /** The width of the text input. Either 'full' (default) or 'auto'. */ + + /** + * Width determination for input: "full" or "auto". + * @default "full" + */ width?: ComboBoxWidth - /** Pass a custom classname to the wrapping
element. This can be useful if you must add styling to the outermost wrapping element of this component, e.g. for positioning. */ + + /** Custom styling classes for the ComboBox's wrapper. + * @default "" + */ wrapperClassName?: string } diff --git a/packages/ui-components/src/components/ComboBoxOption/ComboBoxOption.component.tsx b/packages/ui-components/src/components/ComboBoxOption/ComboBoxOption.component.tsx index c2a8cecafe..b56e644a1b 100644 --- a/packages/ui-components/src/components/ComboBoxOption/ComboBoxOption.component.tsx +++ b/packages/ui-components/src/components/ComboBoxOption/ComboBoxOption.component.tsx @@ -49,6 +49,19 @@ const truncateOptionStyles = ` jn:whitespace-nowrap ` +/** + * `ComboBoxOption` is a component used within a `ComboBox` to represent each selectable option. + * It displays the option's label and value, and indicates the selected state with styles or an icon. + * + * @component + * @param {string} [children] Text or element to render inside the ComboBoxOption. Should be a string when specified. + * @param {boolean} [disabled] If true, the option is disabled and not selectable. Defaults to `false`. + * @param {string} [value] The value of the option, used to identify the selection. + * @param {string} [label] The label for the option, displayed if `children` is not used. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @returns {React.ReactElement} A selectable option component for use within a ComboBox. + */ + export const ComboBoxOption: React.FC = ({ children, disabled = false, @@ -100,14 +113,26 @@ export const ComboBoxOption: React.FC = ({ } export interface ComboBoxOptionProps extends React.HTMLProps { - /** Content to render inside the ComboBoxOption. Is specified should be string. */ + /** + * Content to render inside the ComboBoxOption. Should be specified as a string. + */ children?: string - /** If option is disabled. */ + + /** + * If true, the option is disabled and not selectable. + * @default false + */ disabled?: boolean - /** Option value. */ + + /** The value to be submitted if this option is selected. */ value?: string - /** Option label. */ + + /** The label text for the option, displayed when `children` is not provided. */ label?: string - /** CSS class for the option. */ + + /** + * CSS class names for custom styling. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/Container/Container.component.tsx b/packages/ui-components/src/components/Container/Container.component.tsx index 150e7a66ed..6c8bf79afd 100644 --- a/packages/ui-components/src/components/Container/Container.component.tsx +++ b/packages/ui-components/src/components/Container/Container.component.tsx @@ -13,7 +13,15 @@ const containerStyles = (px: boolean, py: boolean) => { } /** - * A very basic layout container with padding. + * The `Container` component serves as a basic layout container with configurable padding options, + * providing structure and spacing within layouts. + * + * @component + * @param {boolean} [px] Whether horizontal padding should be applied. The default is `true`. + * @param {boolean} [py] Whether vertical padding should be applied. The default is `false`. + * @param {string} [className] Additional CSS classes for styling the container. Defaults to an empty string. + * @param {React.ReactNode} [children] Content to render inside the container. + * @returns {React.ReactElement} A padded container for content layout. */ export const Container: React.FC = ({ px = true, py = false, className = "", children, ...props }) => { return ( @@ -24,11 +32,23 @@ export const Container: React.FC = ({ px = true, py = false, cla } export interface ContainerProps extends React.HTMLAttributes { - /** Choose false if you don't want horizontal padding to be added. */ + /** + * Specifies whether horizontal padding should be added. + * @default true + */ px?: boolean - /** Set to true to add vertical padding. */ + + /** + * Specifies whether vertical padding should be added. + * @default false + */ py?: boolean - /** Add custom class name */ + + /** Additional custom class names for styling the container. + * @default "" + */ className?: string + + /** Elements or components to render within the Container. */ children?: React.ReactNode } diff --git a/packages/ui-components/src/components/ContentAreaToolbar/ContentAreaToolbar.component.tsx b/packages/ui-components/src/components/ContentAreaToolbar/ContentAreaToolbar.component.tsx index 543689309e..b1c025472a 100644 --- a/packages/ui-components/src/components/ContentAreaToolbar/ContentAreaToolbar.component.tsx +++ b/packages/ui-components/src/components/ContentAreaToolbar/ContentAreaToolbar.component.tsx @@ -16,18 +16,25 @@ const baseToolbarStyles = ` export interface ContentAreaToolbarProps extends React.HTMLAttributes { /** - * Additional CSS classes for custom styling. + * Custom CSS classes for styling the toolbar. + * @default "" */ className?: string + /** - * Custom content to render within the content area toolbar. + * Content or elements to render within the content area toolbar. */ children?: React.ReactNode } /** - * ContentAreaToolbar represents the main toolbar within the content area. - * It is designed to hold main actions relevant to the current page. + * The `ContentAreaToolbar` represents the main toolbar within a content area, providing space + * for main actions relevant to the current page context. It supports custom content and styling. + * + * @component + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Custom content or actions to render within the toolbar. + * @returns {React.ReactElement} A styled toolbar component for content areas. */ export const ContentAreaToolbar: React.FC = ({ className = "", children, ...props }) => { return ( diff --git a/packages/ui-components/src/components/ContentContainer/ContentContainer.component.tsx b/packages/ui-components/src/components/ContentContainer/ContentContainer.component.tsx index b99c5a9478..f2ef1a31e7 100644 --- a/packages/ui-components/src/components/ContentContainer/ContentContainer.component.tsx +++ b/packages/ui-components/src/components/ContentContainer/ContentContainer.component.tsx @@ -16,20 +16,23 @@ const baseContainerStyles = ` export interface ContentContainerProps extends React.HTMLAttributes { /** - * Additional CSS classes for custom styling. + * Additional CSS class names for styling the content container. + * @default "" */ className?: string - /** - * Custom content to render within the container. - */ + + /** Components or elements to render inside the content container. */ children?: ReactNode } /** - * ContentContainer serves as a wrapper for app content. - * It is intended for manual app scaffold creation. In most cases, using the AppShell component instead is recommended. + * The `ContentContainer` serves as a wrapper for application content, designed for manual layout creation. + * It can center content when the browser window is wider than the max breakpoint. * - * Note: When the browser window is wider than the max breakpoint width, the content within this container will be centered on the screen. + * @component + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] The content to render within the container. + * @returns {React.ReactElement} A flexible content container for app layouts. */ export const ContentContainer: React.FC = ({ className = "", children, ...props }) => { return ( diff --git a/packages/ui-components/src/components/ContentHeading/ContentHeading.component.tsx b/packages/ui-components/src/components/ContentHeading/ContentHeading.component.tsx index eae697b2e2..df4b14d3fd 100644 --- a/packages/ui-components/src/components/ContentHeading/ContentHeading.component.tsx +++ b/packages/ui-components/src/components/ContentHeading/ContentHeading.component.tsx @@ -14,25 +14,33 @@ const baseHeadingStyles = ` export interface ContentHeadingProps extends React.HTMLAttributes { /** - * Custom content to render within the container heading. - * Takes precedence over the heading prop. + * Custom content to render within the heading. + * Takes precedence over the `heading` prop. */ children?: ReactNode + /** - * Text for the heading. Used if children is not provided. - * Children prop takes precedence. + * Text for the heading, used if `children` is not provided. + * Note that the `children` prop takes precedence over this prop. */ heading?: string + /** - * Additional CSS classes for custom styling. + * Custom CSS classes for styling the heading. + * @default "" */ className?: string } /** - * ContentHeading represents the main heading of a page or view. - * It can be used within an `` component or, if scaffolding manually, within a `` component. - * The heading text can be provided either via the `heading` prop or by passing it as `children`. + * The `ContentHeading` represents the primary heading of a page or view, usable within a `` + * or ``. The heading can be defined via the `heading` prop or the `children` prop. + * + * @component + * @param {React.ReactNode} [children] Custom content for the heading, which takes precedence over the `heading` prop. + * @param {string} [heading] The text for the heading, used if `children` is not provided. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @returns {React.ReactElement} A styled main heading component for pages or views. */ export const ContentHeading: React.FC = ({ heading = "", className = "", children, ...props }) => { return ( diff --git a/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx b/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx index 4f342edd4f..b12a072102 100644 --- a/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx +++ b/packages/ui-components/src/components/DataGrid/DataGrid.component.tsx @@ -54,11 +54,19 @@ export const useDataGridContext = () => React.useContext(DataGridContext) // TODO: allow for passing in props addItems, addItemsLabel, search, etc.: /** - * The `DataGrid` component is primarily used to display lists of items that contain substantial metadata. + * The `DataGrid` component displays tabular data with customizable columns and layout. + * It supports interactive styling through child components like `DataGridRow` for advanced interactions. * - * **For advanced features and interactions**, please refer to the [DataGridRow](?path=/docs/components-datagrid-datagridrow--docs) component, which includes: - * - **Clickable row functionality & interactive styling:** Allows for custom behavior when a row is clicked. This also enables responsive styling, such as **hover effects**, for better user experience. - * - **Selected row styling:** Provides styling to integrate active rows. + * @component + * @param {number} [columns] Number of columns in the grid layout. Defaults to `1`. + * @param {string} [columnMaxSize] Maximum size for columns, with "auto" as default. Use "1fr" for equal sizing. + * @param {string} [columnMinSize] Minimum size for columns, defaulting to `"0px"`. + * @param {number[]} [minContentColumns] Array specifying columns to size by minimum content. + * @param {string} [gridColumnTemplate] Custom CSS notation for grid columns, overriding other sizing props. + * @param {CellVerticalAlignmentType} [cellVerticalAlignment] Vertical alignment for grid cells. Default is `"center"`. + * @param {string} [className] Additional CSS classes for styling the DataGrid. Defaults to an empty string. + * @param {React.ReactNode} [children] Components or elements to render within the DataGrid. + * @returns {React.ReactElement} A flexible data grid component with extensive customization. */ export const DataGrid: React.FC = ({ columns = 1, @@ -92,23 +100,42 @@ export const DataGrid: React.FC = ({ export type CellVerticalAlignmentType = "center" | "top" export interface DataGridProps extends React.HTMLAttributes { - /** Set number of columns */ + /** + * Specifies the number of columns in the grid. + * @default 1 + */ columns?: number - /** Set column max sizing. Default: auto. For equally sized columns use "1fr" */ + + /** + * Defines maximum column sizing. + * @default "auto" + */ columnMaxSize?: string - /** Set column minimum size. Default: 0px */ + + /** + * Specifies minimum column size. + * @default "0px" + */ columnMinSize?: string - /** Specify which columns should be sized by minimum content size (i.e. as small as possible). Pass an array of column numbers (first column is 0) */ + + /** Array of indices for columns sized by minimum content. */ minContentColumns?: number[] - /** Set the grid column template in CSS grid 'grid-template-columns' notation. If this prop is passed, all other template props (columns, columnMaxSize, - * columnMinSize, minContentColumns) are ignored. The easiest case where you might need this is e.g. if you want to set specific column widths for some - * or all columns, e.g. "20% auto auto 10%" (The first column is set to 20%, the next two to auto size, the last to 10%). */ + + /** Custom CSS grid-template-columns. Overwrites other sizing props. */ gridColumnTemplate?: string - /** Set the vertical alignment for all GridCells. Default: center. PLEASE NOTE: the center alignment is achieved by using a flexbox column layout, - * which means that all child elements of the cell will be stacked vertically. To avoid this, wrap the elements in their own div */ + + /** + * Vertical alignment for all grid cells, using a flexbox column layout. + * @default "center" + */ cellVerticalAlignment?: CellVerticalAlignmentType - /** Children to render in the DataGrid */ + + /** Components or elements to render within the DataGrid container. */ children?: React.ReactNode - /** Add a class name */ + + /** + * Additional class names for styling. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/DataGridCell/DataGridCell.component.tsx b/packages/ui-components/src/components/DataGridCell/DataGridCell.component.tsx index 8a26c3d9a3..ce5416dd07 100644 --- a/packages/ui-components/src/components/DataGridCell/DataGridCell.component.tsx +++ b/packages/ui-components/src/components/DataGridCell/DataGridCell.component.tsx @@ -35,6 +35,17 @@ const cellCustomStyles = (colSpan: number | undefined) => { return styles } +/** + * `DataGridCell` is a versatile layout component for `DataGrid`, supporting cell-specific configurations + * like column span and wrapping. It adapts orientation based on grid context. + * + * @component + * @param {number} [colSpan] Defines how many columns the cell should span. + * @param {boolean} [nowrap] Prevents content wrapping within the cell. Defaults to `false`. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Content or components to render inside the DataGridCell. + * @returns {React.ReactElement} A configurable grid cell with optional spanning and wrapping. + */ export const DataGridCell = forwardRef( ({ colSpan, nowrap = false, className = "", children, ...props }, ref) => { const dataGridContext = useDataGridContext() || {} @@ -56,6 +67,25 @@ export const DataGridCell = forwardRef( DataGridCell.displayName = "DataGridCell" +export interface DataGridCellProps extends React.HTMLAttributes { + /** Defines the number of columns the cell spans. */ + colSpan?: number + + /** + * If set, content within the cell will not wrap. + * @default false + */ + nowrap?: boolean + + /** Components or elements to render within the DataGridCell. */ + children?: React.ReactNode + + /** + * Additional CSS class names for custom styling. + * @default "" + */ + className?: string +} export interface DataGridCellProps extends React.HTMLAttributes { /** Add a col span to the cell. This works like a colspan in a normal html table, so you have to take care not to place too many cells in a row if some of them have a colspan. */ colSpan?: number diff --git a/packages/ui-components/src/components/DataGridCheckboxCell/DataGridCheckboxCell.component.tsx b/packages/ui-components/src/components/DataGridCheckboxCell/DataGridCheckboxCell.component.tsx index 09ce4e934f..4f61d53cd1 100644 --- a/packages/ui-components/src/components/DataGridCheckboxCell/DataGridCheckboxCell.component.tsx +++ b/packages/ui-components/src/components/DataGridCheckboxCell/DataGridCheckboxCell.component.tsx @@ -7,6 +7,17 @@ import React from "react" import { Checkbox } from "../Checkbox/Checkbox.component" import { DataGridCell } from "../DataGridCell/DataGridCell.component" +/** + * `DataGridCheckboxCell` integrates a checkbox within a `DataGrid` cell, ideal for selection-based interactions. + * It manages the selected state and supports custom behaviors upon state changes. + * + * @component + * @param {boolean} [selected] Indicates if the cell's row is selected. Defaults to `false`. + * @param {boolean} [disabled] Disables selection if true. Defaults to `false`. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {function} [onChange] Handler to trigger when the selection state changes. + * @returns {React.ReactElement} A data grid cell with selectable state through a checkbox. + */ export const DataGridCheckboxCell: React.FC = ({ selected = false, disabled = false, @@ -22,12 +33,24 @@ export const DataGridCheckboxCell: React.FC = ({ } export interface DataGridCheckboxCellProps extends React.HTMLAttributes { - /** Whether the row this cell belongs to is selected */ + /** + * Indicates selected state of the associated row. + * @default false + */ selected?: boolean - /** Whether the item is disabled */ + + /** + * Determines if the checkbox is disabled. + * @default false + */ disabled?: boolean - /** Add a classname to the cell */ + + /** + * Additional class names for styling. + * @default "" + */ className?: string - /** Handler to change the selected state of the row */ + + /** Event handler for changes in the checkbox's state. */ onChange?: React.ChangeEventHandler } diff --git a/packages/ui-components/src/components/DataGridFoot/DataGridFoot.component.tsx b/packages/ui-components/src/components/DataGridFoot/DataGridFoot.component.tsx index 2292d77165..7bc65f0532 100644 --- a/packages/ui-components/src/components/DataGridFoot/DataGridFoot.component.tsx +++ b/packages/ui-components/src/components/DataGridFoot/DataGridFoot.component.tsx @@ -5,6 +5,15 @@ import React from "react" +/** + * `DataGridFoot` is used to display a footer section for a `DataGrid`, supporting summary data or controls + * related to the grid content. It is styled consistently with other grid sections. + * + * @component + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Content or elements to render within the footer. + * @returns {React.ReactElement} A footer section for use in data grids with custom content. + */ export const DataGridFoot: React.FC = ({ className = "", children, ...props }) => { return ( @@ -14,8 +23,14 @@ export const DataGridFoot: React.FC = ({ className = "", chil } export interface DataGridFootProps extends React.HTMLAttributes { - /** Children to render in the DataGridFoot */ + /** + * Elements or components to render within the DataGridFoot. + */ children?: React.ReactNode - /** Add a classname */ + + /** + * Custom CSS class names for styling. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.component.tsx b/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.component.tsx index da0c6ff248..c6baa7d045 100644 --- a/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.component.tsx +++ b/packages/ui-components/src/components/DataGridHeadCell/DataGridHeadCell.component.tsx @@ -13,6 +13,17 @@ const headCellBaseStyles = ` jn:border-theme-background-lvl-0 ` +/** + * `DataGridHeadCell` is designed for use within a `DataGrid` header, defining column attributes and appearance. + * It accommodates configurations like sorting (future implementation) and display styles. + * + * @component + * @param {number} [colSpan] Specifies the column span for the header cell. + * @param {boolean} [nowrap] Determines if content within the header cell should wrap. Defaults to `false`. + * @param {string} [className] Additional CSS classes for styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Header content to render within the cell. + * @returns {React.ReactElement} A styled header cell for data grids with options for configuration. + */ export const DataGridHeadCell = forwardRef( ( { diff --git a/packages/ui-components/src/components/DataGridRow/DataGridRow.component.tsx b/packages/ui-components/src/components/DataGridRow/DataGridRow.component.tsx index 354798c244..e9139be7ee 100644 --- a/packages/ui-components/src/components/DataGridRow/DataGridRow.component.tsx +++ b/packages/ui-components/src/components/DataGridRow/DataGridRow.component.tsx @@ -6,6 +6,17 @@ import React, { forwardRef } from "react" import "./data-grid-row.css" +/** + * `DataGridRow` represents a row in a `DataGrid`, supporting interactions such as selection and click handling. + * It provides styles for active states and custom behavior when interacted with. + * + * @component + * @param {boolean} [isSelected] Specifies if the row should appear selected. Defaults to `false`. + * @param {function} [onClick] Row click handler to execute custom actions. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Elements or components to render within the row. + * @returns {React.ReactElement} An interactive grid row component with selectable and clickable features. + */ export const DataGridRow = forwardRef( ({ isSelected = false, onClick, className = "", children, ...props }, ref) => { const handleClick = (event: React.MouseEvent) => { diff --git a/packages/ui-components/src/components/DataGridToolbar/DataGridToolbar.component.tsx b/packages/ui-components/src/components/DataGridToolbar/DataGridToolbar.component.tsx index 4eb0957f52..99c56fd779 100644 --- a/packages/ui-components/src/components/DataGridToolbar/DataGridToolbar.component.tsx +++ b/packages/ui-components/src/components/DataGridToolbar/DataGridToolbar.component.tsx @@ -18,7 +18,16 @@ const childrenWrapperStyles = ` jn:ml-auto ` -/** This is the toolbar for use with a DataGrid. This is the place where you would put buttons and other controls that affect the items in the DataGrid (e.g. triggering batch actions). Optionally a search input can be added. */ +/** + * `DataGridToolbar` provides an action bar for a `DataGrid`, designed to hold controls like buttons and search inputs + * for performing group operations and interfacing with the grid content. + * + * @component + * @param {React.ReactElement} [search] Optional search input component for filtering grid content. + * @param {React.ReactNode} [children] Controls or elements to render within the toolbar. + * @param {string} [className] Additional CSS classes for styling. Defaults to an empty string. + * @returns {React.ReactElement} A toolbar component for data grids with customizable actions. + */ export const DataGridToolbar: React.FC = ({ search, className = "", children, ...props }) => { return (
@@ -29,10 +38,19 @@ export const DataGridToolbar: React.FC = ({ search, classN } export interface DataGridToolbarProps extends React.HTMLAttributes { - /** Pass an optional SearchInput component */ + /** + * An optional `SearchInput` component for inclusion in the toolbar. + */ search?: React.ReactElement - /** Children to render in the DataGridToolbar */ + + /** + * Elements or components to render within the DataGridToolbar. + */ children?: React.ReactNode - /** Add a classname */ + + /** + * Custom CSS class names for styling the toolbar. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/DateTimePicker/DateTimePicker.component.tsx b/packages/ui-components/src/components/DateTimePicker/DateTimePicker.component.tsx index 6ef33deaeb..2281c512c3 100644 --- a/packages/ui-components/src/components/DateTimePicker/DateTimePicker.component.tsx +++ b/packages/ui-components/src/components/DateTimePicker/DateTimePicker.component.tsx @@ -86,8 +86,61 @@ interface SelectedDate { selectedDateStr?: string } -/** A all-purpose date and time picker component. Highly configurable, based on Flatpickr. */ - +/** + * `DateTimePicker` is a versatile and highly configurable component for date and time selection, + * powered by Flatpickr. It supports options like direct input, localization, and validation states. + * + * @component + * @param {boolean} [allowInput] Determines if user input is permitted directly. Defaults to `false`. + * @param {boolean} [allowInvalidPreload] Allows preloading invalid dates for display, clearing if disabled. + * @param {string} [ariaDateFormat] ARIA label format for days in the calendar, conforming to dateFormat tokens. + * @param {string} [className] Additional CSS classes for the input element. + * @param {string} [conjunction] Delimiter for multiple dates. Defaults to `", "`. + * @param {string} [dateFormat] Characters customizing date input format, based on Flatpickr specifications. + * @param {string | number | Date | DateOption[]} [defaultDate] Default date setting, used if `value` is unspecified. + * @param {number} [defaultHour] Initial hour in the time picker, effective when time picking is enabled. + * @param {number} [defaultMinute] Initial minute in the time picker, effective when time picking is enabled. + * @param {string | number | Date | DateOption[]} [defaultValue] Alias for value-related properties. + * @param {DateLimit[]} [disable] List of dates to disable from selection, per Flatpickr syntax. + * @param {boolean} [disabled] Overall component disabled state. + * @param {boolean} [enableSeconds] Enables display of seconds in the time picker. + * @param {boolean} [enableTime] Enables time picker functionality alongside date. + * @param {ReactNode} [errortext] Helper text rendered when an error or validation warning is present. + * @param {ReactNode} [helptext] Text providing guidance or explanation of the component's use. + * @param {number} [hourIncrement] Step increment for hours when using the time picker. + * @param {string} [id] Unique ID for the component's input field, auto-generated if omitted. + * @param {boolean} [invalid] Shows an invalid state indicator, often for validation results. + * @param {string} [label] Label for the input field, describing its purpose. + * @param {LocaleKey | Partial} [locale] Locale object or key for international formatting. + * @param {DateOption} [maxDate] Maximum permissible date for input, inclusive. + * @param {DateOption} [minDate] Minimum permissible date for input, inclusive. + * @param {number} [minuteIncrement] Step increment for minutes in the time picker. + * @param {"single" | "multiple" | "range"} [mode] Picker mode: single, multiple, or date range. + * @param {"static" | "dropdown"} [monthSelectorType] Month selection dropdown type; static by default. + * @param {string} [name] Name attribute for HTML form integration. + * @param {boolean} [noCalendar] If true, excludes calendar, showing only the time picker. + * @param {DateChangeHandler} [onBlur] Handler for loss of focus events. + * @param {DateChangeHandler} [onChange] Handler for changes in date or time values. + * @param {DateChangeHandler} [onClear] Specific handler for clear icon interactions, also triggering onChange. + * @param {DateChangeHandler} [onClose] Handler when the calendar interface is closed. + * @param {DateChangeHandler} [onFocus] Handler when the input field receives focus. + * @param {DateChangeHandler} [onMonthChange] Handler for changes in month selection. + * @param {DateChangeHandler} [onOpen] Handler for when the calendar popup is opened. + * @param {DateChangeHandler} [onReady] Handler when the picker is ready for interaction. + * @param {DateChangeHandler} [onYearChange] Handler for changes in the year selection. + * @param {string} [placeholder] Placeholder text for the input. + * @param {boolean} [required] Marks field as required, demanding a Label component for context. + * @param {boolean} [shorthandCurrentMonth] Shows month abbreviated, e.g., "Jan" for "January". + * @param {number} [showMonths] Number of months to display at once. + * @param {ReactNode} [successtext] Success message when input is valid. + * @param {boolean} [time_24hr] Uses 24-hour format without AM/PM toggle. + * @param {boolean} [valid] Boolean specifying a validated state. + * @param {string | number | Date | DateOption[]} [value] Current value, optionally configurable. + * @param {boolean} [weekNumbers] Enables week number display in the calendar. + * @param {"full" | "auto"} [width] Sets input field width, "full" by default. + * @param {string} [wrapperClassName] Wrapper class for the container element for additional styling. + * @returns {React.ReactElement} A comprehensive date and time picker. + */ export const DateTimePicker: React.FC = ({ allowInput = false, allowInvalidPreload = false, @@ -558,132 +611,206 @@ type DateChangeHandler = (dates?: Date[], dateStr?: string, instance?: flatpickr export interface DateTimePickerProps extends Omit, "defaultValue" | "onFocus" | "onBlur" | "onChange"> { - /** Whether the DateTimePicker input element allows direct user keyboard input. Default is `false`. */ + /** + * Determines if the DateTimePicker input element allows direct keyboard input. + * @default false + */ allowInput?: boolean - /** Allows the preloading of an invalid date (e.g. a date that hass been disable by passing `disable`). When disabled, the field will be cleared if the provided date is invalid */ + + /** + * Allows preloading of invalid dates which clear if disabled. + */ allowInvalidPreload?: boolean - /** How the `aria-label` date for each day in the calendar will be formed. Uses the same rules/tokens as `dateFormat´ as described here: https://flatpickr.js.org/formatting/. When changing this, make sure the outcome makes sense when using a screenreader.*/ + + /** ARIA date formatting string for calendar accessibility. */ ariaDateFormat?: string - /** Pass custom classNames. These will be appended to the input element of the DateTimePicker. */ + + /** + * Custom class names appended to the DateTimePicker input element. + * @default "" + */ className?: string - /** A custom string to separate individual dates in `multiple` mode. */ + + /** Delimiter for dates in multiple selection mode. + * @default ", " + */ conjunction?: string - /** A string of characters to customize how a date will be formatted in the input field. Available options: https://flatpickr.js.org/formatting/ */ + + /** Custom date format string for input and display, per Flatpickr. */ dateFormat?: string + /** - * Sets the default date of the DateTimePicker. Same as `value`, only here for compatibility with the original Flatpickr library. If both `value` and `defaultDate` are being passed, `value` will win. Date Objects, timestamps, ISO date strings, chronological date strings `YYYY-MM-DD HH:MM` (must be compatible to current `dateFormat`), and the shortcut `today` are all accepted. + * Default date(s) set on initialization, secondary to `value`. */ defaultDate?: string | number | Date | DateOption[] - /** The initial value of the hour input element. Only effective if time is enabled. Note this will only set the hour input element to the value specified. Setting this options will not set a selected value on the DateTimePicker. */ + + /** + * Initial hour setting in the time component. + */ defaultHour?: number - /** The initial value of the minute input element. Only effective if time is enabled. Note this will only set the minute input element to the value specified. Setting this options will not set a selected value on the DateTimePicker. */ - defaultMinute?: number + /** - * Same as value, defaultDate + * Initial minute setting in the time component. */ + defaultMinute?: number + + /** Alternative default value representation. */ defaultValue?: string | number | Date | DateOption[] + + /** Array of dates or ranges to disable. */ + disable?: DateLimit[] + /** - * Pass an array of dates, date strings, date ranges or functions to disable dates. More on disabling dates: https://flatpickr.js.org/examples/#disabling-specific-dates + * Disables the DateTimePicker entirely. + * @default false */ - disable?: DateLimit[] - /** Whether the DateTimePicker is disabled */ disabled?: boolean - /** Whether to show seconds when showing a time picker. */ + + /** Enables seconds in the time picker. + * @default false + */ enableSeconds?: boolean - /** Whether to show a time picker. */ + + /** + * Enables a time selection feature. + * @default false + */ enableTime?: boolean - /** A text to render when the DateTimePicker has an error or could not be validated. */ + + /** Error message accompanying validation failure. */ errortext?: ReactNode - /** A helptext to render to explain meaning and significance of the DateTimePicker. */ + + /** Helper text to offer additional context or instructions. */ helptext?: ReactNode - /** The step for the hour input. Only has an effect when a time picker is enabled via `enableTime`. */ + + /** + * Hour step increment in time-picking mode. + */ hourIncrement?: number - /** The id of the DateTimePicker input element. If none is passed, an automatically generated id will be used. */ + + /** + * Unique input ID, generated if absent. + * @default Auto-generated ID + */ id?: string - /** Whether the DateTimePicker selected date was negatively validated. */ + + /** Invalid state representation. + * @default false + */ invalid?: boolean - /** The label of the DateTimePicker input element. */ + + /** Descriptive label for the time or date field. */ label?: string - /** - * Localization string or object. Can be used to set starting day of the week, e.g. Mondays instead of Sundays. More on localization: https://flatpickr.js.org/localization/ - */ + + /** Locale setting for calendar interaction, allowing adjustments like first day of the week. */ locale?: LocaleKey | Partial + /** - * The maximum / latest date a user can select (inclusive). + * Maximum selectable date. */ maxDate?: DateOption + /** - * The minimum / earliest date a user can select (inclusive). + * Minimum selectable date. */ minDate?: DateOption - /** The step for the minute input. Only has an effect when a time picker is enabled via `enableTime`. */ + + /** + * Minute step increment in time-picking mode. + */ minuteIncrement?: number - /** The mode of the Datepicker. */ + + /** Selection mode: single, multiple, or range. */ mode?: "single" | "multiple" | "range" - /** Whether to show a dropdown to select the current month. Default is "static". If `showMonths` is set to be greater than 1, it will always be displayed as static. Arrows to scroll through the months as well as through years will still be displayed and working. */ + + /** Dropdown setting for month selection. + * @default static + */ monthSelectorType?: "static" | "dropdown" - /** The name of the DateTimePicker input element */ + + /** Name attribute for the input, for form handling. */ name?: string - /** Set to `true` to not display a calendar at all. To create a time picker, set `enableTime` to true, too. */ - noCalendar?: boolean + /** - * A handler to be executed when the DateTimePicker input element looses focus. + * Hides the calendar, showing only time selectors if `enableTime` is true. */ + noCalendar?: boolean + + /** Handler for when the input field loses focus. */ onBlur?: DateChangeHandler - /** - * A handler to be executed when the selected date(s), date range or time changes - */ + + /** Handler for changes in date or time. */ onChange?: DateChangeHandler - /** - * A handler to be executed when the DateTimePicker value is reset by clicking the clear icon. The onChnage handler will be fired in this event too, onClear is more specific. - */ + + /** Specific handler for reset actions using the clear icon. */ onClear?: DateChangeHandler - /** - * A handler to be executed when the DateTimePicker calendar closes - */ + + /** Handler when closing the date picker. */ onClose?: DateChangeHandler - /** - * A handler to be executed when the DateTimePicker input element receives focus. - */ + + /** Handler for when the input field is focused. */ onFocus?: DateChangeHandler - /** - * A handler to be executed when the selected month changes - */ + + /** Handler for changes in selected month. */ onMonthChange?: DateChangeHandler - /** - * A handler to be executed when the DateTimePicker calendar opens - */ + + /** Handler when the calendar is opened. */ onOpen?: DateChangeHandler - /** - * A handler to be executed when the DateTimePicker component is ready - */ + + /** Handler for when the date-time picker is initialized. */ onReady?: DateChangeHandler - /** - * A handler to be executed when the selected year changes - */ + + /** Handler for changes in selected year. */ onYearChange?: DateChangeHandler - /** The placeholder of the DateTimePicker input element */ + + /** Placeholder text in the input. */ placeholder?: string - /** Whether the DateTimePicker should be marked as required. Requires a `Label` to be set. */ + + /** + * Marks the field as required, often with a visual prompt. + * @default false + */ required?: boolean - /** Whether the current month in the date picker should be displayed as shorthand, e.g. "Jan" instead of "January" */ + + /** Displays abbreviated month names, + * @default false + */ shorthandCurrentMonth?: boolean - /** The number of months to show in the date picker */ + + /** Number of months to show at once. */ showMonths?: number - /** A text to render when the DateTimePicker was successfully validated */ + + /** Success message shown on validation completion. */ successtext?: ReactNode - /** Displays time picker in 24 hour mode without AM/PM selection when enabled. Requires `enableTime` to be set, too. Default is `false`. */ + + /** Uses a 24-hour clock format. + * @default false + */ time_24hr?: boolean - /** Whether the DateTimePicker has been successfully validated */ - valid?: boolean + /** - * The value of the datepicker. Date Objects, timestamps, ISO date strings, chronological date strings `YYYY-MM-DD HH:MM` (must be compatible to current `dateFormat`), and the shortcut `today` are all accepted. + * Validation success state. + * @default false */ + valid?: boolean + + /** Current date or time value selection. */ value?: string | number | Date | DateOption[] - /** Whether to render week numbers. Default is `false`. */ + + /** + * Shows week numbers in the calendar. + * @default false + */ weekNumbers?: boolean - /** The width of the datepicker input. Either 'full' (default) or 'auto'. */ + + /** + * Input width setting: "full" (default) or "auto". + * @default "full" + */ width?: "full" | "auto" - /** Pass a custom className to the wrapping element. This can be useful if you must add styling to the outermost wrapping element of this component, e.g. for positioning. */ + + /** + * Additional classes for the wrapper element, aiding layout management. + */ wrapperClassName?: string } diff --git a/packages/ui-components/src/components/Form/Form.component.tsx b/packages/ui-components/src/components/Form/Form.component.tsx index 50d9227b8c..447cc7397a 100644 --- a/packages/ui-components/src/components/Form/Form.component.tsx +++ b/packages/ui-components/src/components/Form/Form.component.tsx @@ -18,11 +18,13 @@ const formTitleStyles = ` export interface FormProps extends FormHTMLAttributes { /** * Title for the form. + * @default "" */ title?: string /** * Additional CSS classes to apply to the form for custom styling. + * @default "" */ className?: string @@ -34,8 +36,15 @@ export interface FormProps extends FormHTMLAttributes { } /** - * A Form component used to encapsulate FormSections and/or FormGroups. - * Can be used to build complex forms with structured sections. + * The `Form` component is designed to encapsulate form sections and groups, + * providing a structured way to build complex forms. It can include a title and + * supports additional styling through custom CSS classes. + * + * @component + * @param {string} [title] Title for the form, displayed at the top. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Content within the form, typically form elements like `FormSection` or `FormGroup`. + * @returns {React.ReactElement} A structured form component for building complex forms. */ export const Form: React.FC = ({ title = "", className = "", children, ...props }) => { return ( diff --git a/packages/ui-components/src/components/FormHint/FormHint.component.tsx b/packages/ui-components/src/components/FormHint/FormHint.component.tsx index 3ea22c3eaa..4dc410876b 100644 --- a/packages/ui-components/src/components/FormHint/FormHint.component.tsx +++ b/packages/ui-components/src/components/FormHint/FormHint.component.tsx @@ -22,16 +22,19 @@ export interface FormHintProps extends React.HTMLAttributes { /** * The text to render as a hint for a form element. * Overridden by children, if provided. + * @default "" */ text?: ReactNode /** * The variant of the hint ("help", "error", or "success") determining its appearance. + * @default "help" */ variant?: FormHintVariant /** * Additional CSS classes to apply to the form hint for custom styling. + * @default "" */ className?: string } @@ -48,7 +51,15 @@ const getVariantStyles = (variant: FormHintVariant): string => { } /** - * A FormHint component used to provide contextual help, error, or success messages associated with form elements. + * The `FormHint` component provides contextual messages associated with form elements, + * such as help, error, or success messages. It adjusts appearance based on the variant specified. + * + * @component + * @param {React.ReactNode} [children] Content to display as the hint, takes precedence over `text`. + * @param {React.ReactNode} [text] Text for the hint, overridden by `children` if present. Defaults to an empty string. + * @param {FormHintVariant} [variant] Visual style of the hint: "help", "error", or "success". Defaults to `"help"`. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @returns {React.ReactElement} A form hint element with contextual styling. */ export const FormHint: React.FC = ({ children, diff --git a/packages/ui-components/src/components/FormRow/FormRow.component.tsx b/packages/ui-components/src/components/FormRow/FormRow.component.tsx index c0effb4a9e..bc7a68399f 100644 --- a/packages/ui-components/src/components/FormRow/FormRow.component.tsx +++ b/packages/ui-components/src/components/FormRow/FormRow.component.tsx @@ -18,13 +18,20 @@ export interface FormRowProps extends React.HTMLAttributes { /** * Additional CSS classes to apply to the FormRow for custom styling. + * @default "" */ className?: string } /** - * A generic FormRow component used to layout and structure form elements. - * It serves as a container for form elements such as TextInput, Textarea, Select, Radio, CheckboxGroups etc. + * The `FormRow` component structures individual form elements within a row layout. + * It serves as a container for inputs like `TextInput`, `Textarea`, and others, + * supporting custom styling with class names. + * + * @component + * @param {React.ReactNode} [children] Content rendered inside the FormRow, typically form elements. + * @param {string} [className] Custom CSS classes for styling the FormRow. Defaults to an empty string. + * @returns {React.ReactElement} A container for form row elements with support for custom styles. */ export const FormRow: React.FC = ({ children, className = "", ...props }) => { return ( diff --git a/packages/ui-components/src/components/FormSection/FormSection.component.tsx b/packages/ui-components/src/components/FormSection/FormSection.component.tsx index 28a486a787..559bc6182b 100644 --- a/packages/ui-components/src/components/FormSection/FormSection.component.tsx +++ b/packages/ui-components/src/components/FormSection/FormSection.component.tsx @@ -3,7 +3,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -import React, { HTMLAttributes } from "react" +import React, { HTMLAttributes, ReactNode } from "react" const formSectionBaseStyles = ` jn:mb-8 @@ -19,11 +19,13 @@ const headingStyles = ` export interface FormSectionProps extends HTMLAttributes { /** * Title for the form section. + * @default "" */ title?: string /** * Additional CSS classes to apply to the form section for custom styling. + * @default "" */ className?: string @@ -31,11 +33,18 @@ export interface FormSectionProps extends HTMLAttributes { * Content to be rendered within the form section. * This can include form elements and other React nodes. */ - children?: React.ReactNode + children?: ReactNode } /** - * FormSection component for grouping form elements within complex forms. + * The `FormSection` component groups related form elements within a section, + * offering a title and customizable styling. It assists in organizing content within forms. + * + * @component + * @param {string} [title] Section title, displayed at the top. Defaults to an empty string. + * @param {React.ReactNode} [children] Content to be rendered within the form section, can include form elements. + * @param {string} [className] Additional CSS classes for styling the form section. Defaults to an empty string. + * @returns {React.ReactElement} A component for grouping form elements within a defined section. */ export const FormSection: React.FC = ({ title = "", children, className = "", ...props }) => { return ( diff --git a/packages/ui-components/src/components/FormattedText/FormattedText.component.tsx b/packages/ui-components/src/components/FormattedText/FormattedText.component.tsx index 62fb8b8e51..97f5526b3d 100644 --- a/packages/ui-components/src/components/FormattedText/FormattedText.component.tsx +++ b/packages/ui-components/src/components/FormattedText/FormattedText.component.tsx @@ -7,13 +7,24 @@ import React from "react" import "./formatted-text.css" export interface FormattedTextProps extends React.HTMLAttributes { - /** Add custom class name */ + /** + * Custom CSS class name for styling the formatted text container. + * @default "" + */ className?: string + + /** Rendering content within the formatted text container. */ children?: React.ReactNode } /** - * A very basic layout container with padding. + * The `FormattedText` component provides a container for stylized text. + * It supports custom content and additional styling through class names. + * + * @component + * @param {string} [className] Custom CSS class names for styling the container. Defaults to an empty string. + * @param {React.ReactNode} [children] Content to be rendered within the formatted text container. + * @returns {React.ReactElement} A container for formatted text with customizable styles. */ export const FormattedText: React.FC = ({ className = "", // Default value for className diff --git a/packages/ui-components/src/components/Grid/Grid.component.tsx b/packages/ui-components/src/components/Grid/Grid.component.tsx index bde3830054..efc2fdc0e1 100644 --- a/packages/ui-components/src/components/Grid/Grid.component.tsx +++ b/packages/ui-components/src/components/Grid/Grid.component.tsx @@ -3,7 +3,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -import React from "react" +import React, { ReactNode } from "react" // Styles to apply when the 'auto' prop is true, overriding default grid column properties const autoStyles = { @@ -17,21 +17,32 @@ export interface GridProps extends React.HTMLAttributes { /** * Controls whether columns should auto-size. * If true, this will override the default 12-column grid layout. + * @default false */ auto?: boolean + /** * Elements to be rendered within the grid. */ - children?: React.ReactNode + children?: ReactNode + /** * Additional CSS classes to apply to the grid for custom styling. + * @default "" */ className?: string } /** - * A general-use grid component. - * Used in conjunction with GridColumn and GridRow components to create a flexible grid layout. + * The `Grid` component establishes a customizable grid layout, enabling + * responsive design. It collaborates with `GridColumn` and `GridRow` for + * flexible arrangement of content. + * + * @component + * @param {boolean} [auto] Enables auto-sizing of columns, overriding default grid layout. Defaults to `false`. + * @param {React.ReactNode} [children] Elements to be displayed within the grid framework. + * @param {string} [className] Additional CSS classes for styling the grid. Defaults to an empty string. + * @returns {React.ReactElement} A responsive grid layout with configurable column settings. */ export const Grid: React.FC = ({ auto = false, children, className = "", ...props }) => { const gridStyles = auto ? autoStyles : {} diff --git a/packages/ui-components/src/components/GridColumn/GridColumn.component.tsx b/packages/ui-components/src/components/GridColumn/GridColumn.component.tsx index 64d78d2d85..70dd44999f 100644 --- a/packages/ui-components/src/components/GridColumn/GridColumn.component.tsx +++ b/packages/ui-components/src/components/GridColumn/GridColumn.component.tsx @@ -3,7 +3,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -import React from "react" +import React, { ReactNode } from "react" const baseColumnStyles = ` jn:flex-grid-column @@ -43,27 +43,43 @@ export interface GridColumnProps extends React.HTMLAttributes { * The number of columns to span the column over. */ cols?: number + /** * The width in percent. * If a width is given, it will override the 'cols' prop. */ width?: number + /** * Determines whether the column should set an auto width. + * @default false */ auto?: boolean + /** * Additional CSS classes to apply to the grid column for custom styling. + * @default "" */ className?: string + /** * Content to be rendered inside the column. */ - children?: React.ReactNode + children?: ReactNode } /** - * A flexible grid column component used within a Grid. + * The `GridColumn` component represents an individual column within a `Grid`, + * providing options for span and width adjustments. It supports flexible styling + * for responsive layout. + * + * @component + * @param {number} [cols] Number of columns to span across. Overrides default width. + * @param {number} [width] Percentage width, supersedes `cols` if specified. + * @param {boolean} [auto] Sets column to auto width for flexible layout. Defaults to `false`. + * @param {string} [className] Additional CSS classes for styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Content to be rendered inside the column. + * @returns {React.ReactElement} A configurable grid column for layout customization. */ export const GridColumn: React.FC = ({ width, diff --git a/packages/ui-components/src/components/GridRow/GridRow.component.tsx b/packages/ui-components/src/components/GridRow/GridRow.component.tsx index 5f96eb8eaf..08b584a0e4 100644 --- a/packages/ui-components/src/components/GridRow/GridRow.component.tsx +++ b/packages/ui-components/src/components/GridRow/GridRow.component.tsx @@ -3,7 +3,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -import React from "react" +import React, { ReactNode } from "react" const baseRowStyles = ` jn:flex @@ -16,16 +16,23 @@ export interface GridRowProps extends React.HTMLAttributes { * Elements to be rendered within the grid row. * Typically, these would be GridColumn components. */ - children?: React.ReactNode + children?: ReactNode + /** * Additional CSS classes to apply to the grid row for custom styling. + * @default "" */ className?: string } /** - * A grid row container to hold GridColumn elements inside a Grid. - * This component ensures that its children are wrapped correctly in a flexbox layout. + * The `GridRow` component acts as a container to hold `GridColumn` elements + * within a `Grid`. It ensures proper flexbox wrapping for responsive design. + * + * @component + * @param {React.ReactNode} [children] Elements or `GridColumn` components to render inside the row. + * @param {string} [className] Additional CSS classes for styling the row. Defaults to an empty string. + * @returns {React.ReactElement} A row component for flexbox grid arrangements. */ export const GridRow: React.FC = ({ children, className = "", ...props }) => { return ( diff --git a/packages/ui-components/src/components/HeaderContainer/HeaderContainer.component.tsx b/packages/ui-components/src/components/HeaderContainer/HeaderContainer.component.tsx index ed2be046b8..02ede89936 100644 --- a/packages/ui-components/src/components/HeaderContainer/HeaderContainer.component.tsx +++ b/packages/ui-components/src/components/HeaderContainer/HeaderContainer.component.tsx @@ -3,7 +3,7 @@ * SPDX-License-Identifier: Apache-2.0 */ -import React from "react" +import React, { ReactNode } from "react" const headerContainerStyles = ` jn:flex @@ -15,6 +15,16 @@ const headerContainerStyles = ` jn:bg-theme-global-bg ` +/** + * The `HeaderContainer` component serves as a fixed, styled container at the top + * of a page or view, supporting full-width or constrained layouts. + * + * @component + * @param {boolean} [fullWidth] Specifies if the content should stretch to full viewport width. Defaults to `false`. + * @param {string} [className] Additional CSS classes for styling the header container. Defaults to an empty string. + * @param {React.ReactNode} [children] Content wrapped within the header container. + * @returns {React.ReactElement} A configurable container for header content. + */ export const HeaderContainer: React.FC = ({ fullWidth = false, className = "", @@ -36,9 +46,20 @@ export const HeaderContainer: React.FC = ({ } export interface HeaderContainerProps extends React.HTMLAttributes { - /** Whether the page/view content will stretch over the full width of the viewport or not. Default is `false`. */ + /** + * Whether the page/view content will stretch over the full width of the viewport or not. + * @default false + */ fullWidth?: boolean - /** Add custom class name */ + + /** + * Custom CSS class name to apply to the header container. + * @default "" + */ className?: string - children?: React.ReactNode + + /** + * Content to be rendered within the header container. + */ + children?: ReactNode } diff --git a/packages/ui-components/src/components/Icon/Icon.component.tsx b/packages/ui-components/src/components/Icon/Icon.component.tsx index 16dd82b37e..0a4818e004 100644 --- a/packages/ui-components/src/components/Icon/Icon.component.tsx +++ b/packages/ui-components/src/components/Icon/Icon.component.tsx @@ -942,6 +942,21 @@ const getColoredSizedIcon = ({ icon, color, size, title, iconClassName, ...iconP } } +/** + * The `Icon` component provides a versatile way to render SVG icons with customizable size, + * color, and accessibility features. Icons can be interactive through click events or embedded links. + * + * @component + * @param {KnownIcons} [icon] The name of the icon to render, from the predefined set. + * @param {string} [color] Specifies the color to apply to the icon. + * @param {string | number} [size] Determines the size of the icon, in pixels or rem. + * @param {string} [title] Accessibility title attribute for the icon, providing context. + * @param {string} [className] Additional CSS class names for styling. Defaults to an empty string. + * @param {string} [href] URL for navigation when icon is clicked, rendering as an anchor if specified. + * @param {boolean} [disabled] Sets icon to a disabled state, preventing interaction. Defaults to `false`. + * @param {function} [onClick] Handler for click events when rendering as a button element. + * @returns {React.ReactElement} A customizable SVG icon component with interactive capabilities. + */ export const Icon = forwardRef(function Icon( { icon, color = "", size = 24, title = "", className = "", href = "", disabled = false, onClick, ...props }, ref @@ -997,12 +1012,32 @@ export const Icon = forwardRef export interface IconProps extends Omit | React.HTMLProps, "size"> { + /** The name of the icon to render. */ icon?: KnownIcons + + /** Specifies the color of the icon. */ color?: string + + /** Determines the size of the icon, either a number or string representing pixels/rem. */ size?: string | number + + /** Accessibility title for the icon, useful for screen readers. */ title?: string + + /** Additional CSS class names for custom styling. + * @default "" + */ className?: string + + /** URL for navigation via anchor element when clicked. */ href?: string + + /** + * Determines if the icon is interactive or not. + * @default false + */ disabled?: boolean + + /** Click event handler for icon interaction, applicable to button elements. */ onClick?: React.MouseEventHandler } diff --git a/packages/ui-components/src/components/InputGroup/InputGroup.component.tsx b/packages/ui-components/src/components/InputGroup/InputGroup.component.tsx index f4a8908387..3f13911312 100644 --- a/packages/ui-components/src/components/InputGroup/InputGroup.component.tsx +++ b/packages/ui-components/src/components/InputGroup/InputGroup.component.tsx @@ -15,17 +15,22 @@ export interface InputGroupProps extends React.HTMLAttributes { * This can be any React node or a collection of React nodes such as Buttons, TextInput, and Select elements. */ children?: React.ReactNode + /** * Additional CSS class name(s) to apply to the InputGroup for custom styling. + * @default "" */ className?: string + /** * The variant style to apply to the group and its children. */ variant?: VariantTypes + /** * If true, all elements within the InputGroup will be disabled. * Individual elements can override this setting if needed. + * @default false */ disabled?: boolean } @@ -33,10 +38,17 @@ export interface InputGroupProps extends React.HTMLAttributes { type InheritedProps = { variant?: VariantTypes; disabled?: boolean } /** - * Clones a child element with inherited variant and disabled props. - * Individual child props will override inherited ones if specified. + * The `InputGroup` component visually groups related elements such as buttons, + * text inputs, and select elements, providing cohesive styling and optional + * variant and disabled states. * - * @returns A cloned child element with the variant and disabled props applied. + * @component + * @param {React.ReactNode} [children] Elements to be rendered within the `InputGroup`. + * Typical uses include form controls like `Button`, `TextInput`, and `Select`. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {VariantTypes} [variant] Styling variant for the group and its children, such as "default", "primary", etc. + * @param {boolean} [disabled] If true, all elements within the `InputGroup` are disabled. Defaults to `false`. + * @returns {React.ReactElement} A styled grouping component for input-related elements. */ const cloneElementWithInheritedProps = ( child: ReactNode, diff --git a/packages/ui-components/src/components/IntroBox/IntroBox.component.tsx b/packages/ui-components/src/components/IntroBox/IntroBox.component.tsx index 1176fa814b..b7d13203e3 100644 --- a/packages/ui-components/src/components/IntroBox/IntroBox.component.tsx +++ b/packages/ui-components/src/components/IntroBox/IntroBox.component.tsx @@ -56,24 +56,55 @@ const introboxHeading = ` ` export interface IntroBoxProps extends Omit, "title"> { - /** Pass an optional title */ + /** + * Pass an optional title. + * @default "" + */ title?: string - /** Pass a string of text to be rendered as contents. Alternatively, contents can be passed as children (see below) */ + + /** + * Pass a string of text to be rendered as contents. Alternatively, contents can be passed as children (see below). + * @default "" + */ text?: string - /** Pass a custom class */ + + /** + * Pass a variant style to affect the layout of the intro box. + * @default "default" + */ variant?: "default" | "hero" - /** optional "hero" flavor image for hero variant. Specify as css bg image string pointing to an image in your app (see template app for an example). Will always be positioned top and right */ + + /** + * Optional "hero" flavor image for hero variant. Specify as css bg image string pointing to an image. + */ heroImage?: string - /** Pass a custom class */ + + /** + * Pass a custom class or classes for styling the intro box. + * @default "" + */ className?: string - /** Pass child nodes to be rendered as content */ + + /** + * Pass child nodes to be rendered as content, taking precedence over `text`. + */ children?: React.ReactNode } /** -* An Introbox holds generally important information to help understand the contents, purpose, or state of a whole page or view, or individual sections on longer pages. -Use sparingly, there should never be any two or more subsequent instances of Introbox as direct siblings/neighbors on an individual view. -*/ + * The `IntroBox` component presents important information about the contents, + * purpose, or state of a page or view, using distinct styles for emphasis. + * Supports "hero" variant with optional background images. + * + * @component + * @param {string} [title] Optional title for the intro box. Defaults to an empty string. + * @param {string} [text] Content text within the intro box, overridden by `children`. Defaults to an empty string. + * @param {"default" | "hero"} [variant] Style variant of the intro box, affecting layout and visuals. Defaults to "default". + * @param {string} [heroImage] Optional background image for the "hero" variant, specified as a CSS background image string. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Content elements to render inside the intro box, taking precedence over `text`. + * @returns {React.ReactElement} A styled component for presenting introductory information or alerts. + */ export const IntroBox: React.FC = ({ title = "", text = "", diff --git a/packages/ui-components/src/components/JsonViewer/JsonViewer.component.tsx b/packages/ui-components/src/components/JsonViewer/JsonViewer.component.tsx index 8b10d91750..62a3f1d21e 100644 --- a/packages/ui-components/src/components/JsonViewer/JsonViewer.component.tsx +++ b/packages/ui-components/src/components/JsonViewer/JsonViewer.component.tsx @@ -349,7 +349,23 @@ interface JsonDataProps extends React.HTMLAttributes { nestedLevel?: number } -/** A component to render json data in a nice way. */ +/** + * The `JsonViewer` component provides a structured visualization of JSON data, + * with support for syntax highlighting, collapsible elements, and search functionality. + * Tailorable themes and display settings are available for user customization. + * + * @component + * @param {string | object | object[]} [data] JSON data to render; essential for visualizing complex structures. + * @param {object} [style] Custom styles for the viewer. + * @param {boolean} [toolbar] Toggles display of options such as expansion control and search. + * @param {boolean} [showRoot] Displays the root node key, useful for distinguishing hierarchical data. Defaults to `false`. + * @param {ThemeType | JsonViewerTheme} [theme] Preset or custom theme for styling the JSON viewer. + * @param {boolean | number} [expanded] Controls default expansion level for JSON objects. Defaults to `1`. + * @param {boolean | number} [truncate] Maximum length for truncating strings; the default is 100 characters. + * @param {number} [indentWidth] Width for indentation in pixels. Defaults to `4`. + * @param {string} [className] Additional CSS classes for custom styling. + * @returns {React.ReactElement} A configurable and interactive JSON data viewer. + */ export const JsonViewer: React.FC = ({ data = {}, showRoot = false, @@ -408,17 +424,26 @@ export const JsonViewer: React.FC = ({ type ThemeType = "dark" | "light" export interface JsonViewerProps extends Omit, "data"> { - /** Pass a valid json. Required. */ - // data: PropTypes.object.isRequired, + /** + * JSON data to render; essential for visualizing complex structures. + */ data: string | object | object[] - /** pass a styles object */ + + /** Pass a styles object for inline customizations. */ style?: object - /** show toolbar */ + + /** + * Toggles toolbar display, including expansion and search functionalities. + * @default false + */ toolbar?: boolean - /** show root key */ + + /** + * Displays the root node key for hierarchical clarity. + * @default false + */ showRoot?: boolean - /** dark, light or map of colors - * + /** Preset theme (dark/light) or map of colors for custom styling. * @param dark dark theme * @param light light theme * @param base00 background @@ -439,12 +464,26 @@ export interface JsonViewerProps extends Omit, " * @param base0F copy icon, type "integer" */ theme?: themes.JsonViewerTheme | ThemeType - /** expanded can be true|false or a number. The number denotes the hierarchy level to which the object is expanded. */ + /** + * Default expansion level for JSON objects, set as true, false, or a numeric level. + * @default 1 + */ expanded?: boolean | number - // cut strings after max length is reached, default length is 100 characters, if set to true. Or specifcy a different character length. */ + + /** + * Max length for truncating strings within displayed JSON data; defaults to 100 characters if true. + */ truncate?: boolean | number - /* indent width */ + + /** + * Pixel width for indentation. + * @default 4 + */ indentWidth?: number - /* add custom classes */ + + /** + * Additional CSS classes for styled customization. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/Label/Label.component.tsx b/packages/ui-components/src/components/Label/Label.component.tsx index 8332a1b74a..478fecb323 100644 --- a/packages/ui-components/src/components/Label/Label.component.tsx +++ b/packages/ui-components/src/components/Label/Label.component.tsx @@ -42,9 +42,19 @@ const disabledstyles = ` ` /** - * A re-usable Label component + * The `Label` component is a reusable, accessible label for form elements. + * It supports optional features like disabling, required indicators, and floating label styles. + * + * @component + * @param {string} [text] Text content for the label. Required for visual representation. + * @param {string} [htmlFor] Associated ID of a form input, linking label functionality. + * @param {boolean} [required] Displays a required indicator alongside the label. Defaults to `false`. + * @param {string} [className] Custom class names for styling the label. Defaults to an empty string. + * @param {boolean} [disabled] Applies disabled styles, indicating non-interactive fields. + * @param {boolean} [floating] Enables floating label style for enhanced readability. Defaults to `false`. + * @param {boolean} [minimized] Applies minimized label style; requires `floating` set to `true`. Defaults to `false`. + * @returns {React.ReactElement} An accessible and styled form label component. */ - export const Label = React.forwardRef( ( { @@ -92,18 +102,43 @@ export const Label = React.forwardRef( Label.displayName = "Label" export interface LabelProps extends React.HTMLAttributes { - /** Pass a string of text to be rendered as contents. Required. */ + /** + * Text content for the label, required for display. + */ text?: string - /** An Id of an input element to associate the label with */ + + /** + * ID of an input element to associate the label with for accessibility. + */ htmlFor?: string - /** Required */ + + /** + * Displays the required indicator when set. + * @default false + */ required?: boolean - /** Pass a className */ + + /** + * Custom CSS class names for label styling. + * @default "" + */ className?: string - /** Label for a disabled input */ + + /** + * Enables disabled styling to indicate non-interactive fields. + * @default false + */ disabled?: boolean - /** Whether the label is floating */ + + /** + * Applies floating label styles for improved UX. + * @default false + */ floating?: boolean - /** Whether the label is minimized. Requires `floating` set to TRUE, otherwise it will have no effect. */ + + /** + * Applies minimized label styles; requires `floating` to be `true`. + * @default false + */ minimized?: boolean } diff --git a/packages/ui-components/src/components/LoadingIndicator/LoadingIndicator.component.tsx b/packages/ui-components/src/components/LoadingIndicator/LoadingIndicator.component.tsx index ddd5c90514..ff168e203b 100644 --- a/packages/ui-components/src/components/LoadingIndicator/LoadingIndicator.component.tsx +++ b/packages/ui-components/src/components/LoadingIndicator/LoadingIndicator.component.tsx @@ -8,11 +8,12 @@ import Loading from "./loading-indicator.svg" export interface LoadingIndicatorProps extends React.SVGAttributes { /** - * The size of the LoadingIndicator in pixels. - * Must be a positive number value. - * If a string, must be a valid number + * The size of the LoadingIndicator in pixels. Must be a positive number value. + * If a string, must be a valid number. + * @default 96 */ size?: string | number + /** * A custom class that can be applied to change the color of the LoadingIndicator. * By default, the LoadingIndicator will use the color of the current context. @@ -20,8 +21,10 @@ export interface LoadingIndicatorProps extends React.SVGAttributes { * Additionally, you can pass any other class that contains a "color:" CSS declaration. */ color?: string + /** * Additional CSS classes for custom styling. + * @default "" */ className?: string } @@ -29,10 +32,16 @@ export interface LoadingIndicatorProps extends React.SVGAttributes { const defaultSize = 96 /** - * Use this loading indicator to indicate that a full page, a significant portion of a page, or a panel is loading. - * For more generic use cases, including individual components and micro-interactions, use the Spinner component instead. + * The `LoadingIndicator` visually represents ongoing loading processes for pages, + * large sections, or panels, offering custom size and color adjustments. + * It's suitable for prominent loading displays rather than granular elements. + * + * @component + * @param {string | number} [size] Specifies the indicator size in pixels. Defaults to `96`. + * @param {string} [color] Sets the loading indicator's color, flexible via contextual or explicit CSS classes. + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @returns {React.ReactElement} A visual loading indicator for prominent operations. */ - export const LoadingIndicator: React.FC = ({ size = defaultSize, color = "", diff --git a/packages/ui-components/src/components/MainContainer/MainContainer.component.tsx b/packages/ui-components/src/components/MainContainer/MainContainer.component.tsx index 357647f734..69702c52cc 100644 --- a/packages/ui-components/src/components/MainContainer/MainContainer.component.tsx +++ b/packages/ui-components/src/components/MainContainer/MainContainer.component.tsx @@ -12,8 +12,13 @@ const mainStyles = ` ` /** - * Only needed if you want to build your app's scaffold manually. In most cases it is better to use the AppShell component instead. - * The main container for app content. + * The `MainContainer` is the core container for application content, ideal for manual scaffold setups. + * In most instances, `AppShell` offers a comprehensive layout alternative. + * + * @component + * @param {string} [className] Additional CSS classes for custom styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Content or components arranged within the main container. + * @returns {React.ReactElement} A styled container for app content, useful for manual setup. */ export const MainContainer: React.FC = ({ className = "", children, ...props }) => { return ( @@ -24,7 +29,14 @@ export const MainContainer: React.FC = ({ className = "", ch } export interface MainContainerProps extends React.HTMLAttributes { - /** Add custom class name */ + /** + * Custom CSS class names for styling the main container. + * @default "" + */ className?: string + + /** + * Components or content to render within the main container. + */ children?: React.ReactNode } diff --git a/packages/ui-components/src/components/MainContainerInner/MainContainerInner.component.tsx b/packages/ui-components/src/components/MainContainerInner/MainContainerInner.component.tsx index 0f39abb280..0a5a53a5d4 100644 --- a/packages/ui-components/src/components/MainContainerInner/MainContainerInner.component.tsx +++ b/packages/ui-components/src/components/MainContainerInner/MainContainerInner.component.tsx @@ -15,7 +15,16 @@ const constrainStyles = ` jn:2xl:mx-auto ` -/** An inner wrapper to constrain page / view content width. */ +/** + * `MainContainerInner` offers a structured inner wrapper for page content, enabling width constraints + * or full-width rendering as needed. + * + * @component + * @param {React.ReactNode} [children] Components or content to render within the container. + * @param {boolean} [fullWidth] Indicates if content should be full-width. Defaults to `false`. + * @param {string} [className] Additional CSS class names for stylized rendering. Defaults to an empty string. + * @returns {React.ReactElement} A structured inner container for page content. + */ export const MainContainerInner: React.FC = ({ children, fullWidth = false, @@ -37,10 +46,20 @@ export const MainContainerInner: React.FC = ({ } export interface MainContainerInnerProps extends React.HTMLAttributes { - /** The children to render */ + /** + * The children to render within the container. + */ children?: React.ReactNode - /** Whether the page/view content will stretch over the full width of the viewport or not. Default is `false`. */ + + /** + * Determines if content stretches to full viewport width. + * @default false + */ fullWidth?: boolean - /** Add a custom class */ + + /** + * Custom CSS class names for stylized rendering. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/MainTabs/MainTabs.component.tsx b/packages/ui-components/src/components/MainTabs/MainTabs.component.tsx index 0dfc3f23cd..446248ff48 100644 --- a/packages/ui-components/src/components/MainTabs/MainTabs.component.tsx +++ b/packages/ui-components/src/components/MainTabs/MainTabs.component.tsx @@ -6,8 +6,17 @@ import React from "react" import { Tabs } from "../Tabs/index" -/** -Main Tabs are used at the top of the content area when using the tabs to switch the complete content area content. If you only want to have tabs for parts of the content use 'Tabs' instead and place them in the part of the content where the tabbed content should live. You will probably want to use a 'Container' inside the TabPanels to get nice padding. +/** + * `MainTabs` represents primary tab navigation at the content area's top, for complete content switching. + * Ideal for major interface tabbing; use `Tabs` for partial content areas. + * + * @component + * @param {React.ReactNode} [children] Tab elements and panels configured inside `MainTabs`. + * @param {number} [defaultIndex] The index of the default selected tab in uncontrolled mode. + * @param {number | null} [selectedIndex] The index of the selected tab for controlled mode. + * @param {function} [onSelect] Handler for tab selection in controlled mode. + * @param {string} [className] Additional CSS classes for styling. Defaults to an empty string. + * @returns {React.ReactElement} A main tab navigation component for comprehensive content switching. */ export const MainTabs: React.FC = ({ children, @@ -32,15 +41,29 @@ export const MainTabs: React.FC = ({ } export interface MainTabsProps extends Omit, "onSelect"> { - /** All the child elements of MainTabs: Tab(s) inside a TabList and TabPanel(s) */ + /** + * All the child elements of MainTabs: Tab(s) inside a TabList and TabPanel(s). + */ children?: React.ReactNode - /** The index of the Tab to be selected by default in "Uncontrolled Mode" (default) where Tabs handle their state internally. Do not use in "Controlled Mode".*/ + + /** + * The index of the Tab to be selected by default in "Uncontrolled Mode" (default) where Tabs handle their state internally. Do not use in "Controlled Mode". + */ defaultIndex?: number - /** The index of the Tab to be selected by default. This enables "Controlled Mode" where the developer takes over control of the Tabs state and behaviour. Requires onSelect to be set.*/ + + /** + * The index of the Tab to be selected by default. This enables "Controlled Mode" where the developer takes over control of the Tabs state and behaviour. Requires onSelect to be set. + */ selectedIndex?: number | null - /** Handler required in "Controlled Mode" */ - // eslint-disable-next-line no-unused-vars - onSelect?: (value: number) => void - /** Add a custom className to the whole Tabs construct */ + + /** + * Handler required in "Controlled Mode". + */ + onSelect?: (_value: number) => void + + /** + * Add a custom className to the whole Tabs construct. + * @default "" + */ className?: string } diff --git a/packages/ui-components/src/components/Message/Message.component.tsx b/packages/ui-components/src/components/Message/Message.component.tsx index bed0b78bfd..380e9b27b0 100644 --- a/packages/ui-components/src/components/Message/Message.component.tsx +++ b/packages/ui-components/src/components/Message/Message.component.tsx @@ -65,12 +65,12 @@ export type MessageVariantType = "info" | "warning" | "danger" | "error" | "succ export interface MessageProps extends React.HTMLAttributes { /** - * Pass an optional title. + * Optional title for the message. */ title?: string /** - * Pass an optional string of text to be rendered as content. + * Optional string of text to be rendered as content. * Alternatively, content can be passed as children (see below). * If children are provided, they will take precedence. */ @@ -78,22 +78,26 @@ export interface MessageProps extends React.HTMLAttributes { /** * Specify an optional semantic variant that determines the appearance of a message. + * @default "info" */ variant?: MessageVariantType /** * Optional. If true, the message will have a 'close' button to dismiss it. + * @default false */ dismissible?: boolean /** * Optional. If true, the message will be automatically dismissed after the default or passed autoDismissTimeout. + * @default false */ autoDismiss?: boolean /** * Optional. The timeout in milliseconds after which the message auto-dismisses. * By default 10000 (10s). + * @default 10000 */ autoDismissTimeout?: number @@ -104,6 +108,7 @@ export interface MessageProps extends React.HTMLAttributes { /** * Pass an optional CSS class to apply to the message. + * @default "" */ className?: string @@ -206,8 +211,20 @@ const clearAutoDismissTimeout = (timeoutRef: React.MutableRefObject = ({ title, diff --git a/packages/ui-components/src/components/Modal/Modal.component.tsx b/packages/ui-components/src/components/Modal/Modal.component.tsx index be09cf75cc..72ed836f2d 100644 --- a/packages/ui-components/src/components/Modal/Modal.component.tsx +++ b/packages/ui-components/src/components/Modal/Modal.component.tsx @@ -73,18 +73,34 @@ const sizeClass = (size: ModalSize) => { } /** -A generic Modal component. - -The Modal component can automatically create cancelling and confirming buttons with the desired labels and handlers. - -For more complex use cases, more buttons, etc., an instance of `` with all custom content as children can be passed as prop `modalFooter` and will be rendered. - -The Modal uses a boolean 'open' prop to determine whether it is open or not. Alternatively, the open state can be handled outside the component, e.g. in a global state. In this case the 'open' prop needs to be passed as true always, otherwise the Modal component will not render. - -By default, the modal will close (i.e. set its `open` state to false) once the user cancels the Modal. When confirming, you will have to either set the `open` to false to close the modal, or use whatever global state mechanism you have to handle modals. - -To make the modal less intrusive and effectively un-modal it, pass `closeOnBackdropClick`. This will close the modal when the user clicks the modal backdrop. -*/ + * The `Modal` component provides a flexible dialog window for user interactions, + * supporting titles, dismissal controls, sizing options, and comprehensive footer configurations. + * + * @component + * @param {ReactNode} [title] Title for the modal, rendered as its heading; reference for accessibility. + * @param {ReactNode} [heading] Alternative method for specifying title; `title` takes precedence if both are defined. + * @param {string} [ariaLabel] ARIA label for modals without headings, assisting screen reader navigation. + * @param {HTMLElement | SVGElement | string} [initialFocus] Element focused upon modal opening, default is the first focusable element. + * @param {boolean} [open] Indicates if the modal is visible. Defaults to `false`. + * @param {boolean} [closeable] Allows closure via close button at top-right; defaults to `true`. + * @param {boolean} [closeOnEsc] Enables ESC key closure action. Defaults to `true`. + * @param {boolean} [closeOnBackdropClick] Closure upon clicking the backdrop, slightly "un-modal"-ing the interface. + * @param {boolean} [disableCloseButton] Disables functionality of the close button. + * @param {ModalSize} [size] Sets modal size, ranging from small to 2XL. + * @param {boolean} [unpad] Removes default padding inside the modal content area. + * @param {string} [className] Additional CSS classes for styling. Defaults to an empty string. + * @param {React.ReactNode} [children] Central modal content; customizable for varied interactivity. + * @param {React.ReactElement} [modalFooter] Integrates custom footer; defaults to `ModalFooter` if absent. + * @param {string} [confirmButtonLabel] Label for confirmation button in modal interactions, defaults to empty string. + * @param {string} [cancelButtonLabel] Label for the cancellation button, defaults to "Cancel". + * @param {KnownIcons} [confirmButtonIcon] Icon placed on the confirm button for visual clarity. + * @param {KnownIcons} [cancelButtonIcon] Appends icon to cancellation button. + * @param {boolean} [disableConfirmButton] Disables the confirm button's interactive action. + * @param {boolean} [disableCancelButton] Disables the cancel button's interactive functionality. + * @param {React.MouseEventHandler} [onConfirm] Execution of confirming modal actions; modal remains open unless externally controlled. + * @param {(event: React.MouseEvent | KeyboardEvent)} [onCancel] Callback for closure actions, covering ESC, close button, cancel button, and backdrop clicks. + * @returns {React.ReactElement} A comprehensive modal component with flexible configuration. + */ export const Modal: React.FC = ({ title = "", heading = "", @@ -254,49 +270,125 @@ export const Modal: React.FC = ({ type ModalSize = "small" | "large" | "xl" | "2xl" export interface ModalProps extends Omit, "size" | "title"> { - /** The title of the modal. This will be rendering as the heading of the modal, and the modal's `arial-labelledby` attribute will reference the title/heading element. If the modal does not have `title` or `heading`, use `ariaLabel` to provide an accessible name for the modal. */ + /** + * The title of the modal. This will be rendering as the heading of the modal, and the modal's `arial-labelledby` attribute will reference the title/heading element. If the modal does not have `title` or `heading`, use `ariaLabel` to provide an accessible name for the modal. + */ title?: ReactNode - /** Also the title of the modal, just for API flexibility. If both `title` and `heading` are passed, `title` will take precedence. */ + + /** + * Also the title of the modal, just for API flexibility. If both `title` and `heading` are passed, `title` will take precedence. + */ heading?: ReactNode - /** The aria-label of the modal. Use only if the modal does NOT have a `title` or `heading`. */ + + /** + * The aria-label of the modal. Use only if the modal does NOT have a `title` or `heading`. + */ ariaLabel?: string - /** By default, the first element in the tab order of the Modal content will be focussed. To specify an element to be focussed when the modal opens, pass an element, DOM node, or selector string. */ + + /** + * By default, the first element in the tab order of the Modal content will be focussed. To specify an element to be focussed when the modal opens, pass an element, DOM node, or selector string. + */ initialFocus?: HTMLElement | SVGElement | string - /** Whether the modal will be open */ + + /** + * Whether the modal will be open. + * @default false + */ open?: boolean - /** Whether the modal can be closed using an "X"-Button at the top right. Defaults to true. */ + + /** + * Whether the modal can be closed using an "X"-Button at the top right. + * @default true + */ closeable?: boolean - /** Whether the modal should be closed when the backdrop is clicked. Essentially 'un-modals' the modal. */ - closeOnEsc?: boolean - /** The Modal size */ + + /** + * Whether the modal should be closed when the backdrop is clicked. Essentially 'un-modals' the modal. + * @default false + */ closeOnBackdropClick?: boolean - /** Determines whether the close button should be disabled */ + + /** + * Determines whether the close button should be disabled. + * @default false + */ disableCloseButton?: boolean - /** Whether the modal can be closed by hitting the ESC key */ + + /** + * Whether the modal can be closed by hitting the ESC key. + * @default true + */ + closeOnEsc?: boolean + + /** + * The Modal size, determines the aesthetics of the modal. + * @default small + */ size?: ModalSize - /** Pass to remove default padding from the content area of the modal */ + + /** + * Pass to remove default padding from the content area of the modal. + * @default false + */ unpad?: boolean - /** Custom className to add to the modal */ + + /** + * Custom className to add to the modal for additional styling. + * @default "" + */ className?: string - /** The children of the modal. These will be rendered as the modal content. To render custom buttons at the bottom, see `modalFooter` below.*/ + + /** + * The children of the modal. These will be rendered as the modal content. To render custom buttons at the bottom, see `modalFooter` below. + */ children?: React.ReactNode - /** Optional. Pass a `` component with custom content as required. Will default to using the `` component internally. */ + + /** + * Optional. Pass a `` component with custom content as required. Will default to using the `` component internally. + */ modalFooter?: React.ReactElement - /** Pass a label to render a confirm button and a Cancel button */ + + /** + * Pass a label to render a confirm button and a Cancel button. + * @default "" + */ confirmButtonLabel?: string - /** Pass a label for the cancel button. Defaults to "Cancel" */ + + /** + * Pass a label for the cancel button. Defaults to "Cancel". + * @default "Cancel" + */ cancelButtonLabel?: string - /** Pass an Icon name to show on the confirming action button */ + + /** + * Pass an Icon name to show on the confirming action button. + */ confirmButtonIcon?: KnownIcons - /** Pass an icon name to show on the cancelling button */ + + /** + * Pass an icon name to show on the cancelling button. + */ cancelButtonIcon?: KnownIcons - /** Determines whether the confirm action button should be disabled */ + + /** + * Determines whether the confirm action button should be disabled. + * @default false + */ disableConfirmButton?: boolean - /** Determines whether the cancel action button should be disabled */ + + /** + * Determines whether the cancel action button should be disabled. + * @default false + */ disableCancelButton?: boolean - /** A handler to execute once the modal is confirmed by clicking the confrim button if exists. Note that we do not close the modal automatically. */ + + /** + * A handler to execute once the modal is confirmed by clicking the confirm button if exists. Note that we do not close the modal automatically. + */ onConfirm?: React.MouseEventHandler - /** A handler to execute once the modal is cancelled or dismissed using the x-Close button, Cancel-button or pressing ESC */ - // eslint-disable-next-line no-unused-vars - onCancel?: (event: React.MouseEvent | KeyboardEvent) => void + + /** + * A handler to execute once the modal is cancelled or dismissed using the x-Close button, Cancel-button or pressing ESC. + */ + onCancel?: (_event: React.MouseEvent | KeyboardEvent) => void } diff --git a/packages/ui-components/src/components/ModalFooter/ModalFooter.component.tsx b/packages/ui-components/src/components/ModalFooter/ModalFooter.component.tsx index 1580c2e072..aafc8f59e7 100644 --- a/packages/ui-components/src/components/ModalFooter/ModalFooter.component.tsx +++ b/packages/ui-components/src/components/ModalFooter/ModalFooter.component.tsx @@ -23,12 +23,23 @@ const defaultmodalfooterstyles = ` ` /** -A Footer component for Modal. -Renders a simple "Close" Button (and accepts a corresponding onCancel-handler) by default. -Can be passed a confirmButtonLabel and cancelButton label with corresponding onConfirm- and onCancel-handlers. -Can alternatively render all custom children as passed. -*/ - + * The `ModalFooter` component is a versatile footer meant for the `Modal`, offering + * default or customizable confirm and cancel buttons, and an option to pass + * custom content. + * + * @component + * @param {string} [className] Custom class names for styling and alignment, especially useful with custom content. + * @param {React.ReactNode} [children] Custom children content replacing default button structure. + * @param {string} [confirmButtonLabel] Label for the confirm button; its presence enables dual button mode. Defaults to empty string. + * @param {string} [cancelButtonLabel] Custom label for the cancel button, only effective alongside `confirmButtonLabel`. + * @param {KnownIcons} [confirmButtonIcon] Icon name for the confirm button enhancement. + * @param {KnownIcons} [cancelButtonIcon] Icon name for the cancel button enhancement. + * @param {boolean} [disableConfirmButton] Disables the confirm button functionality. Defaults to `false`. + * @param {boolean} [disableCancelButton] Disables the cancellation button functionality. Defaults to `false`. + * @param {React.MouseEventHandler} [onConfirm] Handler for confirm button click events. + * @param {React.MouseEventHandler} [onCancel] Handler for cancel button click events. + * @returns {React.ReactElement} A configurable footer for modals with standard or custom button arrangements. + */ export const ModalFooter: React.FC = ({ className = "", children, @@ -90,24 +101,58 @@ export const ModalFooter: React.FC = ({ } export interface ModalFooterProps extends React.HTMLProps { - /** A custom className. Useful to configure flex items alignment when passing custom content as children. */ + /** + * A custom className. Useful to configure flex items alignment when passing custom content as children. + * @default "" + */ className?: string - /** Custom children to render. */ + + /** + * Custom children content replacing default button structure. + */ children?: React.ReactNode - /** The label for the Confirm-button. When passed, the component will render a Confirm button and a cancel button, otherwise the component will ONLY render a Close-Button. */ + + /** + * The label for the Confirm-button. When passed, the component will render a Confirm button and a cancel button, otherwise the component will ONLY render a Close-Button. + * @default "" + */ confirmButtonLabel?: string - /** Custom label for the cancel button. ONLY has an effect if a `confirmButtonLabel` is passed. */ + + /** + * Custom label for the cancel button. ONLY has an effect if a `confirmButtonLabel` is passed. + * @default "Close" + */ cancelButtonLabel?: string - /** Pass an Icon name to show on the confirming action button */ + + /** + * Pass an Icon name to show on the confirming action button. + */ confirmButtonIcon?: KnownIcons - /** Pass an icon name to show on the cancelling button */ + + /** + * Pass an icon name to show on the cancelling button. + */ cancelButtonIcon?: KnownIcons - /** Determines whether the confirm action button should be disabled */ + + /** + * Determines whether the confirm action button should be disabled. + * @default false + */ disableConfirmButton?: boolean - /** Determines whether the cancel action button should be disabled */ + + /** + * Determines whether the cancel action button should be disabled. + * @default false + */ disableCancelButton?: boolean - /** Handler to execute once the confirming button is clicked */ + + /** + * Handler to execute once the confirming button is clicked. + */ onConfirm?: React.MouseEventHandler - /** Handler to execute once the cancelling button is clicked */ + + /** + * Handler to execute once the cancelling button is clicked. + */ onCancel?: React.MouseEventHandler } diff --git a/packages/ui-components/src/components/NativeSelect/NativeSelect.component.tsx b/packages/ui-components/src/components/NativeSelect/NativeSelect.component.tsx index 33431406b2..8f0ba1aa12 100644 --- a/packages/ui-components/src/components/NativeSelect/NativeSelect.component.tsx +++ b/packages/ui-components/src/components/NativeSelect/NativeSelect.component.tsx @@ -95,6 +95,7 @@ export interface NativeSelectProps extends React.SelectHTMLAttributes /** * Event handler for the click event on the select element. * Triggered when the user clicks on the select element. */ - onClick?: MouseEventHandler /** * Additional CSS classes to apply to the outer wrapper of the select component for custom styling. + * @default "" */ wrapperClassName?: string } @@ -196,9 +202,24 @@ const SelectIcons: FC<{ } /** - * A basic, uncontrolled native HTML select component. - * Takes NativeSelectOption and NativeSelectOptionGroup children as options. - * Handles states such as loading, valid, invalid, and error. + * The `NativeSelect` component is a basic HTML select element with extra features + * such as styles and loading/error states. It supports native select options while + * offering customization for validation indicators. + * + * @component + * @param {string} [name] Key/name associated with the select value during form submissions. + * @param {string} [id] Identifier for the select element to ensure unique accessibility. + * @param {string} [className] CSS class names for styling the select element. Defaults to an empty string. + * @param {React.ReactNode} [children] Options or groups rendered within the select element. Defaults to empty. + * @param {boolean} [disabled] Disables component interactions, rendering it unclickable. Defaults to `false`. + * @param {boolean} [invalid] Highlights the select element for invalid input or validation errors. Defaults to `false`. + * @param {boolean} [valid] Signifies successful input or validation, with visual highlights. Defaults to `false`. + * @param {boolean} [loading] Displays a loading state over the select during asynchronous operations. Defaults to `false`. + * @param {boolean} [error] Shows error status, commonly for data-fetching issues, not validation errors. Defaults to `false`. + * @param {ChangeEventHandler} [onChange] Response to changes in selection amongst options. + * @param {MouseEventHandler} [onClick] Handler for click events on the select dropdown. + * @param {string} [wrapperClassName] CSS class names for styling the outer wrapper around the component. Defaults to an empty string. + * @returns {React.ReactElement} A configurable and interactive native select component. */ export const NativeSelect: FC = ({ name = "Unnamed Select", diff --git a/packages/ui-components/src/components/NativeSelectOption/NativeSelectOption.component.tsx b/packages/ui-components/src/components/NativeSelectOption/NativeSelectOption.component.tsx index 756b91aa96..165a343eb3 100644 --- a/packages/ui-components/src/components/NativeSelectOption/NativeSelectOption.component.tsx +++ b/packages/ui-components/src/components/NativeSelectOption/NativeSelectOption.component.tsx @@ -22,18 +22,27 @@ export interface NativeSelectOptionProps /** * Determines whether the option is disabled. * If true, the option will be unselectable. + * @default false */ disabled?: boolean /** * Additional CSS classes to apply to the option for custom styling. + * @default "" */ className?: string } /** - * The NativeSelectOption component represents an individual option in a dropdown list. - * It should be used inside the NativeSelect component to define each option. + * The `NativeSelectOption` represents individual options within a dropdown list + * for use in `NativeSelect`, offering label-value pairs with optional disable state. + * + * @component + * @param {string | number} [label] Visible label for the option within the dropdown menu. + * @param {string | number} [value] Value tied to the option, submitted during form process. + * @param {boolean} [disabled] Disables option selection, making it not selectable. Defaults to `false`. + * @param {string} [className] Additional CSS classes for customized styling. Defaults to an empty string. + * @returns {React.ReactElement} A self-contained option element for dropdown select menus. */ export const NativeSelectOption: React.FC = ({ value, diff --git a/packages/ui-components/src/components/NativeSelectOptionGroup/NativeSelectOptionGroup.component.tsx b/packages/ui-components/src/components/NativeSelectOptionGroup/NativeSelectOptionGroup.component.tsx index 65d0900908..e3dd60a467 100644 --- a/packages/ui-components/src/components/NativeSelectOptionGroup/NativeSelectOptionGroup.component.tsx +++ b/packages/ui-components/src/components/NativeSelectOptionGroup/NativeSelectOptionGroup.component.tsx @@ -15,11 +15,13 @@ export interface NativeSelectOptionGroupProps extends React.OptgroupHTMLAttribut /** * Determines whether the option group is disabled. * If true, all options within the group will also be disabled. + * @default false */ disabled?: boolean /** * Additional CSS classes to apply to the option group for custom styling. + * @default "" */ className?: string @@ -31,8 +33,15 @@ export interface NativeSelectOptionGroupProps extends React.OptgroupHTMLAttribut } /** - * The NativeSelectOptionGroup component groups related options within a dropdown list. - * It should be used inside the component to group components. + * The `NativeSelectOptionGroup` categorizes related options within a dropdown list, + * enhancing semantic groupings for larger datasets in `NativeSelect`. + * + * @component + * @param {string} [label] Group heading displayed for item contextualization within dropdown. + * @param {boolean} [disabled] Quando true, a group and each item within it are blocked from selection. Defaults to `false`. + * @param {string} [className] CSS classes applied for tailored style. Defaults to an empty string. + * @param {React.ReactNode} [children] `NativeSelectOption` components or items to be housed within the group. + * @returns {React.ReactElement} A component grouping related options for dropdown selections. */ export const NativeSelectOptionGroup: React.FC = ({ label = "", diff --git a/packages/ui-components/src/components/Navigation/Navigation.component.tsx b/packages/ui-components/src/components/Navigation/Navigation.component.tsx index 3acb51db73..3c0e692e8c 100644 --- a/packages/ui-components/src/components/Navigation/Navigation.component.tsx +++ b/packages/ui-components/src/components/Navigation/Navigation.component.tsx @@ -33,7 +33,20 @@ interface NavigationMappingItem { displayName: ReactNode } -/** A generic Navigation component providing all the necessary functionality for a navigation. For internal use only. Not to be used directly, but to be wrapped by more role-specific / semantic navigation components such as `TabNavigation`, `TopNavigation`, `SideNavigation`. */ +/** + * A generic `Navigation` component that offers context-managed item selection, + * designed for internal use with semantic wrappers like `SideNavigation`, + * `TabNavigation`, and `TopNavigation`. + * + * @component + * @param {ReactNode} [activeItem] Currently active item within the navigation context. + * @param {string} [ariaLabel] Descriptive label for navigation, aiding accessibility. + * @param {ReactNode} [children] Navigation items rendered within the container. + * @param {string} [className] Custom class names for styling navigation elements. Defaults to an empty string. + * @param {boolean} [disabled] Disables navigation state and its children. Defaults to `false`. + * @param {ItemChangeHandler} [onActiveItemChange] Callback fired on active item updates. + * @returns {React.ReactElement} A flexible navigation component serving organized item management. + */ export const Navigation: React.FC = ({ activeItem = "", ariaLabel = "", @@ -128,16 +141,35 @@ export const Navigation: React.FC = ({ } export interface NavigationProps extends React.HTMLAttributes { - /** The currently active item. Pass the `value`, `label` prop, or the child string of the respective NavigationItem. */ + /** + * The currently active item. Pass the `value`, `label` prop, or the child string of the respective NavigationItem. + */ activeItem?: ReactNode - /** The aria label of the navigation */ + + /** + * The aria label of the navigation for accessibility purposes. + */ ariaLabel?: string - /** The child navigation items of the navigation */ + + /** + * The child navigation items to be rendered within the navigation component. + */ children?: ReactNode - /** Pass a custom className to the navigation parent element */ + + /** + * Pass a custom className to the navigation parent element. + * @default "" + */ className?: string - /** Whether the navigation is disabled. Will disable all children. */ + + /** + * Whether the navigation is disabled, affecting interactivity for all children. + * @default false + */ disabled?: boolean - /** Handler to execute when the active item changes. */ + + /** + * Handler to execute when the active item changes. + */ onActiveItemChange?: ItemChangeHandler } diff --git a/packages/ui-components/src/components/NavigationItem/NavigationItem.component.tsx b/packages/ui-components/src/components/NavigationItem/NavigationItem.component.tsx index 6fc332fecd..4c2fcfbc6c 100644 --- a/packages/ui-components/src/components/NavigationItem/NavigationItem.component.tsx +++ b/packages/ui-components/src/components/NavigationItem/NavigationItem.component.tsx @@ -18,7 +18,27 @@ const disabledStyles = ` jn:cursor-not-allowed ` -/** A generic Navigation Item component. For internal use only. Use to wrap more semantic, role-specific navigation item components such as `SidenavigationItem`, `TabNavigationItem` , `TopNavigationItem` around. */ +/** + * `NavigationItem` acts as a singular navigational unit within a `Navigation`, + * offering styles for active and inactive states, and supporting disabled + * interactions internally. + * + * @component + * @param {boolean} [active] Indicates if the item is currently selected; parent setting overrides if active item exists. + * @param {string} [activeItemStyles] CSS styles applied to the item when active. + * @param {string} [ariaLabel] ARIA label aiding navigational element description. + * @param {string} [className] Custom styling for the item element; impacts wrapper if `wrapperClassName` is undefined. Defaults to an empty string. + * @param {ReactNode} [children] Content or label rendered within the navigation item. + * @param {boolean} [disabled] Toggles the disabled attribute, preventing interactivity. Defaults to `false`. + * @param {KnownIcons} [icon] An icon displayed within the item for visual representation. + * @param {string} [inactiveItemStyles] Styles applied to items when inactive to differentiate visually. + * @param {string} [label] Alternative label text if `children` is absent, impacting rendered content. + * @param {string} [href] When specified, renders the item as an anchor element for navigation. + * @param {React.MouseEventHandler} [onClick] Click event handler, executing custom logic for the item. + * @param {string} [value] Technical identifier through item value, usable when child strings are not available. + * @param {string} [wrapperClassName] Class names for `
  • ` element wrapping the navigation item itself. Defaults to an empty string. + * @returns {React.ReactElement} A detailed navigational unit with configurable styles and states. + */ export const NavigationItem: React.FC = ({ active = false, activeItemStyles = "", @@ -150,30 +170,74 @@ export const NavigationItem: React.FC = ({ } export interface NavigationItemProps extends React.HTMLAttributes { - /** Whether the navigation item is the currently active item. If an acitve item is set on the parent, the one on the parent will win. */ + /** + * Whether the navigation item is the currently active item. If an active item is set on the parent, the one on the parent will win. + * @default false + */ active?: boolean - /** Styles to apply to the active item*/ + + /** + * Styles to apply when the item is active. + * @default "" + */ activeItemStyles?: string - /** The aria-label of the item */ + + /** + * The aria-label of the item for accessibility. + */ ariaLabel?: string - /** Pass custom classNames to the item itself. */ + + /** + * Pass custom classNames to the item itself. + * @default "" + */ className?: string - /** The child string of the item. Will override `label` when passed. */ + + /** + * The child nodes of the item, overriding `label` if specified. + */ children?: ReactNode - /** Whether the item is disabled */ + + /** + * Determines if the item is disabled. + * @default false + */ disabled?: boolean - /** An icon to render in the item */ + + /** + * An icon to render within the item for visual indication. + */ icon?: KnownIcons - /* Pass styles that apply to IN-active items only, in the event activeStyles are overwritten by defaultStyles affecting the same CSS property*/ + + /** + * Styles applied to inactive items, ensuring differentiation from active. + * @default "" + */ inactiveItemStyles?: string - /** The label of the item. Will be rendered if no children are passed */ + + /** + * The label of the item, displayed if `children` are not provided. + */ label?: string - /** The href of the item. The item will be rendered as an `` element when passed, instead of a `