@commercetools/nimbus 0.0.9-rc8 → 0.0.10

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { AriaButtonProps } from 'react-aria';
 import { AriaCheckboxProps } from 'react-aria';
 import { AriaLinkOptions } from 'react-aria';
 import { AriaNumberFieldProps } from 'react-aria';
+import { AriaProgressBarProps } from 'react-aria';
 import { AriaToggleButtonGroupProps } from 'react-aria';
 import { AriaToggleButtonProps } from 'react-aria';
 import { AutocompleteProps } from 'react-aria-components';
@@ -74,6 +75,7 @@ import { SelectOptionProps as SelectOptionProps_2 } from './select.types';
 import { SelectOptionsProps as SelectOptionsProps_2 } from './select.types';
 import { SelectProps } from 'react-aria-components';
 import { SelectRootProps as SelectRootProps_2 } from './select.types';
+import { SeparatorProps } from 'react-aria';
 import { SetStateAction } from 'react';
 import { SimpleGridProps as SimpleGridProps_2 } from '@chakra-ui/react';
 import { SlotRecipeDefinition } from '@chakra-ui/react';
@@ -799,7 +801,7 @@ declare type CheckboxVariantProps = CheckboxRootProps & RecipeVariantProps<typeo
  */
 export declare const Code: ForwardRefExoticComponent<CodeProps & RefAttributes<HTMLElement>>;
 
-declare interface ColorModeProviderProps extends ThemeProviderProps {
+export declare interface ColorModeProviderProps extends ThemeProviderProps {
 }
 
 export declare const ComboBox: {
@@ -1255,6 +1257,84 @@ export declare type DisclosureItemProps = AccordionItemProps & {
     onExpandedChange?: (isExpanded: boolean) => void;
 };
 
+/**
+ * Divider
+ * ============================================================
+ * A visual separator that divides content sections
+ *
+ * Features:
+ *
+ * - allows forwarding refs to the underlying DOM element
+ * - accepts all native html 'HTMLDivElement' attributes (including aria- & data-attributes)
+ * - supports 'variants', 'orientation', etc. configured in the recipe
+ * - allows overriding styles by using style-props
+ * - supports 'asChild' and 'as' to modify the underlying html-element (polymorphic)
+ * - built with React Aria for accessibility
+ */
+export declare const Divider: {
+    (props: DividerProps): JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Main props interface for the Divider component.
+ * Extends DividerVariantProps to include both root props and variant props,
+ * while adding support for React Aria separator props.
+ */
+export declare interface DividerProps extends Omit<DividerVariantProps, "orientation">, Pick<SeparatorProps, "orientation"> {
+    /** The orientation of the divider */
+    orientation?: "horizontal" | "vertical";
+    /** Reference to the divider element */
+    ref?: React.Ref<HTMLDivElement>;
+}
+
+/**
+ * Recipe configuration for the Divider component.
+ * Defines the styling variants and base styles using Chakra UI's recipe system.
+ */
+declare const dividerRecipe: RecipeDefinition<    {
+    orientation: {
+        horizontal: {
+            width: "100%";
+            height: "1px";
+            borderTopWidth: "1px";
+            borderTopStyle: "solid";
+            borderLeftWidth: "0";
+        };
+        vertical: {
+            height: "100%";
+            width: "1px";
+            borderLeftWidth: "1px";
+            borderLeftStyle: "solid";
+            borderTopWidth: "0";
+        };
+    };
+}>;
+
+/**
+ * Base recipe props interface that combines Chakra UI's recipe props
+ * with the unstyled prop option for the div element.
+ */
+export declare interface DividerRecipeProps extends RecipeProps<"div">, UnstyledProp {
+}
+
+/**
+ * Root props interface that extends Chakra's HTML props with our recipe props.
+ * This creates a complete set of props for the root element, combining
+ * HTML attributes, Chakra's styling system, and our custom recipe props.
+ */
+export declare interface DividerRootProps extends HTMLChakraProps<"div", DividerRecipeProps> {
+}
+
+/**
+ * Combines the root props with Chakra UI's recipe variant props.
+ * This allows the component to accept both structural props from Root
+ * and styling variants from the recipe.
+ */
+declare type DividerVariantProps = DividerRootProps & RecipeVariantProps<typeof dividerRecipe> & {
+    [key: `data-${string}`]: unknown;
+};
+
 declare type ExcludedNumberInputProps = "asChild" | "onChange";
 
 /**
@@ -1281,6 +1361,12 @@ declare type ExcludedProps_3 = "as" | "asChild" | "style" | "createCalendar";
  */
 declare type ExcludedProps_4 = "validationState" | "label" | "description" | "errorMessage" | "css" | "colorScheme" | "unstyled" | "recipe" | "as" | "asChild";
 
+/**
+ * Additional properties we want to exclude from the ProgressBar component.
+ * These are chakra-ui props we don't want exposed.
+ */
+declare type ExcludedProps_5 = "css" | "unstyled" | "as" | "asChild";
+
 /**
  * List of props that should be excluded from the root props when combining with ARIA props
  */
@@ -1844,9 +1930,82 @@ declare interface MultilineTextInputRecipeProps extends RecipeVariantProps<typeo
 
 declare type MultilineTextInputRootSlotProps = HTMLChakraProps<"textarea", MultilineTextInputRecipeProps>;
 
-export declare function NimbusProvider({ children, locale, ...props }: ColorModeProviderProps & {
+export declare function NimbusProvider({ children, locale, router, ...props }: NimbusProviderProps): JSX.Element;
+
+export declare interface NimbusProviderProps extends ColorModeProviderProps {
+    /**
+     * Optional locale for internationalization.
+     * Expects a [BCP47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) (e.g., 'en-US', 'de-DE', 'fr-FR').
+     * Defaults to the user's browser locale if not provided.
+     */
     locale?: string;
-}): JSX.Element;
+    /**
+     * Optional router configuration object for client-side navigation.
+     * When provided, all nimbus components with href props will use client-side routing.
+     * - `navigate`: Function to programmatically navigate to routes.
+     * - `useHref`: Optional function to transform hrefs (useful for base paths).
+     */
+    router?: NimbusRouterConfig | TypedNimbusRouterConfig;
+}
+
+export declare interface NimbusRouterConfig {
+    /**
+     * Function to programmatically navigate to a new route.
+     * This should be the navigate function from your client-side router.
+     *
+     * @example
+     * // React Router
+     * const navigate = useNavigate();
+     * <NimbusProvider router={{ navigate }} />
+     *
+     * @example
+     * // Next.js App Router
+     * const router = useRouter();
+     * <NimbusProvider router={{ navigate: router.push }} />
+     */
+    navigate: (href: string, routerOptions?: any) => void;
+    /**
+     * Optional function to transform hrefs before they are used.
+     * Useful for prepending base paths or other URL transformations.
+     *
+     * @example
+     * // Next.js with basePath
+     * const useHref = (href: string) => process.env.BASE_PATH + href;
+     * <NimbusProvider router={{ navigate, useHref }} />
+     */
+    useHref?: (href: string) => string;
+}
+
+/**
+ * TypeScript module augmentation for Nimbus router configuration.
+ *
+ * This allows consumers to extend the router configuration types
+ * to match their specific router framework, providing better type safety.
+ *
+ * TODO: Document this in an mdx-file, available to consumers via the docs-app
+ *
+ * @example
+ * // For React Router
+ * import type { NavigateOptions } from 'react-router-dom';
+ *
+ * declare module '@commercetools/nimbus' {
+ *   interface NimbusRouterOptionsBase {
+ *     routerOptions?: NavigateOptions;
+ *   }
+ * }
+ *
+ * @example
+ * // For Next.js App Router
+ * import type { AppRouterInstance } from 'next/dist/shared/lib/app-router-context';
+ *
+ * declare module '@commercetools/nimbus' {
+ *   interface NimbusRouterOptionsBase {
+ *     routerOptions?: Parameters<AppRouterInstance['push']>[1];
+ *   }
+ * }
+ */
+export declare interface NimbusRouterOptionsBase {
+}
 
 /**
  * NumberInput
@@ -2003,6 +2162,159 @@ export declare const PasswordInput: ForwardRefExoticComponent<Omit<PasswordInput
 export declare interface PasswordInputProps extends Omit<TextInputProps, "type"> {
 }
 
+/**
+ * ProgressBar
+ * ============================================================
+ * Displays progress towards completion of a task or process
+ *
+ * Features:
+ *
+ * - Supports both determinate (with value) and indeterminate (loading) states
+ * - Two visual variants: solid (gradient) and contrast (monochromatic)
+ * - Three layouts: minimal, inline, and stacked
+ * - Configurable value formatting with internationalization support
+ * - Full accessibility support with ARIA attributes
+ * - Allows forwarding refs to the underlying DOM element
+ * - Accepts all native HTML div attributes
+ * - Supports variants, sizes, etc. configured in the recipe
+ * - Allows overriding styles by using style-props
+ */
+export declare const ProgressBar: {
+    (props: ProgressBarProps): JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Main props interface for the ProgressBar component.
+ * Extends ProgressBarRootProps to include root props, variant props, and aria props,
+ * while adding custom props for label display and formatting.
+ */
+export declare interface ProgressBarProps extends Omit<ProgressBarRootProps, ExcludedProps_5> {
+    /**
+     * Ref forwarding to the root element
+     */
+    ref?: React.Ref<HTMLDivElement>;
+    /**
+     * Whether the progress bar represents an active, ongoing process.
+     * Set to `true` for dynamic progress (e.g., file uploads, downloads).
+     * Set to `false` for static progress indicators (e.g., step 3 of 5 in a wizard).
+     * @default true
+     */
+    isDynamic?: boolean;
+    /**
+     * Format options for the progress bar.
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat
+     */
+    formatOptions: ProgressBarRootProps["formatOptions"];
+}
+
+/**
+ * Base recipe props interface that combines Chakra UI's recipe props
+ * with the unstyled prop option for the div element.
+ */
+declare interface ProgressBarRecipeProps extends RecipeProps<"div">, UnstyledProp {
+}
+
+/**
+ * Root props interface that extends Chakra's HTML props with our recipe props,
+ * aria props, and data attributes.
+ */
+declare interface ProgressBarRootProps extends HTMLChakraProps<"div", ProgressBarRecipeProps>, Omit<RecipeVariantProps<typeof progressBarSlotRecipe>, "isIndeterminate">, AriaProgressBarProps {
+    [key: `data-${string}`]: string;
+}
+
+/**
+ * Recipe configuration for the ProgressBar component.
+ * Defines the styling variants and base styles using Chakra UI's slot recipe system.
+ */
+declare const progressBarSlotRecipe: SlotRecipeDefinition<"fill" | "label" | "track" | "value" | "root", {
+    size: {
+        "2xs": {
+            root: {
+                "--progress-bar-radius": "{radii.300}";
+                "--progress-bar-font-size": "{fontSizes.350}";
+                "--progress-bar-height": "{sizes.300}";
+                "--progress-bar-line-height": "{fontSizes.500}";
+            };
+        };
+        md: {
+            root: {
+                "--progress-bar-radius": "{radii.600}";
+                "--progress-bar-font-size": "{fontSizes.400}";
+                "--progress-bar-height": "{sizes.600}";
+                "--progress-bar-line-height": "{fontSizes.600}";
+            };
+        };
+    };
+    isDynamic: {
+        true: {
+            fill: {
+                "--progress-bar-animation": "gradient-shimmer 4s ease-in-out infinite";
+                "&[data-complete='true']": {
+                    "--progress-bar-animation": "none";
+                };
+            };
+        };
+    };
+    isIndeterminate: {
+        true: {
+            fill: {
+                "--progress-bar-animation": "progress-indeterminate 2s ease-in-out infinite";
+                width: "40% !important";
+            };
+        };
+    };
+    variant: {
+        solid: {
+            root: {
+                "--progress-bar-text-color": "{colors.neutral.12}";
+                "--progress-bar-track-bg": "{colors.neutralAlpha.3}";
+            };
+        };
+        contrast: {
+            root: {
+                "--progress-bar-text-color": "{colors.colorPalette.contrast}";
+                "--progress-bar-track-bg": "{colors.colorPalette.contrast/15}";
+            };
+            fill: {
+                bgImage: "linear-gradient(90deg, {colors.colorPalette.contrast/25}, {colors.colorPalette.contrast}, {colors.colorPalette.contrast/25})";
+            };
+        };
+    };
+    layout: {
+        minimal: {
+            label: {
+                display: "none";
+            };
+            value: {
+                display: "none";
+            };
+        };
+        inline: {
+            root: {
+                flexDirection: "row";
+                alignItems: "center";
+                gap: "400";
+            };
+            track: {
+                flex: number;
+            };
+        };
+        stacked: {
+            root: {
+                flexDirection: "column";
+                gap: "200";
+            };
+            text: {
+                display: "flex";
+                justifyContent: "space-between";
+                alignItems: "center";
+                width: "100%";
+            };
+        };
+    };
+}>;
+
 declare type RadioGroupProps = Omit<RadioGroupProps_2, "children"> & {
     children?: React.ReactNode;
 };
@@ -2062,6 +2374,10 @@ declare const radioInputSlotRecipe: SlotRecipeDefinition<"option" | "root", {
     };
 }>;
 
+export declare type RouterOptions = NimbusRouterOptionsBase extends {
+    routerOptions: any;
+} ? NimbusRouterOptionsBase["routerOptions"] : any;
+
 export declare const Select: {
     Root: ForwardRefExoticComponent<SelectRootProps_2 & RefAttributes<HTMLDivElement>>;
     Options: {
@@ -2648,14 +2964,68 @@ declare interface TooltipRootProps extends HTMLChakraProps<"div", TooltipRecipeP
  */
 declare type TooltipVariantProps = ExcludePolymorphicFromProps<TooltipRootProps & RecipeVariantProps<typeof tooltipRecipe> & TooltipProps_2>;
 
+export declare interface TypedNimbusRouterConfig {
+    navigate: (href: string, routerOptions?: RouterOptions) => void;
+    useHref?: (href: string) => string;
+}
+
+/**
+ * Hook for managing color mode (light/dark theme) state.
+ *
+ * @experimental This hook is experimental and may change in future versions.
+ *
+ * This hook provides access to the current color mode and functions to change it.
+ * It integrates with the next-themes library to handle theme persistence and system preference detection.
+ *
+ * @returns An object containing:
+ *   - `colorMode`: The current resolved theme ('light' | 'dark' | 'system' | undefined)
+ *   - `setColorMode`: Function to set a specific color mode
+ *   - `toggleColorMode`: Function to toggle between light and dark modes
+ *
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { colorMode, toggleColorMode } = useColorMode();
+ *
+ *   return (
+ *     <button onClick={toggleColorMode}>
+ *       Current mode: {colorMode}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export declare function useColorMode(): {
     colorMode: string | undefined;
     setColorMode: Dispatch<SetStateAction<string>>;
     toggleColorMode: () => void;
 };
 
+/**
+ * Hook that returns a value based on the current color mode.
+ *
+ * @experimental This hook is experimental and may change in future versions.
+ *
+ * @param light - The value to return when the color mode is light
+ * @param dark - The value to return when the color mode is dark
+ * @returns The appropriate value based on the current color mode
+ */
 export declare function useColorModeValue<T>(light: T, dark: T): T;
 
+/**
+ * Hook that provides access to the current color scheme value.
+ *
+ * @experimental This hook is experimental and may change in future versions.
+ *
+ * This hook monitors the color-scheme CSS property on the document's HTML element
+ * and returns the current value. It automatically updates when the color scheme changes,
+ * either through direct style changes or theme updates stored in localStorage.
+ *
+ * The hook observes mutations to the HTML element's style attribute to detect
+ * color scheme changes and re-renders the component when changes occur.
+ *
+ * @returns The current color scheme value as a string ('light', 'dark')
+ */
 export declare function useColorScheme(): string;
 
 export { useCopyToClipboard }