@bspk/ui 1.3.8 → 1.3.10

package/src/components/Layout/Layout.tsx

@@ -44,9 +44,7 @@ export type LayoutProps<As extends ElementType = ElementType> = {
  * @example
  *     import { Layout } from '@bspk/ui/Layout';
  *
- *     function Example() {
- *         return <Layout>Low effort example</Layout>;
- *     }
+ *     <Layout>Low effort example</Layout>;
  *
  * @name Layout
  * @phase Utility

package/src/components/Link/Link.tsx

@@ -46,9 +46,7 @@ export type LinkProps = Pick<CommonPropsLibrary, 'disabled'> & {
  * @example
  *     import { Link } from '@bspk/ui/Link';
  *
- *     function Example() {
- *         return <Link href="https://bspk.dev" label="Example label" trailingIcon="external" />;
- *     }
+ *     <Link href="https://anywhere.re" label="Example label" trailingIcon="external" />;
  *
  * @name Link
  * @phase UXReview

package/src/components/ListItem/ListItem.tsx

@@ -9,7 +9,6 @@ import {
     AriaRole,
     ComponentProps,
 } from 'react';
-import { ListItemButton } from './ListItemButton';
 import { Truncated } from '-/components/Truncated';
 import { useId } from '-/hooks/useId';
 import { CommonProps, ElementProps, SetRef } from '-/types/common';
@@ -47,11 +46,11 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<'a
         /**
          * The trailing element to display in the ListItem.
          *
-         * Trailing elements should only be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio,
-         * Switch, Tag, Txt.
+         * Trailing elements should only be one of the following [Icon](/icons), Checkbox, Button, Radio, Switch, Tag,
+         * Txt.
          *
          * @exampleType select
-         * @options Checkbox, Icon, ListItemButton, Radio, Switch, Tag, Txt
+         * @options Checkbox, Icon, Button, Radio, Switch, Tag, Txt
          */
         trailing?: ReactNode;
         /** Props to pass to the trailing element wrapper span. */
@@ -109,24 +108,29 @@ export type ListItemProps<As extends ElementType = ElementType> = CommonProps<'a
  *
  * Leading elements should be one of the following [Icon](/icons), Img, Avatar.
  *
- * Trailing elements should be one of the following [Icon](/icons), Checkbox, ListItemButton, Radio, Switch, Tag, Txt.
- *
- * The ListItemButton is a more limited Button with context specific options.
+ * Trailing elements should be one of the following [Icon](/icons), Checkbox, Button, Radio, Switch, Tag, Txt.
  *
  * @example
- *     import { SvgSquare } from '@bspk/icons/Square';
+ *     import { SvgFolder } from '@bspk/icons/Folder';
+ *     import { SvgChevronRight } from '@bspk/icons/ChevronRight';
  *     import { ListItem } from '@bspk/ui/ListItem';
  *
- *     function Example() {
- *         return (
- *             <ListItem
- *                 label="Example label"
- *                 leading={<SvgSquare />}
- *                 subText="Example subtest"
- *                 trailing={<ListItem.Button label="Click me" onClick={() => console.log('Hello world')} />}
- *             />
- *         );
- *     }
+ *     <div style={{ width: 300 }}>
+ *         <ListItem
+ *             leading={<SvgDelete />}
+ *             label="File 13"
+ *             subText="Last modified: Jan 21, 2024"
+ *             trailing={<SvgChevronRight />}
+ *             onClick={() => sendSnackbar('Clicked Open Folder button')}
+ *         />
+ *         <ListItem
+ *             leading={<SvgFolder />}
+ *             label="Death Star Plans"
+ *             subText="Last modified: May 25, 1977"
+ *             trailing={<SvgChevronRight />}
+ *             onClick={() => sendSnackbar('Downloading blueprints...')}
+ *         />
+ *     </div>;
  *
  * @name ListItem
  * @phase UXReview
@@ -201,8 +205,6 @@ function ListItem<As extends ElementType = ElementType>({
     );
 }
 
-ListItem.Button = ListItemButton;
-
 export { ListItem };
 
 function asLogic<As extends ElementType>(as: As | undefined, props: Partial<ListItemProps>): ElementType {

package/src/components/Menu/Menu.tsx

@@ -46,15 +46,11 @@ export type MenuProps<As extends ElementType = ElementType> = CommonProps<'id' |
  *
  *     import { Menu } from '@bspk/ui/Menu';
  *
- *     function Example() {
- *         return (
- *             <Menu>
- *                 <ListItem label="List Item" />
- *                 <ListItem label="List Item" />
- *                 <ListItem label="List Item" />
- *             </Menu>
- *         );
- *     }
+ *     <Menu>
+ *         <ListItem label="List Item" />
+ *         <ListItem label="List Item" />
+ *         <ListItem label="List Item" />
+ *     </Menu>;
  *
  * @name Menu
  * @phase UXReview

package/src/components/Modal/Modal.tsx

@@ -87,7 +87,7 @@ export type ModalProps = Pick<
      */
     callToAction?: ModalCallToAction;
     /**
-     * The format of the buttons in the footer. Ignored if not mobile.
+     * The format of the buttons in the footer. Vertical applies only on screen widths less than or equal to 640px.
      *
      * @default horizontal
      */
@@ -114,8 +114,8 @@ export type ModalProps = Pick<
  *     import { Button } from '@bspk/ui/Button';
  *     import { Modal } from '@bspk/ui/Modal';
  *
- *     function Example() {
- *         const [open, setOpen] = React.useState(false);
+ *     () => {
+ *         const [open, setOpen] = useState(false);
  *
  *         return (
  *             <>
@@ -130,7 +130,7 @@ export type ModalProps = Pick<
  *                 </Modal>
  *             </>
  *         );
- *     }
+ *     };
  *
  * @name Modal
  * @phase UXReview
@@ -200,7 +200,12 @@ export function Modal({
                 {Array.isArray(buttons) && buttons.length > 0 && (
                     <div data-button-format={buttonFormat} data-modal-footer>
                         {buttons.map((buttonProps, idx) => (
-                            <Button key={idx} {...buttonProps} size={isMobile ? 'medium' : 'small'} />
+                            <Button
+                                key={idx}
+                                {...buttonProps}
+                                size={isMobile ? 'medium' : 'small'}
+                                width={buttonFormat === 'vertical' && isMobile ? 'fill' : 'hug'}
+                            />
                         ))}
                     </div>
                 )}

package/src/components/Modal/modal.scss

@@ -25,9 +25,21 @@
 
     > [data-modal-footer] {
         display: flex;
+        gap: var(--spacing-sizing-04);
+    }
+
+    [data-button-format='horizontal'] {
         flex-direction: row-reverse;
         justify-content: flex-start;
-        gap: var(--spacing-sizing-04);
+    }
+
+    [data-button-format='vertical'] {
+        flex-direction: column;
+
+        @media (width >= 640px) {
+            flex-direction: row-reverse;
+            justify-content: flex-start;
+        }
     }
 }
 

package/src/components/OTPInput/OTPInput.tsx

@@ -34,9 +34,11 @@ export type OTPInputProps = CommonProps<'id' | 'invalid' | 'name' | 'size'> & {
  * @example
  *     import { OTPInput } from '@bspk/ui/OTPInput';
  *
- *     function Example() {
- *         return <OTPInput name="2-auth-otp" length={4} value={otpValue} onChange={setOtpValue} />;
- *     }
+ *     () => {
+ *         const [otpValue, setOtpValue] = useState('');
+ *
+ *         <OTPInput name="2-auth" length={4} value={otpValue} onChange={setOtpValue} />;
+ *     };
  *
  * @name OTPInput
  * @phase UXReview

package/src/components/PageControl/PageControl.tsx

@@ -40,9 +40,7 @@ export type DotSize = 'medium' | 'small' | 'x-small';
  * @example
  *     import { PageControl } from '@bspk/ui/PageControl';
  *
- *     function Example() {
- *         return <PageControl value={1} numPages={3} />;
- *     }
+ *     <PageControl value={1} numPages={3} />;
  *
  * @name PageControl
  * @phase UXReview

package/src/components/Pagination/PageList.tsx

@@ -3,6 +3,12 @@ import { Button } from '-/components/Button';
 
 export type PageListProps = Pick<PaginationProps, 'numPages' | 'onChange' | 'value'>;
 
+/**
+ * PageList component displays a list of page buttons for pagination.
+ *
+ * @name PageList
+ * @parent Pagination
+ */
 export function PageList({ numPages, onChange, value }: PageListProps) {
     return Array.from({ length: numPages }, (_, index) => {
         const page = index + 1;

package/src/components/Pagination/Pagination.tsx

@@ -1,9 +1,9 @@
 import './pagination.scss';
 import { SvgIcon } from '@bspk/icons/SvgIcon';
-import { AriaAttributes } from 'react';
-import { PageInput } from './PageInput';
+import { AriaAttributes, useEffect, useState } from 'react';
 import { PageList } from './PageList';
 import { Button } from '-/components/Button';
+import { InputElement } from '-/components/Input';
 
 // After this point the manual input renders. With equal or fewer pages the individual page buttons render instead.
 const INPUT_TYPE_THRESHOLD = 7;
@@ -12,7 +12,9 @@ export type PaginationProps = {
     /**
      * The number of pages to display in the pagination component.
      *
-     * @default 1
+     * If there is only one page, the component will not render.
+     *
+     * @default 2
      */
     numPages: number;
     /**
@@ -32,14 +34,11 @@ export type PaginationProps = {
  *
  * @example
  *     import { Pagination } from '@bspk/ui/Pagination';
- *     import { usePaginationState } from '@bspk/ui/hooks/usePaginationState';
  *
  *     function Example() {
- *         const numPages = 10;
- *
- *         const { currentPage, setCurrentPage } = usePaginationState(numPages);
+ *         const [currentPage, setCurrentPage] = useState(1);
  *
- *         return <Pagination value={currentPage} onChange={setCurrentPage} numPages={numPages} />;
+ *         return <Pagination value={currentPage} onChange={setCurrentPage} numPages={10} />;
  *     }
  *
  * @name Pagination
@@ -47,46 +46,73 @@ export type PaginationProps = {
  */
 export function Pagination({ numPages, value, onChange, ...ariaProps }: AriaAttributes & PaginationProps) {
     const nextPage = () => {
-        if (value < numPages) {
-            onChange(value + 1);
-        }
+        if (value < numPages) onChange(value + 1);
     };
 
     const previousPage = () => {
-        if (value > 1) {
-            onChange(value - 1);
-        }
+        if (value > 1) onChange(value - 1);
     };
 
-    const isFirstPage = value === 1;
-    const isLastPage = value === numPages;
-    const isOutOfBoundsValue = value < 1 || value > numPages;
-    const isOneOrFewerPages = numPages <= 1;
+    const [inputValue, setInputValue] = useState<string | undefined>(`${value}`);
+
+    useEffect(() => setInputValue(`${value}`), [value]);
+
+    const submitInputChange = () => {
+        const parsedValue = parseInt(inputValue || '', 10);
+        if (isNaN(parsedValue)) return setInputValue(`${value}`);
+
+        let next = parsedValue;
+        if (parsedValue < 1) next = 1;
+        if (parsedValue > numPages) next = numPages;
+
+        onChange(next);
+        if (next !== parsedValue) setInputValue(`${next}`);
+    };
+
+    const inBounds = (n: number) => n >= 1 && n <= numPages;
+
+    if (numPages <= 1) return null;
 
     return (
         <span data-bspk="pagination" role="group" {...ariaProps}>
             <Button
-                disabled={isOutOfBoundsValue || isOneOrFewerPages || isFirstPage}
+                disabled={!inBounds(value - 1)}
                 icon={<SvgIcon name="ChevronLeft" />}
                 iconOnly
-                label={isFirstPage ? 'First page' : `Previous page (${value - 1})`}
+                label={value === 1 ? 'First page' : `Previous page (${value - 1})`}
                 onClick={previousPage}
                 owner="pagination"
                 size="small"
                 variant="tertiary"
             />
-
             {numPages > INPUT_TYPE_THRESHOLD ? (
-                <PageInput numPages={numPages} onChange={onChange} value={value} />
+                <form
+                    data-input-form
+                    onSubmit={(e) => {
+                        e.preventDefault();
+                        submitInputChange();
+                    }}
+                >
+                    <InputElement
+                        name="page-number"
+                        onBlur={() => submitInputChange()}
+                        onChange={setInputValue}
+                        owner="pagination"
+                        showClearButton={false}
+                        type="number"
+                        value={inputValue}
+                    />
+                    of {numPages}
+                </form>
             ) : (
                 <PageList numPages={numPages} onChange={onChange} value={value} />
             )}
 
             <Button
-                disabled={isOutOfBoundsValue || isOneOrFewerPages || isLastPage}
+                disabled={!inBounds(value + 1)}
                 icon={<SvgIcon name="ChevronRight" />}
                 iconOnly
-                label={isLastPage ? 'Last page' : `Next page (${value + 1})`}
+                label={value === numPages ? 'Last page' : `Next page (${value + 1})`}
                 onClick={nextPage}
                 owner="pagination"
                 size="small"

package/src/components/Pagination/pagination.scss

@@ -6,25 +6,15 @@
     gap: var(--spacing-sizing-01);
     flex: 1;
 
-    [data-bspk='page-input'] {
-        display: flex;
-        flex-direction: row;
-        align-items: center;
-        justify-content: center;
-        gap: var(--spacing-sizing-01);
-
-        [data-bspk='txt'] {
-            color: var(--foreground-neutral-on-surface-variant-02);
-            text-wrap: nowrap;
-        }
+    [data-input-form] {
+        display: contents;
+    }
 
-        [data-bspk='text-input'] {
-            width: var(--spacing-sizing-12);
+    [data-bspk='input'] {
+        max-width: var(--spacing-sizing-12);
 
-            input {
-                text-align: center;
-                flex: 1;
-            }
+        input {
+            text-align: center;
         }
     }
 

package/src/components/Password/Password.tsx

@@ -16,30 +16,29 @@ export type PasswordProps = FieldControlProps & Pick<InputProps, 'containerRef'
  *     import { Password } from '@bspk/ui/Password';
  *     import { useState } from 'react';
  *
- *     function ExampleStandalone() {
+ *     () => {
  *         const [value, setValue] = useState('');
  *
  *         return (
- *             <Password
- *                 aria-label="Enter password"
- *                 value={value}
- *                 onChange={setValue}
- *                 aria-label="password"
- *                 name="password"
- *             />
+ *             <>
+ *                 // standalone password example
+ *                 <Password
+ *                     aria-label="Enter password"
+ *                     value={value}
+ *                     onChange={setValue}
+ *                     aria-label="password"
+ *                     name="password"
+ *                 />
+ *                 <br />
+ *                 // password used within a field
+ *                 <Field>
+ *                     <FieldLabel>Password</FieldLabel>
+ *                     <Password value={value} onChange={setValue} aria-label="password" name="password" />
+ *                     <FieldDescription>The password field allows you to enter a secure password.</FieldDescription>
+ *                 </Field>
+ *             </>
  *         );
- *     }
- *
- *     function ExampleWithField() {
- *         const [value, setValue] = useState('');
- *         return (
- *             <Field>
- *                 <FieldLabel>Password</FieldLabel>
- *                 <Password value={value} onChange={setValue} aria-label="password" name="password" />
- *                 <FieldDescription>The password field allows you to enter a secure password.</FieldDescription>
- *             </Field>
- *         );
- *     }
+ *     };
  *
  * @name Password
  * @phase UXReview

package/src/components/Popover/Popover.tsx

@@ -60,26 +60,17 @@ export type PopoverProps = CommonProps<'disabled'> &
  *     import { Popover } from '@bspk/ui/Popover';
  *     import { Button } from '@bspk/ui/Button';
  *
- *     function Example() {
- *         const [showPopover, setShowPopover] = useState<boolean>(false);
- *
- *         const togglePopover = () => setShowPopover(!showPopover);
- *         const onPopoverCallToActionClick = () => alert('Action clicked');
- *
- *         return (
- *             <Popover
- *                 placement="bottom"
- *                 content="This is a popover content"
- *                 header="Popover Header"
- *                 callToAction={{
- *                     label: 'Action',
- *                     onClick: onPopoverCallToActionClick,
- *                 }}
- *             >
- *                 <Button label="Toggle popover" onClick={togglePopover} />
- *             </Popover>
- *         );
- *     }
+ *     <Popover
+ *         placement="bottom"
+ *         content="This is a popover content"
+ *         header="Popover Header"
+ *         callToAction={{
+ *             label: 'Action',
+ *             onClick: () => action('Action clicked'),
+ *         }}
+ *     >
+ *         {(triggerProps) => <Button {...triggerProps} label="Toggle popover" />}
+ *     </Popover>;
  *
  * @name Popover
  * @phase UXReview

package/src/components/Popover/PopoverExample.tsx

@@ -8,7 +8,7 @@ export const PopoverExample: ComponentExampleFn<PopoverProps> = ({ action }) =>
     render: ({ props, Component }) => {
         return (
             <>
-                <Txt style={{ marginBottom: `var(--spacing-sizing-02)` }}>Click button for a Popover</Txt>
+                <Txt style={{ marginBottom: `var(--spacing-sizing-02)` }}>Click for a Popover</Txt>
                 <Component {...props}>
                     {(triggerProps) => <Button label={`${props.placement}`} variant="secondary" {...triggerProps} />}
                 </Component>

package/src/components/ProgressBar/ProgressBar.tsx

@@ -53,9 +53,7 @@ export type ProgressBarProps = {
  * @example
  *     import { ProgressBar } from '@bspk/ui/ProgressBar';
  *
- *     function Example() {
- *         return <ProgressBar label="Example label" completion={50} />;
- *     }
+ *     <ProgressBar label="Example label" completion={50} />;
  *
  * @name ProgressBar
  * @phase UXReview

package/src/components/ProgressCircle/ProgressCircle.tsx

@@ -27,9 +27,7 @@ export type ProgressCircleProps = {
  * @example
  *     import { ProgressCircle } from '@bspk/ui/ProgressCircle';
  *
- *     function Example() {
- *         return <ProgressCircle label="Example label" />;
- *     }
+ *     <ProgressCircle label="Example label" />;
  *
  * @name ProgressCircle
  * @phase UXReview

package/src/components/ProgressionStepper/ProgressionStepper.tsx

@@ -59,9 +59,7 @@ export type ProgressionStepperProps = {
  * @example
  *     import { ProgressionStepper } from '@bspk/ui/ProgressionStepper';
  *
- *     function Example() {
- *         return <ProgressionStepper steps={[{ name: 'Step 1' }, { name: 'Step 2' }, { name: 'Step 3' }]} />;
- *     }
+ *     <ProgressionStepper steps={[{ name: 'Step 1' }, { name: 'Step 2' }, { name: 'Step 3' }]} />;
  *
  * @name ProgressionStepper
  * @phase UXReview

package/src/components/RadioGroup/RadioGroup.tsx

@@ -40,7 +40,7 @@ export type RadioGroupProps = Omit<FieldControlProps, 'readOnly'> & {
  *     import { useState } from 'react';
  *     import { RadioGroup } from '@bspk/ui/RadioGroup';
  *
- *     function Example() {
+ *     () => {
  *         const [selectedOption, setSelectedOption] = useState<string>('1');
  *
  *         return (
@@ -59,7 +59,7 @@ export type RadioGroupProps = Omit<FieldControlProps, 'readOnly'> & {
  *                 value={selectedOption}
  *             />
  *         );
- *     }
+ *     };
  *
  * @name RadioGroup
  * @phase UXReview

package/src/components/Rating/Rating.tsx

@@ -1,6 +1,5 @@
 import './rating.scss';
 import { SvgStarFill } from '@bspk/icons/StarFill';
-import { ElementType } from 'react';
 
 export type RatingSize = 'large' | 'medium' | 'small';
 export type RatingProps = {
@@ -12,7 +11,7 @@ export type RatingProps = {
      */
     value?: number;
     /**
-     * If included the component is in interactive mode and this callback is fired when a star is selected.
+     * If included the component is interactive and this callback is fired when the user selects a new rating value.
      *
      * @param value - The new value of the rating.
      */
@@ -39,37 +38,58 @@ const iconWidths: Record<RatingSize, number> = {
  * @example
  *     import { Rating } from '@bspk/ui/Rating';
  *
- *     function Example() {
- *         return <Rating value={4.5} />;
- *     }
+ *     <Rating value={4.5} size="large" />;
  *
  * @name Rating
  * @phase UXReview
  */
 export function Rating({ size = 'medium', value, onChange }: RatingProps) {
-    const As: ElementType = onChange ? 'button' : 'div';
+    if (!onChange)
+        return (
+            <div
+                aria-label={value ? `${value} out of ${MAX_STARS} stars` : 'Rating'}
+                data-bspk="rating"
+                data-size={size}
+                role="img"
+            >
+                {Array.from({ length: MAX_STARS }, (_, index) => {
+                    const fill = getFill(index + 1, value);
+                    return (
+                        <div data-fill={fill} data-star key={index} role="presentation" tabIndex={-1}>
+                            <SvgStarFill width={iconWidths[size]} />
+                            {fill === 'half' && (
+                                <div data-fill-half>
+                                    <div data-star>
+                                        <SvgStarFill width={iconWidths[size]} />
+                                    </div>
+                                </div>
+                            )}
+                        </div>
+                    );
+                })}
+            </div>
+        );
 
     return (
         <div
-            aria-label={onChange ? 'Select a star rating' : value ? `${value} out of ${MAX_STARS} stars` : 'Rating'}
+            aria-label={value ? `${value} out of ${MAX_STARS} stars` : 'Select a star rating'}
             data-bspk="rating"
             data-size={size}
-            role={onChange ? 'radiogroup' : 'img'}
+            role="radiogroup"
         >
             {Array.from({ length: MAX_STARS }, (_, index) => {
                 const fill = getFill(index + 1, value);
                 const selected = value !== undefined && Math.floor(value) === index;
                 return (
-                    <As
+                    <button
                         aria-checked={selected}
-                        aria-hidden={!onChange}
-                        aria-label={onChange ? `Rate ${index + 1}` : undefined}
+                        aria-label={`Rate ${index + 1}`}
                         data-fill={fill}
                         data-star
                         key={index}
                         onClick={() => onChange?.(index + 1)}
-                        role={onChange ? 'radio' : 'presentation'}
-                        tabIndex={onChange ? (selected ? 0 : -1) : -1}
+                        role="radio"
+                        tabIndex={selected ? 0 : -1}
                         type="button"
                     >
                         <SvgStarFill width={iconWidths[size]} />
@@ -80,7 +100,7 @@ export function Rating({ size = 'medium', value, onChange }: RatingProps) {
                                 </div>
                             </div>
                         )}
-                    </As>
+                    </button>
                 );
             })}
         </div>