@optiaxiom/react 1.7.12 → 1.8.0

package/README.md

@@ -10,6 +10,16 @@ Install the package using your package manager of choice:
 npm install @optiaxiom/react
 ```
 
+## AI Assistant Integration
+
+We provide an MCP server that enables AI assistants like Claude Code and Cursor to access accurate Axiom component metadata, design tokens, and usage examples:
+
+```sh
+npm install -g @optiaxiom/mcp
+```
+
+See the [MCP guide](https://optimizely-axiom.github.io/optiaxiom/guides/mcp) for setup instructions.
+
 ## Getting Started
 
 ### 1. Setup CSS Imports
@@ -33,14 +43,14 @@ export function App() {
 Import and use components in your application:
 
 ```jsx
-import { Button, Input, Box, Flex } from "@optiaxiom/react";
+import { Box, Button, Group, Input } from "@optiaxiom/react";
 
 export function MyComponent() {
   return (
-    <Flex alignItems="start">
+    <Group alignItems="start" flexDirection="column" gap="16">
       <Input placeholder="Enter text..." />
       <Button appearance="primary">Submit</Button>
-    </Flex>
+    </Group>
   );
 }
 ```
@@ -58,11 +68,11 @@ import { Button } from "@optiaxiom/react";
 ### Form with Validation
 
 ```jsx
-import { Field, Input, Button, Flex } from "@optiaxiom/react";
+import { Button, Field, Group, Input } from "@optiaxiom/react";
 
 function LoginForm() {
   return (
-    <Flex alignItems="start">
+    <Group alignItems="start" flexDirection="column" gap="16">
       <Field label="Email">
         <Input placeholder="you@example.com" type="email" />
       </Field>
@@ -70,23 +80,23 @@ function LoginForm() {
         <Input type="password" />
       </Field>
       <Button appearance="primary">Sign In</Button>
-    </Flex>
+    </Group>
   );
 }
 ```
 
-### Layout with Box and Flex
+### Layout with Box and Group
 
 ```jsx
-import { Box, Flex, Heading, Text } from "@optiaxiom/react";
+import { Box, Group, Heading, Text } from "@optiaxiom/react";
 
 function Sample() {
   return (
     <Box bg="bg.default" color="fg.default" p="16" rounded="md" shadow="sm">
-      <Flex>
+      <Group flexDirection="column" gap="16">
         <Heading level="3">Sample Title</Heading>
         <Text>Sample description goes here</Text>
-      </Flex>
+      </Group>
     </Box>
   );
 }

package/dist/{MenuTrigger-C0Ab8gBW.d.ts → MenuTrigger-ByYy6TIu.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,49 @@ 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 GroupProps = 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.
+     *
+     * Default: 'row' (CSS standard)
+     */
+    flexDirection?: BoxProps["flexDirection"];
+}>;
+/**
+ * A flexbox layout component for grouping items horizontally or vertically.
+ *
+ * Default Props:
+ * - flexDirection: 'row' (CSS standard - horizontal layout)
+ * - alignItems: 'center' (when row) or 'stretch' (when column)
+ *
+ * Common Usage:
+ * - Horizontal button groups: <Group gap="8"><Button /><Button /></Group>
+ * - Vertical forms: <Group flexDirection="column" gap="16"><Input /><Input /></Group>
+ * - Icon + text combos: <Group gap="4" alignItems="center"><Icon /><Text /></Group>
+ *
+ * @category layout
+ */
+declare const Group: 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.
+     *
+     * Default: 'row' (CSS standard)
+     */
+    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 +3000,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 +3016,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 +3100,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 +3121,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 +3158,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 +3354,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;
@@ -3292,5 +3417,5 @@ declare const MenuTrigger: react.ForwardRefExoticComponent<Omit<Omit<{
     className?: string;
 }>, "size"> & Omit<Omit<_radix_ui_react_popover.PopoverTriggerProps & react.RefAttributes<HTMLButtonElement>, "ref">, "color" | "disabled" | "asChild" | "className"> & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
 
-export { Calendar as C, Flex as F, ModalListbox as M, PopoverContent as P, Button as b, dialogkit as d, Box as f, PopoverTrigger as i, ButtonRoot as j, DialogContent as k, Menu as o, MenuContent as q, MenuTrigger as s, sprinkles as u, vars as v, mapResponsiveValue as w, normalizeResponsiveValue as x, TableHeaderCell as y, createDialogKit as z };
-export type { BoxProps as B, DialogContentProps as D, ExcludeProps as E, LonghandProps as L, RecipeVariants as R, Sprinkles as S, TableHeaderCellProps as T, ButtonProps as a, ExtendProps as c, CalendarProps as e, ResponsiveArray as g, PopoverContentProps as h, FlexProps as l, MenuOption as m, MenuProps as n, MenuContentProps as p, MenuTriggerProps as r, PopoverTriggerProps as t };
+export { Calendar as C, Group as G, ModalListbox as M, PopoverContent as P, Button as b, dialogkit as d, Box as f, PopoverTrigger as i, ButtonRoot as j, DialogContent as k, Menu as o, MenuContent as q, MenuTrigger as s, sprinkles as u, vars as v, mapResponsiveValue as w, normalizeResponsiveValue as x, TableHeaderCell as y, createDialogKit as z };
+export type { BoxProps as B, DialogContentProps as D, ExcludeProps as E, LonghandProps as L, RecipeVariants as R, Sprinkles as S, TableHeaderCellProps as T, ButtonProps as a, ExtendProps as c, CalendarProps as e, ResponsiveArray as g, PopoverContentProps as h, GroupProps as l, MenuOption as m, MenuProps as n, MenuContentProps as p, MenuTriggerProps as r, PopoverTriggerProps as t };