@optiaxiom/react 1.7.11 → 1.7.13

package/dist/{MenuTrigger-C0Ab8gBW.d.ts → MenuTrigger-DWB6KgSO.d.ts}

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ElementType, ComponentPropsWithoutRef, ReactNode, ComponentPropsWithRef, MouseEvent, ReactElement, ContextType } from 'react';
+import { ElementType, ComponentPropsWithoutRef, ReactNode, MouseEvent, ReactElement, ContextType } from 'react';
 import { DayPicker, Matcher } from 'react-day-picker';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _radix_ui_react_popover from '@radix-ui/react-popover';
@@ -2756,6 +2756,16 @@ type BoxProps<T extends ElementType = "div", P = unknown> = ExtendProps<Componen
     asChild?: boolean;
     className?: string;
 }, P>>;
+/**
+ * A primitive layout component that provides access to design tokens and
+ * styling without custom CSS.
+ *
+ * Use `Box` for simple styling (padding, margin, colors, borders) when you
+ * don't need flexbox layout features. For flexbox layouts with
+ * direction/alignment, use `Flex` instead.
+ *
+ * @category layout
+ */
 declare const Box: react.ForwardRefExoticComponent<Omit<NonNullable<Sprinkles & {
     /**
      * Change the default rendered element for the one passed as a child, merging their props and behavior.
@@ -2867,6 +2877,25 @@ type ButtonProps<T extends ElementType = "button", P = unknown> = ButtonRootProp
      */
     iconPosition?: "end" | "start";
 }, P>>;
+/**
+ * Button component for triggering actions, with support for icons, addons, and
+ * loading states.
+ *
+ * Use this for standard action buttons. The component supports icon-only
+ * buttons, buttons with leading/trailing icons, and custom addon content before
+ * or after the main label.
+ *
+ * When not to use:
+ * - For menu and select buttons with a chevron use AngleMenuButton instead.
+ * - For ellipsis menus use EllipsisMenuButton instead.
+ * - For buttons that include label use LabelMenuButton instead.
+ * - For expand/collapse triggers use Disclosure instead of Button with chevron
+ *   icon and manual state.
+ * - Don't use Button to build tab navigation - use Tabs instead.
+ *
+ * @category actions
+ * @since 0.1.0
+ */
 declare const Button: react.ForwardRefExoticComponent<Omit<{
     /**
      * Display content inside the button after `children`.
@@ -2898,13 +2927,65 @@ declare const Button: react.ForwardRefExoticComponent<Omit<{
     className?: string;
 }>, "size"> & Omit<Omit<react.DetailedHTMLProps<react.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "ref">, "color" | "disabled" | "className"> & react.RefAttributes<HTMLButtonElement>>;
 
-type FlexProps = ComponentPropsWithRef<typeof Box>;
-declare const Flex: react.ForwardRefExoticComponent<Omit<Omit<Omit<NonNullable<Sprinkles & {
+type FlexProps = BoxProps<"div", {
+    /**
+     * Set the element's `align-items` CSS property. Defaults to `center` when
+     * `flexDirection='row'`, and `stretch` when `flexDirection='column'`.
+     */
+    alignItems?: BoxProps["alignItems"];
+    /**
+     * Set the element's `flex-direction` CSS property.
+     *
+     * ⚠️ DEFAULTS TO 'column' (vertical stacking) - NOT 'row' like standard CSS!
+     *
+     * - Default: 'column'
+     * - For horizontal layouts: explicitly set flexDirection='row'
+     * - When direction is 'row', alignItems defaults to 'center'
+     * - When direction is 'column', alignItems defaults to 'stretch'
+     */
+    flexDirection?: BoxProps["flexDirection"];
+}>;
+/**
+ * Stack items vertically or horizontally in a flex container.
+ *
+ * 🚨 Use `<Flex>` for vertical stacking and `<Flex flexDirection="row">` for
+ * horizontal stacking, as our component does NOT use the standard CSS `row`
+ * default.
+ *
+ * Best Practices:
+ * - Use Flex for layout direction (flexDirection, gap, alignment)
+ * - Use Box for simpler styling needs (padding, margin, borders, colors)
+ * - Box is a lighter primitive; Flex adds flexbox-specific defaults
+ *
+ * Default Props:
+ * - flexDirection: 'column' (NOT 'row' like CSS!)
+ * - gap: '16'
+ * - alignItems: 'stretch' (when column) or 'center' (when row)
+ *
+ * @category layout
+ * @extends Box
+ */
+declare const Flex: react.ForwardRefExoticComponent<{
+    /**
+     * Set the element's `align-items` CSS property. Defaults to `center` when
+     * `flexDirection='row'`, and `stretch` when `flexDirection='column'`.
+     */
+    alignItems?: BoxProps["alignItems"];
+    /**
+     * Set the element's `flex-direction` CSS property.
+     *
+     * ⚠️ DEFAULTS TO 'column' (vertical stacking) - NOT 'row' like standard CSS!
+     *
+     * - Default: 'column'
+     * - For horizontal layouts: explicitly set flexDirection='row'
+     * - When direction is 'row', alignItems defaults to 'center'
+     * - When direction is 'column', alignItems defaults to 'stretch'
+     */
+    flexDirection?: BoxProps["flexDirection"];
+} & Omit<NonNullable<Sprinkles & {
     asChild?: boolean;
     className?: string;
-}>, never> & Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "color" | "className"> & react.RefAttributes<HTMLDivElement>, "ref"> & {
-    ref?: ((instance: HTMLDivElement | null) => void | react.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES[keyof react.DO_NOT_USE_OR_YOU_WILL_BE_FIRED_CALLBACK_REF_RETURN_VALUES]) | react.RefObject<HTMLDivElement> | null | undefined;
-}, "ref"> & react.RefAttributes<HTMLDivElement>>;
+}>, "alignItems" | "flexDirection"> & Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "color" | "className"> & react.RefAttributes<HTMLDivElement>>;
 
 declare const DialogKitContext: react.Context<{
     id: string;
@@ -2935,6 +3016,11 @@ type DialogKit = {
         getServerSnapshot?: () => DialogItem[]
     ];
 };
+/**
+ * Create a dialog kit instance for managing dialogs programmatically.
+ *
+ * @experimental
+ */
 declare const createDialogKit: () => DialogKit;
 declare const dialogkit: DialogKit;
 
@@ -2946,6 +3032,9 @@ declare const cell: (props?: {
 type CellVariants = RecipeVariants<typeof cell>;
 
 type TableHeaderCellProps = BoxProps<"th", NonNullable<CellVariants>>;
+/**
+ * @group Table
+ */
 declare const TableHeaderCell: react.ForwardRefExoticComponent<{
     pinned?: boolean | undefined;
 } & Omit<NonNullable<Sprinkles & {
@@ -3027,6 +3116,13 @@ type DateRange = {
     from: Date;
     to: Date;
 };
+/**
+ * Base date picker component.
+ *
+ * @category date
+ * @since 0.12.1
+ * @experimental
+ */
 declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<HTMLDivElement>>;
 
 declare const ModalListbox: react.ForwardRefExoticComponent<{
@@ -3041,9 +3137,16 @@ declare const ModalListbox: react.ForwardRefExoticComponent<{
 }>, never> & Omit<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "color" | "className"> & react.RefAttributes<HTMLDivElement>, "ref">, "animation" | "fontFamily" | "fontSize" | "size" | "backgroundImage" | "borderColor" | "color" | "cursor" | "fontWeight" | "objectFit" | "overflowX" | "overflowY" | "pointerEvents" | "textAlign" | "textTransform" | "transition" | "whiteSpace" | "bg" | "border" | "borderB" | "borderL" | "borderR" | "borderT" | "m" | "mx" | "my" | "mb" | "ml" | "mr" | "mt" | "overflow" | "p" | "px" | "py" | "pb" | "pl" | "pr" | "pt" | "rounded" | "shadow" | "z" | "gap" | "alignItems" | "alignSelf" | "display" | "flex" | "flexDirection" | "flexWrap" | "gridColumn" | "gridTemplateColumns" | "justifyContent" | "justifyItems" | "placeItems" | "maxH" | "maxW" | "h" | "w" | "asChild" | "className"> & react.RefAttributes<HTMLDivElement>>;
 
 type PopoverContentProps = ExcludeProps<BoxProps<typeof _radix_ui_react_popover.Content, Pick<ComponentPropsWithoutRef<typeof ModalListbox>, "maxH" | "minW">>, "arrowPadding" | "avoidCollisions" | "collisionBoundary" | "collisionPadding" | "forceMount" | "hideWhenDetached" | "sticky" | "updatePositionStrategy">;
+/**
+ * @group Popover
+ */
 declare const PopoverContent: react.ForwardRefExoticComponent<PopoverContentProps & react.RefAttributes<HTMLDivElement>>;
 
 type PopoverTriggerProps = ButtonProps<typeof _radix_ui_react_popover.Trigger>;
+/**
+ * @extends Button
+ * @group Popover
+ */
 declare const PopoverTrigger: react.ForwardRefExoticComponent<Omit<{
     addonAfter?: react.ReactNode;
     addonBefore?: react.ReactNode;
@@ -3071,6 +3174,9 @@ declare const content: (props?: {
 type DialogVariants = RecipeVariants<typeof content>;
 
 type DialogContentProps = ExcludeProps<BoxProps<typeof RadixDialog.Content, DialogVariants>, "forceMount">;
+/**
+ * @group Dialog
+ */
 declare const DialogContent: react.ForwardRefExoticComponent<DialogContentProps & react.RefAttributes<HTMLDivElement>>;
 
 type CommandOption = {
@@ -3264,15 +3370,50 @@ type MenuProps = ExcludeProps<ExtendProps<ComponentPropsWithoutRef<typeof Comman
      */
     size?: "lg" | "sm";
 }>, "enabled" | "onHover" | "onSelect">;
+/**
+ * Dropdown menu component for displaying a list of actions or options with
+ * support for multi-select, filtering, and complex interactions.
+ *
+ * Use this with MenuTrigger for action menus and dropdowns. MenuTrigger
+ * automatically renders a button with chevron icon, or use MenuTrigger asChild
+ * with custom buttons like EllipsisMenuButton for overflow menus.
+ *
+ * For simple single-select form inputs, use Select instead.
+ *
+ * @category overlay
+ * @group Menu
+ * @since 1.6.0
+ */
 declare function Menu({ children, defaultOpen, inputValue: inputValueProp, inputVisible: inputVisibleProp, onInputValueChange, onOpenChange, open: openProp, options: optionsProp, placeholder, size: sizeProp, ...props }: MenuProps): react_jsx_runtime.JSX.Element;
 declare namespace Menu {
     var displayName: string;
 }
 
 type MenuContentProps = ExcludeProps<ComponentPropsWithoutRef<typeof DialogContent> & ComponentPropsWithoutRef<typeof PopoverContent>, "size">;
+/**
+ * Menu content rendered in a portal with absolute positioning.
+ *
+ * Rendered as a popover in larger screens and in a dialog in smaller screens by
+ * default.
+ *
+ * @group Menu
+ */
 declare const MenuContent: react.ForwardRefExoticComponent<MenuContentProps & react.RefAttributes<HTMLDivElement>>;
 
 type MenuTriggerProps = ComponentPropsWithoutRef<typeof PopoverTrigger>;
+/**
+ * Trigger button for Menu component with automatic chevron icon.
+ *
+ * Use this as the trigger for Menu dropdowns. By default, renders an
+ * AngleMenuButton (button with trailing chevron). Use asChild to customize the
+ * trigger button.
+ *
+ * @example
+ * <MenuTrigger asChild><EllipsisMenuButton /></MenuTrigger>
+ *
+ * @extends Button
+ * @group Menu
+ */
 declare const MenuTrigger: react.ForwardRefExoticComponent<Omit<Omit<{
     addonAfter?: react.ReactNode;
     addonBefore?: react.ReactNode;