@bspk/ui 1.1.21 → 1.1.23

package/src/Avatar.tsx

@@ -80,9 +80,25 @@ export type AvatarProps = {
 /**
  * An avatar is a visual representation of a user or entity. It can be used to display an initials, icon, image.
  *
- * The image if provided is displayed first, followed by the icon if provided, and finally the initials.
+ * @example
+ *     import { Avatar } from '@bspk/ui/Avatar';
+ *     import { SvgPerson } from '@bspk/icons/Person';
  *
- * If no initials are provided, the first two letters of the name will be used as initials.
+ *     function Example() {
+ *         return (
+ *             <Avatar
+ *                 name="Jane Doe"
+ *                 initials="JD"
+ *                 color="blue"
+ *                 size="large"
+ *                 icon={<SvgPerson />}
+ *                 image="/profile.jpg"
+ *                 showTooltip={true}
+ *             />
+ *         );
+ *     }
+ *
+ * @exampleDescription The image if provided is displayed first, followed by the icon if provided, and finally the initials. If no initials are provided, the first two letters of the name will be used as initials.
  *
  * @name Avatar
  */

package/src/AvatarGroup.tsx

@@ -43,6 +43,20 @@ export type AvatarGroupProps = {
 /**
  * AvatarGroup component displays a group of avatars.
  *
+ * @example
+ *     import { AvatarGroup } from '@bspk/ui/AvatarGroup';
+ *
+ *     export function Example() {
+ *         return (
+ *             <AvatarGroup
+ *                 items={[
+ *                     { name: 'Jane Doe', image: '/path/to/image.jpg' },
+ *                     { name: 'John Smith', initials: 'JS' },
+ *                 ]}
+ *             />
+ *         );
+ *     }
+ *
  * @name AvatarGroup
  */
 function AvatarGroup({ items, size = 'small', max = 5, variant }: AvatarGroupProps) {

package/src/Badge.tsx

@@ -1,3 +1,5 @@
+import { ReactNode } from 'react';
+
 import './badge.scss';
 import { tryIntParse } from './utils/tryIntPsrse';
 
@@ -6,9 +8,15 @@ export type BadgeProps = {
      * The content of the badge. If larger than 99, the badge will display '99+'. If null or undefined, the badge will
      * be hidden.
      *
+     * @example
+     *     5;
+     *
+     * @default 1
+     *
      * @type number
+     * @minimum 1
      */
-    count?: number | string | null | undefined;
+    count?: number;
     /**
      * The size of the badge.
      *
@@ -21,25 +29,70 @@ export type BadgeProps = {
      * @default primary
      */
     variant?: 'primary' | 'secondary';
+    /**
+     * Whether the badge should have a border that matches the surface color.
+     *
+     * @default false
+     */
+    surfaceBorder?: boolean;
+    /**
+     * The context for which the badge is applied.
+     *
+     * Could be a button, link, or any other element that the badge is associated with.
+     *
+     * @type
+     */
+    children?: ReactNode;
 };
 
 /**
  * Visual indicator for new items within a parent page represented with a numerical count of new items.
  *
+ * @example
+ *     import { Badge } from '@bspk/ui/badge';
+ *
+ *     function Example() {
+ *         return <Badge count={5} size="small" variant="primary" />;
+ *     }
+ *
+ * @exampleDescription This example shows a badge with a count of 5, size small, and primary variant.
+ *
  * @name Badge
  */
-function Badge({ count: countProp, size = 'small', variant = 'primary' }: BadgeProps) {
+function Badge({ count: countProp, size = 'small', variant = 'primary', surfaceBorder, children }: BadgeProps) {
     const count: number | null = tryIntParse(countProp);
 
-    return (
-        count !== null && (
-            <div data-bspk="badge" data-size={size} data-variant={variant}>
-                {count > 99 ? '99+' : count}
-            </div>
-        )
+    if (count === null) return;
+
+    const badge = (
+        <sup data-bspk="badge" data-size={size} data-surface-border={surfaceBorder || undefined} data-variant={variant}>
+            {count > 99 ? '99+' : count}
+        </sup>
     );
+
+    if (children) {
+        return (
+            <span data-bspk="badge-wrapper">
+                {children}
+                {badge}
+            </span>
+        );
+    }
+
+    return badge;
 }
 
+// position: relative;
+// display: -webkit-inline-box;
+// display: -webkit-inline-flex;
+// display: -ms-inline-flexbox;
+// display: inline-flex
+// ;
+// vertical-align: middle;
+// -webkit-flex-shrink: 0;
+// -ms-flex-negative: 0;
+// flex-shrink: 0;
+
 Badge.bspkName = 'Badge';
 
 export { Badge };

package/src/BannerAlert.tsx

@@ -51,6 +51,23 @@ export type BannerAlertProps = {
  * A visual and contextual message used to communicate an important message or notification to users relating to a
  * status or the body content of a page.
  *
+ * @example
+ *     import { BannerAlert } from '@bspk/ui/BannerAlert';
+ *
+ *     function Example() {
+ *         <BannerAlert
+ *             variant="error"
+ *             header="Error"
+ *             body="There was an error processing your request."
+ *             onClose={() => console.log('Alert closed')}
+ *         />;
+ *     }
+ *
+ * @exampleDescription This example shows how to use the BannerAlert component with an error variant, a header, and a body message.
+ *
+ *
+ *
+ *
  * @name BannerAlert
  */
 function BannerAlert({

package/src/Button.tsx

@@ -74,6 +74,22 @@ export type ButtonProps<As extends ElementType = 'button'> = CommonProps<'disabl
 /**
  * A clickable component that allows users to perform an action, make a choice or trigger a change in state.
  *
+ * @example
+ *     import { Button } from '@bspk/ui/Button';
+ *     import { SvgPerson } from '@bspk/icons/Person';
+ *
+ *     function Example() {
+ *         return (
+ *             <Button
+ *                 label="Click Me"
+ *                 size="medium"
+ *                 variant="primary"
+ *                 onClick={() => console.log('Button clicked')}
+ *                 icon={<SvgPerson />}
+ *             />
+ *         );
+ *     }
+ *
  * @name Button
  */
 function Button<As extends ElementType = 'button'>(props: ElementProps<ButtonProps<As>, As>): JSX.Element {

package/src/Card.tsx

@@ -29,6 +29,18 @@ export type CardProps = {
  * They are similar in size and shape to playing cards and are intended to encourage users to click or tap to view more
  * details.
  *
+ * @example
+ *     import { Card } from '@bspk/ui/card';
+ *
+ *     function Example() {
+ *         return (
+ *             <Card variant="elevated" showPadding={false}>
+ *                 <h3>Card Title</h3>
+ *                 <p>This is some content inside the card.</p>
+ *             </Card>
+ *         );
+ *     }
+ *
  * @name Card
  */
 function Card({ children, showPadding, variant = 'elevated' }: CardProps) {

package/src/Checkbox.tsx

@@ -32,6 +32,27 @@ export type CheckboxProps = CommonProps<'aria-label' | 'disabled' | 'name'> &
  * element and if used directly you must wrap it with a label. This will more often be used in the CheckboxOption or
  * CheckboxGroup component.
  *
+ * @example
+ *     import { Checkbox } from '@bspk/ui/Checkbox';
+ *
+ *     function Example() {
+ *         const [checked, setChecked] = React.useState(false);
+ *
+ *         return (
+ *             <label htmlFor="sample-checkbox">
+ *                 <Checkbox
+ *                     aria-label="Sample"
+ *                     checked={checked}
+ *                     id="sample-checkbox"
+ *                     name="sample-checkbox"
+ *                     onChange={(nextChecked) => setChecked(nextChecked)}
+ *                     value="sample"
+ *                 />
+ *                 Checkbox Label
+ *             </label>
+ *         );
+ *     }
+ *
  * @element
  *
  * @name Checkbox

package/src/CheckboxGroup.tsx

@@ -24,6 +24,13 @@ export type CheckboxGroupProps = CommonProps<'aria-label'> & {
     /**
      * The options for the checkboxes.
      *
+     * @example
+     *     [
+     *         { label: 'Option 1', value: 'option1' },
+     *         { label: 'Option 2', value: 'option2' },
+     *         { label: 'Option 3', value: 'option3' },
+     *     ];
+     *
      * @type Array<CheckboxGroupOption>
      * @required
      */
@@ -47,6 +54,29 @@ export type CheckboxGroupProps = CommonProps<'aria-label'> & {
 /**
  * A group of checkboxes that allows users to choose one or more items from a list or turn an feature on or off.
  *
+ * @example
+ *     import { CheckboxGroup } from '@bspk/ui/CheckboxGroup';
+ *
+ *     function Example() {
+ *         const [values, setValues] = React.useState<string[]>([]);
+ *
+ *         return (
+ *             <CheckboxGroup
+ *                 aria-label="Example Checkbox Group"
+ *                 name="example-checkbox-group"
+ *                 options={[
+ *                     { label: 'Option 1', value: 'option1' },
+ *                     { label: 'Option 2', value: 'option2' },
+ *                     { label: 'Option 3', value: 'option3' },
+ *                 ]}
+ *                 values={values}
+ *                 onChange={(nextValues: string[]) => {
+ *                     setValues(nextValues);
+ *                 }}
+ *             />
+ *         );
+ *     }
+ *
  * @name CheckboxGroup
  */
 function CheckboxGroup({

package/src/CheckboxOption.tsx

@@ -17,13 +17,38 @@ export type CheckboxOptionProps = InvalidPropsLibrary &
 /**
  * A control that allows users to choose one or more items from a list or turn an feature on or off.
  *
+ * If only a Checkbox is needed, consider using the `Checkbox` component directly.
+ *
+ * @example
+ *     import { CheckboxOption } from '@bspk/ui/CheckboxOption';
+ *
+ *     function Example() {
+ *         const [checked, setChecked] = React.useState(false);
+ *         return (
+ *             <CheckboxOption
+ *                 checked={checked}
+ *                 description="This is an example checkbox option."
+ *                 label="Example Checkbox"
+ *                 name="example-checkbox-name"
+ *                 onChange={(nextChecked, event) => {
+ *                     setChecked(nextChecked);
+ *                     console.log('Checkbox changed:', nextChecked, event);
+ *                 }}
+ *                 value="example-checkbox-value"
+ *             />
+ *         );
+ *     }
+ *
  * @name CheckboxOption
  */
-function CheckboxOption({ label, description, ...checkboxProps }: CheckboxOptionProps) {
+function CheckboxOption({ label: labelProp, description, ...checkboxProps }: CheckboxOptionProps) {
+    const label = labelProp || description;
     return (
-        <ToggleOption data-bspk="checkbox-option" description={description} label={label}>
-            <Checkbox {...checkboxProps} aria-label={label} />
-        </ToggleOption>
+        label && (
+            <ToggleOption data-bspk="checkbox-option" description={description} label={label}>
+                <Checkbox {...checkboxProps} aria-label={label} />
+            </ToggleOption>
+        )
     );
 }
 

package/src/Chip.tsx

@@ -46,6 +46,17 @@ export type ChipProps = CommonProps<'disabled'> & {
 /**
  * Dynamically generated options that are suggested to the user as responses or prompts.
  *
+ * @example
+ *     import { Chip } from '@bspk/ui/Chip';
+ *
+ *     function Example() {
+ *         return (
+ *             <Chip variant="filter" onClick={() => console.log('Chip clicked!')}>
+ *                 Example Chip
+ *             </Chip>
+ *         );
+ *     }
+ *
  * @name Chip
  */
 function Chip({

package/src/Dialog.tsx

@@ -44,6 +44,25 @@ export type DialogProps = CommonProps<'id'> & {
  * Dialogs display important information that users need to acknowledge. They appear over the interface and block
  * further interactions until an action is selected.
  *
+ * @example
+ *     import { Dialog } from '@bspk/ui/Dialog';
+ *     import { Button } from '@bspk/ui/Button';
+ *
+ *     function Example() {
+ *         const [open, setOpen] = React.useState(false);
+ *
+ *         return (
+ *             <>
+ *                 <Button label="Open Dialog" onClick={() => setOpen(true)} />
+ *                 <Dialog open={open} onClose={() => setOpen(false)}>
+ *                     <h1>Dialog Title</h1>
+ *                     <p>This is the content of the dialog.</p>
+ *                     <button onClick={() => setOpen(false)}>Close</button>
+ *                 </Dialog>
+ *             </>
+ *         );
+ *     }
+ *
  * @name Dialog
  */
 function Dialog({

package/src/Divider.tsx

@@ -42,6 +42,19 @@ const insetToVariable = (insetProp: number | string) => {
  *
  * Vertical thin lines that separates grouped content or other visual elements within a container.
  *
+ * @example
+ *     import { Divider } from '@bspk/ui/Divider';
+ *
+ *     function Example() {
+ *         return (
+ *             <div>
+ *                 <p>Content above the divider</p>
+ *                 <Divider orientation="horizontal" />
+ *                 <p>Content below the divider</p>
+ *             </div>
+ *         );
+ *     }
+ *
  * @name Divider
  */
 function Divider({

package/src/Dropdown.tsx

@@ -74,6 +74,36 @@ export type DropdownProps<T extends DropdownOption = DropdownOption> = CommonPro
 /**
  * A field element that allows users to select one option from a list of available choices. *
  *
+ * @example
+ *     import { Dropdown } from '@bspk/ui/Dropdown';
+ *
+ *     export function Example() {
+ *         const [selected, setSelected] = React.useState<string[]>([]);
+ *         return (
+ *             <Dropdown
+ *                 aria-label="Select an option"
+ *                 itemCount={5}
+ *                 name="example-dropdown"
+ *                 onChange={setSelected}
+ *                 options={[
+ *                     { value: '1', label: 'Option 1' },
+ *                     { value: '2', label: 'Option 2' },
+ *                     { value: '3', label: 'Option 3' },
+ *                     { value: '4', label: 'Option 4' },
+ *                     { value: '5', label: 'Option 5' },
+ *                     { value: '6', label: 'Option 6' },
+ *                     { value: '7', label: 'Option 7' },
+ *                     { value: '8', label: 'Option 8' },
+ *                     { value: '9', label: 'Option 9' },
+ *                     { value: '10', label: 'Option 10' },
+ *                 ]}
+ *                 placeholder="Select an option"
+ *                 size="medium"
+ *                 value={selected}
+ *             />
+ *         );
+ *     }
+ *
  * @name Dropdown
  */
 function Dropdown({

package/src/DropdownField.tsx

@@ -21,6 +21,28 @@ export type DropdownFieldProps = Pick<
  *
  * This component takes properties from the FormField and Dropdown components.
  *
+ * @example
+ *     import { DropdownField } from '@bspk/ui/DropdownField';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState(['option1']);
+ *         return (
+ *             <DropdownField
+ *                 controlId="Example controlId"
+ *                 label="Example label"
+ *                 name="Example name"
+ *                 onChange={(nextValue) => setState(nextValue)}
+ *                 options={[
+ *                     { label: 'Option 1', value: 'option1' },
+ *                     { label: 'Option 2', value: 'option2' },
+ *                     { label: 'Option 3', value: 'option3' },
+ *                 ]}
+ *                 placeholder="Select one..."
+ *                 value={state}
+ *             />
+ *         );
+ *     }
+ *
  * @name DropdownField
  */
 function DropdownField({

package/src/EmptyState.tsx

@@ -38,6 +38,17 @@ export type EmptyStateProps = {
 /**
  * A design pattern component that indicates to users that system has no content to display.
  *
+ * @example
+ *     import { EmptyState } from '@bspk/ui/EmptyState';
+ *
+ *     export function Example() {
+ *         return (
+ *             <EmptyState body="Example body" header="Example header">
+ *                 Example EmptyState
+ *             </EmptyState>
+ *         );
+ *     }
+ *
  * @name EmptyState
  */
 function EmptyState({ children, header, body, callToAction, bodyAlign = 'center' }: EmptyStateProps) {

package/src/Fab.tsx

@@ -45,6 +45,14 @@ export type FabProps<As extends ElementType = 'button'> = Pick<
  * A button that highlights a primary action that is elevated above the body content of a page; normally fixed to the
  * bottom right of a screen.
  *
+ * @example
+ *     import { SvgBolt } from '@bspk/icons/Bolt';
+ *     import { Fab } from '@bspk/ui/Fab';
+ *
+ *     export function Example() {
+ *         return <Fab icon={<SvgBolt />} label="Example label" placement="bottom-right" variant="neutral" />;
+ *     }
+ *
  * @name Fab
  */
 function Fab<As extends ElementType = 'button'>({

package/src/FormField.tsx

@@ -47,6 +47,31 @@ export type FormFieldProps = CommonProps<'required'> &
  *
  * Children may be one of the following: TextInput, Dropdown, DatePicker, or TimePicker.
  *
+ * @example
+ *     import { TextInput } from '@bspk/ui/TextInput';
+ *     import { FormField } from '@bspk/ui/FormField';
+ *
+ *     export function Example() {
+ *         const [state, setState] = React.useState<string | undefined>(undefined);
+ *         return (
+ *             <FormField controlId="Example controlId" label="Example label">
+ *                 {(fieldProps) => {
+ *                     return (
+ *                         <TextInput
+ *                             aria-label="example aria-label"
+ *                             name="example-text"
+ *                             onChange={(next) => {
+ *                                 setState(next);
+ *                             }}
+ *                             value={state}
+ *                             {...fieldProps}
+ *                         />
+ *                     );
+ *                 }}
+ *             </FormField>
+ *         );
+ *     }
+ *
  * @name FormField
  */
 function FormField({

package/src/Img.tsx

@@ -18,6 +18,13 @@ export type ImgProps = {
 /**
  * The Img component is used to display images on the page.
  *
+ * @example
+ *     import { Img } from '@bspk/ui/Img';
+ *
+ *     export function Example() {
+ *         return <Img alt="Example alt" src="Example src" />;
+ *     }
+ *
  * @name Img
  */
 function Img({ alt, ...props }: ElementProps<ImgProps, 'img'>) {

package/src/InlineAlert.tsx

@@ -30,6 +30,13 @@ export type InlineAlertProps = {
  * Inline alerts provide contextual feedback messages for typical user actions with a handful of available and flexible
  * alert messages.
  *
+ * @example
+ *     import { InlineAlert } from '@bspk/ui/InlineAlert';
+ *
+ *     export function Example() {
+ *         return <InlineAlert variant="informational">Example informational inline alert</InlineAlert>;
+ *     }
+ *
  * @name InlineAlert
  */
 function InlineAlert({ children, variant = 'informational', id }: InlineAlertProps) {

package/src/Layout.tsx

@@ -41,6 +41,13 @@ export type LayoutProps<As extends ElementType = 'div'> = {
 /**
  * Utility component used within other components for layout purposes.
  *
+ * @example
+ *     import { Layout } from '@bspk/ui/Layout';
+ *
+ *     export function Example() {
+ *         return <Layout>Low effort example</Layout>;
+ *     }
+ *
  * @name Layout
  */
 function Layout<As extends ElementType = 'div'>({