@bspk/ui 1.1.21 → 1.1.23

package/src/SegmentedControl.tsx

@@ -8,18 +8,23 @@ import { ElementProps } from './';
 
 export type SegmentedControlOption = {
     /**
-     * The label of the option. This is the text that will be displayed on the option.
+     * The label of the option. This is the text that will be displayed on the
+     * option.
      *
      * @required
      */
     label: string;
     /**
-     * Determines if the element is [disabled](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled).
+     * Determines if the element is
+     * [disabled](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled).
      *
      * @default false
      */
     disabled?: boolean;
-    /** The value of the option. If not provided, the label will be used as the value. */
+    /**
+     * The value of the option. If not provided, the label will be used as the
+     * value.
+     */
     value?: string;
     /**
      * The the icon to display before the label.
@@ -37,7 +42,8 @@ export type SegmentedControlOption = {
 
 export type SegmentedControlProps = {
     /**
-     * The options to display. Each option has a label and an optional leading icon.
+     * The options to display. Each option has a label and an optional leading
+     * icon.
      *
      * @example
      *     [
@@ -72,15 +78,16 @@ export type SegmentedControlProps = {
      */
     size?: 'medium' | 'small';
     /**
-     * The width of the options. If set to 'fill', the options will fill the width of the container. If set to 'hug',
-     * the options will be as wide as their content.
+     * The width of the options. If set to 'fill', the options will fill the
+     * width of the container. If set to 'hug', the options will be as wide as
+     * their content.
      *
      * @default hug
      */
     width?: 'fill' | 'hug';
     /**
-     * Determines if the labels of the options should be displayed. If icons are not provided for every option this is
-     * ignored and labels are shown.
+     * Determines if the labels of the options should be displayed. If icons are
+     * not provided for every option this is ignored and labels are shown.
      *
      * @default true
      */
@@ -90,6 +97,26 @@ export type SegmentedControlProps = {
 /**
  * Navigation tool that organizes content across different screens and views.
  *
+ * @example
+ *     import { useState } from 'react';
+ *     import { SegmentedControl } from '@bspk/ui/SegmentedControl';
+ *
+ *     export function Example() {
+ *         const [selectedOption, setSelectedOption] = useState<string>();
+ *
+ *         return (
+ *             <SegmentedControl
+ *                 onChange={setSelectedOption}
+ *                 options={[
+ *                     { value: '1', label: 'Option 1' },
+ *                     { value: '2', label: 'Option 2' },
+ *                     { value: '3', label: 'Option 3' },
+ *                 ]}
+ *                 value={selectedOption}
+ *             />
+ *         );
+ *     }
+ *
  * @name SegmentedControl
  */
 function SegmentedControl({
@@ -104,26 +131,42 @@ function SegmentedControl({
     const options = Array.isArray(optionsProp) ? optionsProp : [];
     useOptionIconsInvalid(options);
 
-    const hideLabels = showLabelsProp === false && options.every((item) => item.icon && item.label);
+    const hideLabels =
+        showLabelsProp === false &&
+        options.every((item) => item.icon && item.label);
 
     return (
-        <div {...containerProps} data-bspk="segmented-control" data-size={size} data-width={width}>
+        <div
+            {...containerProps}
+            data-bspk="segmented-control"
+            data-size={size}
+            data-width={width}
+        >
             {options.map((item, index) => {
                 const isActive = item.value === value;
                 return (
                     <Fragment key={item.value}>
-                        <Tooltip disabled={!hideLabels} label={item.label} placement="top">
+                        <Tooltip
+                            disabled={!hideLabels}
+                            label={item.label}
+                            placement="top"
+                        >
                             <button
                                 aria-label={item.label}
                                 data-first={index === 0 || undefined}
-                                data-last={index === options.length - 1 || undefined}
+                                data-last={
+                                    index === options.length - 1 || undefined
+                                }
                                 data-selected={isActive || undefined}
                                 disabled={item.disabled || undefined}
-                                onClick={() => onChange(item.value || item.label)}
+                                onClick={() =>
+                                    onChange(item.value || item.label)
+                                }
                             >
                                 <span data-outer>
                                     <span data-inner>
-                                        {(isActive && item.iconActive) || item.icon}
+                                        {(isActive && item.iconActive) ||
+                                            item.icon}
                                         {!hideLabels && item.label}
                                     </span>
                                 </span>

package/src/Skeleton.tsx

@@ -44,7 +44,9 @@ export type SkeletonProps = {
  * displayed on the screen.
  *
  * @example
- *     function Example() {
+ *     import { Skeleton } from '@bspk/ui/skeleton';
+ *
+ *     function Example(item: { title: string; src: string } | null) {
  *         return item ? (
  *             <img
  *                 style={{

package/src/Switch.tsx

@@ -22,7 +22,24 @@ export type SwitchProps = CommonProps<'aria-label' | 'disabled' | 'name' | 'valu
 /**
  * A control element that allows users to toggle between two states, typically representing on/off and inherits
  * immediate reaction in each state. This is the base element and if used directly you must wrap it with a label. This
- * will more often be used in the SwitchOption or SwitchGroup component.
+ * will more often be used in the SwitchOption component.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { Switch } from '@bspk/ui/Switch';
+ *
+ *     export function Example() {
+ *         const [isChecked, setIsChecked] = useState<boolean>(false);
+ *
+ *         return (
+ *             <Switch
+ *                 aria-label="Example aria-label"
+ *                 name="Example name"
+ *                 onChange={setIsChecked}
+ *                 checked={isChecked}
+ *             />
+ *         );
+ *     }
  *
  * @element
  *

package/src/SwitchOption.tsx

@@ -1,19 +1,24 @@
 import { SwitchProps, Switch } from './Switch';
 import { ToggleOptionProps, ToggleOption } from './ToggleOption';
 
-export type SwitchOptionProps = Omit<SwitchProps, 'aria-label'> &
-    Pick<ToggleOptionProps, 'description' | 'label' | 'size'>;
+export type SwitchOptionProps = Omit<SwitchProps, 'aria-label'> & Pick<ToggleOptionProps, 'description' | 'label'>;
 
 /**
  * A control that allows users to choose one or more items from a list or turn an feature on or off.
  *
+ * If only a switch is needed, consider using the `Switch` component directly.
+ *
  * @name SwitchOption
  */
-function SwitchOption({ label, description, size, ...checkboxProps }: SwitchOptionProps) {
+function SwitchOption({ label: labelProp, description, ...checkboxProps }: SwitchOptionProps) {
+    const label = labelProp || description;
+
     return (
-        <ToggleOption data-bspk="switch-option" description={description} label={label} size={size}>
-            <Switch {...checkboxProps} aria-label={label} />
-        </ToggleOption>
+        label && (
+            <ToggleOption data-bspk="switch-option" description={description} label={label}>
+                <Switch {...checkboxProps} aria-label={label} />
+            </ToggleOption>
+        )
     );
 }
 

package/src/TabGroup.tsx

@@ -22,7 +22,8 @@ export type TabGroupOption = {
      */
     label: string;
     /**
-     * Determines if the element is [disabled](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled).
+     * Determines if the element is
+     * [disabled](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled).
      *
      * @default false
      */
@@ -86,15 +87,15 @@ export type TabGroupProps = {
      */
     size?: TabGroupSize;
     /**
-     * When 'fill' the options will fill the width of the container. When 'hug', the options will be as wide as their
-     * content.
+     * When 'fill' the options will fill the width of the container. When 'hug',
+     * the options will be as wide as their content.
      *
      * @default hug
      */
     width?: 'fill' | 'hug';
     /**
-     * When width is 'hug' this determines if the trailing underline should be showing. When width is 'fill' this
-     * property isn't applicable.
+     * When width is 'hug' this determines if the trailing underline should be
+     * showing. When width is 'fill' this property isn't applicable.
      *
      * @default false
      */
@@ -104,6 +105,26 @@ export type TabGroupProps = {
 /**
  * Navigation tool that organizes content across different screens and views.
  *
+ * @example
+ *     import { useState } from 'react';
+ *     import { TabGroup } from '@bspk/ui/TabGroup';
+ *
+ *     export function Example() {
+ *         const [selectedTab, setSelectedTab] = useState<string>();
+ *
+ *         return (
+ *             <TabGroup
+ *                 onChange={setSelectedTab}
+ *                 options={[
+ *                     { value: '1', label: 'Option 1' },
+ *                     { value: '2', label: 'Option 2' },
+ *                     { value: '3', label: 'Option 3' },
+ *                 ]}
+ *                 value={selectedTab}
+ *             />
+ *         );
+ *     }
+ *
  * @name TabGroup
  */
 function TabGroup({
@@ -143,7 +164,10 @@ function TabGroup({
                             {(isActive && item.iconActive) || item.icon}
                             {item.label}
                             {item.badge && !item.disabled && !isActive && (
-                                <Badge count={item.badge} size={TAB_BADGE_SIZES[size]} />
+                                <Badge
+                                    count={item.badge}
+                                    size={TAB_BADGE_SIZES[size]}
+                                />
                             )}
                         </span>
                     </button>

package/src/Tag.tsx

@@ -51,7 +51,19 @@ export type TagProps<As extends ElementType = 'span'> = {
 };
 
 /**
- * A non-interactive visual indicators to draw attention or categorization of a component.
+ * A non-interactive visual indicators to draw attention or categorization of a
+ * component.
+ *
+ * @example
+ *     import { Tag } from '@bspk/ui/Tag';
+ *
+ *     export function Example() {
+ *         return (
+ *             <Tag variant="flat" color="primary">
+ *                 Example Tag
+ *             </Tag>
+ *         );
+ *     }
  *
  * @name Tag
  */

package/src/TextField.tsx

@@ -3,7 +3,12 @@ import { TextInputProps, TextInput } from './TextInput';
 
 import { InvalidPropsLibrary } from '.';
 
-export type TextFieldProps = InvalidPropsLibrary &
+export type TextFieldProps =
+    InvalidPropsLibrary &
+    Pick<
+        FormFieldProps,
+        'controlId' | 'errorMessage' | 'helperText' | 'label' | 'labelTrailing'
+    > &
     Pick<
         TextInputProps,
         | 'autoComplete'
@@ -19,14 +24,32 @@ export type TextFieldProps = InvalidPropsLibrary &
         | 'trailing'
         | 'type'
         | 'value'
-    > &
-    Pick<FormFieldProps, 'controlId' | 'errorMessage' | 'helperText' | 'label' | 'labelTrailing'>;
+    >;
 
 /**
- * A text input that allows users to enter text, numbers or symbols in a singular line.
+ * A text input that allows users to enter text, numbers or symbols in a
+ * singular line.
  *
  * This component takes properties from the FormField and TextInput components.
  *
+ * @example
+ *     import { useState } from 'react';
+ *     import { TextField } from '@bspk/ui/TextField';
+ *
+ *     export function Example() {
+ *         const [value, setValue] = useState<string>('');
+ *
+ *         return (
+ *             <TextField
+ *                 controlId="Example controlId"
+ *                 label="Example label"
+ *                 name="Example name"
+ *                 onChange={setValue}
+ *                 value={value}
+ *             />
+ *         );
+ *     }
+ *
  * @name TextField
  */
 function TextField({
@@ -38,7 +61,9 @@ function TextField({
     required,
     ...inputProps
 }: TextFieldProps) {
-    const errorMessage = (!inputProps.readOnly && !inputProps.disabled && errorMessageProp) || undefined;
+    const errorMessage =
+        (!inputProps.readOnly && !inputProps.disabled && errorMessageProp) ||
+        undefined;
 
     return (
         <FormField
@@ -51,7 +76,13 @@ function TextField({
             required={required}
         >
             {(fieldProps) => (
-                <TextInput {...inputProps} {...fieldProps} aria-label={label} id={controlId} required={required} />
+                <TextInput
+                    {...inputProps}
+                    {...fieldProps}
+                    aria-label={label}
+                    id={controlId}
+                    required={required}
+                />
             )}
         </FormField>
     );

package/src/TextInput.tsx

@@ -1,5 +1,10 @@
 import { SvgCancel } from '@bspk/icons/Cancel';
-import { ChangeEvent, HTMLInputAutoCompleteAttribute, HTMLInputTypeAttribute, ReactNode } from 'react';
+import {
+    ChangeEvent,
+    HTMLInputAutoCompleteAttribute,
+    HTMLInputTypeAttribute,
+    ReactNode,
+} from 'react';
 
 import { useId } from './hooks/useId';
 
@@ -15,7 +20,14 @@ export const DEFAULT = {
 } as const;
 
 export type TextInputProps = CommonProps<
-    'aria-label' | 'disabled' | 'id' | 'name' | 'readOnly' | 'required' | 'size' | 'value'
+    | 'aria-label'
+    | 'disabled'
+    | 'id'
+    | 'name'
+    | 'readOnly'
+    | 'required'
+    | 'size'
+    | 'value'
 > &
     InvalidPropsLibrary & {
         /**
@@ -41,7 +53,8 @@ export type TextInputProps = CommonProps<
          */
         type?: Extract<HTMLInputTypeAttribute, 'number' | 'text'>;
         /**
-         * Specifies if user agent has any permission to provide automated assistance in filling out form field values.
+         * Specifies if user agent has any permission to provide automated
+         * assistance in filling out form field values.
          * https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
          *
          * @default off
@@ -50,8 +63,26 @@ export type TextInputProps = CommonProps<
     };
 
 /**
- * A text input that allows users to enter text, numbers or symbols in a singular line. This is the base element and is
- * not intended to be used directly. Use the TextField component.
+ * A text input that allows users to enter text, numbers or symbols in a
+ * singular line. This is the base element and is not intended to be used
+ * directly. Use the TextField component.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { TextInput } from '@bspk/ui/TextInput';
+ *
+ *     export function Example() {
+ *         const [value, setValue] = useState<string>('');
+ *
+ *         return (
+ *             <TextInput
+ *                 aria-label="Example aria-label"
+ *                 name="Example name"
+ *                 onChange={setValue}
+ *                 value={value}
+ *             />
+ *         );
+ *     }
  *
  * @element
  *

package/src/Textarea.tsx

@@ -11,7 +11,9 @@ const DEFAULT = {
     textSize: 'medium',
 } as const;
 
-export type TextareaProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'readOnly' | 'required'> &
+export type TextareaProps = CommonProps<
+    'aria-label' | 'disabled' | 'id' | 'readOnly' | 'required'
+> &
     InvalidPropsLibrary & {
         /**
          * Callback when the value of the field changes.
@@ -19,7 +21,10 @@ export type TextareaProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'read
          * @type (next: String, Event) => void
          * @required
          */
-        onChange: (next: string, event?: ChangeEvent<HTMLTextAreaElement>) => void;
+        onChange: (
+            next: string,
+            event?: ChangeEvent<HTMLTextAreaElement>,
+        ) => void;
         /**
          * The text size of the field.
          *
@@ -67,11 +72,30 @@ export type TextareaProps = CommonProps<'aria-label' | 'disabled' | 'id' | 'read
     };
 
 /**
- * A component that allows users to input large amounts of text that could span multiple lines.
+ * A component that allows users to input large amounts of text that could span
+ * multiple lines.
  *
- * This component gives you a textarea HTML element that automatically adjusts its height to match the length of the
- * content within maximum and minimum rows. A character counter when a maxLength is set to show the number of characters
- * remaining below the limit.
+ * This component gives you a textarea HTML element that automatically adjusts
+ * its height to match the length of the content within maximum and minimum
+ * rows. A character counter when a maxLength is set to show the number of
+ * characters remaining below the limit.
+ *
+ * @example
+ *     import { useState } from 'react';
+ *     import { Textarea } from '@bspk/ui/Textarea';
+ *
+ *     export function Example() {
+ *         const [value, setValue] = useState<string>('');
+ *
+ *         return (
+ *             <Textarea
+ *                 aria-label="Example aria-label"
+ *                 name="Example name"
+ *                 onChange={setValue}
+ *                 value={value}
+ *             />
+ *         );
+ *     }
  *
  * @element
  *
@@ -95,8 +119,14 @@ function Textarea({
     const id = useId(idProp);
     const invalid = !otherProps.readOnly && !otherProps.disabled && invalidProp;
     // ensure minRows and maxRows are within bounds
-    const minRows = Math.min(DEFAULT.maxRows, Math.max(minRowsProp, DEFAULT.minRows));
-    const maxRows = Math.max(DEFAULT.minRows, Math.min(maxRowsProp, DEFAULT.maxRows));
+    const minRows = Math.min(
+        DEFAULT.maxRows,
+        Math.max(minRowsProp, DEFAULT.minRows),
+    );
+    const maxRows = Math.max(
+        DEFAULT.minRows,
+        Math.min(maxRowsProp, DEFAULT.maxRows),
+    );
 
     return (
         <div
@@ -125,11 +155,13 @@ function Textarea({
                     const target = event.target as HTMLTextAreaElement;
                     // we know the textarea was resized, so we don't want to auto-size it
                     if (target.style.height) return;
-                    (target.nextSibling as HTMLElement).innerText = `${target.value}\n`;
+                    (target.nextSibling as HTMLElement).innerText =
+                        `${target.value}\n`;
                 }}
                 placeholder={placeholder}
                 ref={innerRef}
                 value={value}
+                wrap="hard"
             />
             <div aria-hidden data-replicated-value />
         </div>

package/src/TextareaField.tsx

@@ -3,13 +3,36 @@ import { TextareaProps, Textarea } from './Textarea';
 import { Txt } from './Txt';
 import { tryIntParse } from './utils/tryIntPsrse';
 
-export type TextareaFieldProps = Pick<FormFieldProps, 'controlId' | 'errorMessage' | 'helperText' | 'label'> &
+export type TextareaFieldProps = Pick<
+    FormFieldProps,
+    'controlId' | 'errorMessage' | 'helperText' | 'label'
+> &
     TextareaProps;
 /**
- * A component that allows users to input large amounts of text that could span multiple lines.
+ * A component that allows users to input large amounts of text that could span
+ * multiple lines.
  *
  * This component takes properties from the FormField and Textarea components.
  *
+ * @example
+ *     import { useState } from 'react';
+ *     import { TextareaField } from '@bspk/ui/TextareaField';
+ *
+ *     export function Example() {
+ *         const [value, setValue] = useState<string>();
+ *
+ *         return (
+ *             <TextareaField
+ *                 aria-label="Example aria-label"
+ *                 controlId="Example controlId"
+ *                 label="Example label"
+ *                 name="Example name"
+ *                 onChange={setValue}
+ *                 value={value}
+ *             />
+ *         );
+ *     }
+ *
  * @name TextareaField
  */
 function TextareaField({
@@ -26,7 +49,8 @@ function TextareaField({
     ...textareaProps
 }: TextareaFieldProps) {
     const maxLength = tryIntParse(maxLengthProp) || -1;
-    const errorMessage = (!readOnly && !disabled && errorMessageProp) || undefined;
+    const errorMessage =
+        (!readOnly && !disabled && errorMessageProp) || undefined;
 
     if (typeof onChange !== 'function') return null;
 
@@ -38,7 +62,12 @@ function TextareaField({
             helperText={helperText}
             label={label}
             labelTrailing={
-                <Txt style={{ color: 'var(--foreground-neutral-on-surface-variant-02)' }} variant="body-small">
+                <Txt
+                    style={{
+                        color: 'var(--foreground-neutral-on-surface-variant-02)',
+                    }}
+                    variant="body-small"
+                >
                     {`${textareaProps?.value?.length || 0}${maxLength > 0 ? `/${maxLength}` : ''}`}
                 </Txt>
             }

package/src/ToggleOption.tsx

@@ -3,17 +3,20 @@ import { ReactElement } from 'react';
 
 export type ToggleOptionProps = {
     /**
-     * The label of the field. Also used as the aria-label of the checkbox.
+     * The label of the option. Also used as the aria-label of the checkbox.
      *
      * @required
      */
     label: string;
-    /** The description of the field. */
+    /**
+     * The description of the option.
+     *
+     * @type multiline
+     * @type multiline
+     */
     description?: string;
     /** The control element to use. */
     children?: ReactElement;
-    /** The size of the control option label. */
-    size?: 'base' | 'large' | 'small';
 };
 
 /**
@@ -21,9 +24,9 @@ export type ToggleOptionProps = {
  *
  * @name ToggleOption
  */
-function ToggleOption({ label, description, children, size }: ToggleOptionProps) {
+function ToggleOption({ label, description, children }: ToggleOptionProps) {
     return (
-        <label data-bspk="toggle-option" data-size={size}>
+        <label data-bspk="toggle-option">
             <span data-control>{children}</span>
             <span data-content>
                 <span data-label>{label}</span>