@ideasui/button 0.0.2-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 IdeasUI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @ideasui/button
+
+A versatile button component with multiple variants, sizes, and states.
+
+## Installation
+
+```bash
+npm install @ideasui/button
+```
+
+## Usage
+
+```tsx
+import { Button } from '@ideasui/button';
+
+function App() {
+  return (
+    <Button variant="solid" color="primary" size="md">
+      Click me
+    </Button>
+  );
+}
+```
+
+## API Reference
+
+### ButtonProps
+
+| Prop         | Type                                                                                  | Default   | Description                            |
+| ------------ | ------------------------------------------------------------------------------------- | --------- | -------------------------------------- |
+| variant      | 'solid' \| 'outline' \| 'ghost'                                                       | 'solid'   | Visual style variant                   |
+| color        | 'default' \| 'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' | 'default' | Color variant based on semantic intent |
+| size         | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'                                                  | 'md'      | Size of the button                     |
+| radius       | 'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'                                      | 'md'      | Border radius variant                  |
+| fullWidth    | boolean                                                                               | false     | Whether button should take full width  |
+| loading      | boolean                                                                               | false     | Whether button is in loading state     |
+| loadingText  | string                                                                                | -         | Text to show when loading              |
+| startContent | ReactNode                                                                             | -         | Content to show at start of button     |
+| endContent   | ReactNode                                                                             | -         | Content to show at end of button       |
+| disabled     | boolean                                                                               | false     | Whether button is disabled             |
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Button>Default Button</Button>
+<Button variant="outline">Outline Button</Button>
+<Button variant="ghost">Ghost Button</Button>
+```
+
+### Colors
+
+```tsx
+<Button color="primary">Primary</Button>
+<Button color="success">Success</Button>
+<Button color="warning">Warning</Button>
+<Button color="danger">Danger</Button>
+```
+
+### Sizes
+
+```tsx
+<Button size="xs">Extra Small</Button>
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
+<Button size="xl">Extra Large</Button>
+```
+
+### With Icons
+
+```tsx
+import { Heart, Download } from 'lucide-react'
+
+<Button startContent={<Heart />}>Like</Button>
+<Button endContent={<Download />}>Download</Button>
+```
+
+### Loading State
+
+```tsx
+<Button loading>Loading</Button>
+<Button loading loadingText="Saving...">Save</Button>
+```
+
+### States
+
+```tsx
+<Button disabled>Disabled</Button>
+<Button fullWidth>Full Width</Button>
+```
+
+## Accessibility
+
+The Button component follows WAI-ARIA guidelines:
+
+- Uses semantic `button` element
+- Supports keyboard navigation (Enter/Space)
+- Proper `disabled` and `aria-disabled` attributes
+- Loading state is communicated to screen readers
+- Focus management with visible focus indicators
+
+## Styling
+
+The component uses Tailwind CSS classes and can be customized via:
+
+- CSS custom properties
+- Tailwind configuration
+- Custom className prop
+- Component variants system
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type { ButtonProps } from '@ideasui/button';
+
+const MyButton: React.FC<ButtonProps> = (props) => {
+  return <Button {...props} />;
+};
+```

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import {Button}from'react-aria-components';import {cn,mergePropsWithContext,getAccessibleName}from'@ideasui/utils';import {createContext,forwardRef,useContext}from'react';import {button}from'@ideasui/theme/recipes';import {jsx,jsxs,Fragment}from'react/jsx-runtime';var C=createContext(null);function E(){return useContext(C)}var v=forwardRef(({children:o,className:c,size:t,color:s,variant:u,isDisabled:a,isAttached:n=true,isVertical:l=false,radius:d,fullWidth:i,disableAnimation:p=true,showDivider:m,...B},h)=>{let e={size:t,color:s,variant:u,isDisabled:a,isAttached:n,isVertical:l,radius:d,fullWidth:i,disableAnimation:p,showDivider:m},I=cn(i?"flex":"inline-flex",l?"flex-col":"flex-row",n?"isolate":l?"gap-y-2":"gap-x-2",i&&"w-full",c);return jsx(C.Provider,{value:e,children:jsx("div",{ref:h,className:I,"data-attached":n,"data-full-width":i,"data-slot":"button-group","data-vertical":l,role:"group",...B,children:o})})});v.displayName="IdeasUI.Button.Group";var T=createContext(null);function P(){let o=useContext(T);if(!o)throw new Error("Button sub-components must be rendered within a Button component");return o}var f=forwardRef(({children:o,className:c,placement:t="start",...s},u)=>{let{styles:a,classNames:n}=P(),{icon:l}=a,d=t==="start"?n?.startIcon:n?.endIcon;return jsx("span",{ref:u,"aria-hidden":"true",className:cn(l(),t==="end"?"order-last":"order-first",d,c),"data-slot":"button-icon",...s,children:o})});f.displayName="IdeasUI.Button.Icon";var g=forwardRef(({className:o,label:c="Loading",...t},s)=>{let{styles:u,classNames:a}=P(),{loader:n,icon:l}=u;return jsxs("span",{ref:s,className:cn(n(),l(),"inline-flex shrink-0 items-center justify-center",a?.spinner,o),"data-slot":"button-spinner",role:"status",...t,children:[jsx("svg",{className:"size-full animate-spin",fill:"none",stroke:"currentColor",strokeLinecap:"round",strokeLinejoin:"round",strokeWidth:"2.5",viewBox:"0 0 24 24",xmlns:"http://www.w3.org/2000/svg",children:jsx("path",{d:"M21 12a9 9 0 1 1-6.219-8.56"})}),jsx("span",{className:"sr-only",children:c})]})});g.displayName="IdeasUI.Button.Spinner";var S=forwardRef(({children:o,className:c,...t},s)=>{let{styles:u,classNames:a}=P(),{shortcut:n}=u;return jsx("kbd",{ref:s,className:cn(n(),a?.shortcut,c),"data-slot":"button-shortcut",...t,children:o})});S.displayName="IdeasUI.Button.Shortcut";var L=forwardRef(({children:o,className:c,...t},s)=>{let{styles:u,classNames:a}=P(),{label:n}=u;return jsx("span",{ref:s,className:cn(n(),a?.label,c),"data-slot":"button-label",...t,children:o})});L.displayName="IdeasUI.Button.Label";var j=({isLoading:o,loadingIndicator:c,loadingPosition:t="start",isIconOnly:s,startIcon:u,endIcon:a,shortcut:n,children:l,renderProps:d})=>{let i=typeof l=="function"?l(d):l,p=c||jsx(g,{});if(s||o&&t==="center")return o?p:i;let m=o&&t==="start",B=o&&t==="end";return jsxs(Fragment,{children:[m?jsx(f,{placement:"start",children:p}):null,u&&!m?jsx(f,{placement:"start",children:u}):null,typeof i=="string"||typeof i=="number"?jsx(L,{children:i}):i,a&&!B?jsx(f,{placement:"end",children:a}):null,B?jsx(f,{placement:"end",children:p}):null,n?jsx(S,{children:n}):null]})},D=forwardRef((o,c)=>{let{isLoading:t,loadingIndicator:s,loadingPosition:u,isIconOnly:a,startIcon:n,endIcon:l,shortcut:d,children:i,className:p,classNames:m,...B}=o,h=E(),e=mergePropsWithContext(o,h),I=e.isDisabled||t,w=button({variant:e.variant,size:e.size,color:e.color,radius:e.radius,fullWidth:e.fullWidth,isIconOnly:a,isDisabled:I,isLoading:t,disableAnimation:e.disableAnimation,isAttached:e.isAttached,isVertical:e.isVertical,elevation:e.elevation,showDivider:e.showDivider??e.isAttached}),R=getAccessibleName(e,typeof i=="function"?null:i);return jsx(Button,{ref:c,"aria-busy":t,"aria-label":t&&!R?typeof s=="string"?s:"Loading":R,className:N=>w.base({className:cn(typeof p=="function"?p(N):p,m?.base)}),"data-attached":e.isAttached,"data-slot":"button","data-vertical":e.isVertical,isDisabled:I,isPending:t,...B,children:N=>jsx(T.Provider,{value:{styles:w,classNames:m},children:jsx(j,{endIcon:l,isIconOnly:a,isLoading:t,loadingIndicator:s,loadingPosition:u,renderProps:N,shortcut:d,startIcon:n,children:i})})})});D.displayName="IdeasUI.Button";var x=D;x.Icon=f;x.Shortcut=S;x.Spinner=g;x.Label=L;x.Group=v;
+export{x as Button,v as ButtonGroup,C as ButtonGroupContext,E as useButtonGroupContext};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ideasui/button",
+  "version": "0.0.2-beta.0",
+  "description": "A high-performance, accessible Button and ButtonGroup component library for React, built with Tailwind CSS v4 and React Aria.",
+  "author": "IdeasUI<support@ideasui.com>",
+  "homepage": "https://ideasui.com",
+  "license": "MIT",
+  "keywords": [
+    "ideasui",
+    "react",
+    "button",
+    "button-group",
+    "button-component",
+    "accessible-components",
+    "ui-components",
+    "design-system",
+    "tailwindcss"
+  ],
+  "main": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "clean-package": "../../../clean-package.config.json",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ideas2logic-lab/ideasui.git",
+    "directory": "packages/components/button"
+  },
+  "bugs": {
+    "url": "https://github.com/ideas2logic-lab/ideasui/issues"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "react-aria-components": "^1.16.0",
+    "@ideasui/theme": "0.0.5-beta.0",
+    "@ideasui/utils": "0.0.2-beta.0"
+  },
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts"
+}

package/src/button-group-context.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import type { ButtonProps } from './button.types';
+
+import { createContext, useContext } from 'react';
+
+export interface ButtonGroupContextType {
+  size?: ButtonProps['size'];
+  color?: ButtonProps['color'];
+  variant?: ButtonProps['variant'];
+  isDisabled?: boolean;
+  isAttached?: boolean;
+  isVertical?: boolean;
+  radius?: ButtonProps['radius'];
+  fullWidth?: boolean;
+  disableAnimation?: boolean;
+  showDivider?: boolean;
+}
+
+export const ButtonGroupContext = createContext<ButtonGroupContextType | null>(null);
+
+/**
+ * Hook to consume the ButtonGroupContext.
+ * @returns The button group context or null if not within a group.
+ */
+export function useButtonGroupContext(): ButtonGroupContextType | null {
+  return useContext(ButtonGroupContext);
+}

package/src/button-group.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import type { HTMLAttributes, ReactNode, JSX } from 'react';
+import type { ButtonGroupContextType } from './button-group-context';
+
+import { forwardRef } from 'react';
+import { cn } from '@ideasui/utils';
+
+import { ButtonGroupContext } from './button-group-context';
+
+/* -----------------------------------------------------------------------------------------------
+ * ButtonGroup Component
+ * ---------------------------------------------------------------------------------------------*/
+
+export interface ButtonGroupProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'color'>, ButtonGroupContextType {
+  /**
+   * Whether the buttons in the group should be vertical.
+   * @default false
+   */
+  isVertical?: boolean;
+  /**
+   * Whether the buttons in the group should be joined together without gaps.
+   * @default true
+   */
+  isAttached?: boolean;
+  /**
+   * Whether to show a divider between the buttons in the group.
+   * @default true (when isAttached is true)
+   */
+  showDivider?: boolean;
+  /**
+   * The content of the button group.
+   */
+  children: ReactNode;
+}
+
+export const ButtonGroup = forwardRef<HTMLDivElement, ButtonGroupProps>(
+  (
+    {
+      children,
+      className,
+      size,
+      color,
+      variant,
+      isDisabled,
+      isAttached = true,
+      isVertical = false,
+      radius,
+      fullWidth,
+      disableAnimation = true,
+      showDivider,
+      ...props
+    },
+    ref,
+  ): JSX.Element => {
+    const contextValue = {
+      size,
+      color,
+      variant,
+      isDisabled,
+      isAttached,
+      isVertical,
+      radius,
+      fullWidth,
+      disableAnimation,
+      showDivider,
+    };
+
+    const groupClasses = cn(
+      fullWidth ? 'flex' : 'inline-flex',
+      isVertical ? 'flex-col' : 'flex-row',
+      isAttached ? 'isolate' : isVertical ? 'gap-y-2' : 'gap-x-2',
+      fullWidth && 'w-full',
+      className,
+    );
+
+    return (
+      <ButtonGroupContext.Provider value={contextValue}>
+        <div
+          ref={ref}
+          className={groupClasses}
+          data-attached={isAttached}
+          data-full-width={fullWidth}
+          data-slot="button-group"
+          data-vertical={isVertical}
+          role="group"
+          {...props}
+        >
+          {children}
+        </div>
+      </ButtonGroupContext.Provider>
+    );
+  },
+);
+
+ButtonGroup.displayName = 'IdeasUI.Button.Group';

package/src/button.tsx

@@ -0,0 +1,320 @@
+'use client';
+
+import type {
+  ButtonProps,
+  ButtonComponent,
+  ButtonLabelProps,
+  ButtonIconProps,
+  ButtonSpinnerProps,
+  ButtonShortcutProps,
+} from './button.types';
+import type { ButtonReturnType } from '@ideasui/theme/recipes';
+import type { ButtonRenderProps } from 'react-aria-components';
+import type { ReactNode, JSX } from 'react';
+
+import { Button as ButtonPrimitive } from 'react-aria-components';
+import { cn, getAccessibleName, mergePropsWithContext } from '@ideasui/utils';
+import { createContext, forwardRef, useContext } from 'react';
+import { button } from '@ideasui/theme/recipes';
+
+import { useButtonGroupContext } from './button-group-context';
+import { ButtonGroup } from './button-group';
+
+/* -----------------------------------------------------------------------------------------------
+ * Button Context
+ * ---------------------------------------------------------------------------------------------*/
+
+/**
+ * Internal context for the Button component to share styles with slots.
+ */
+interface ButtonContextValue {
+  styles: ButtonReturnType;
+  classNames?: ButtonProps['classNames'];
+}
+
+const ButtonContext = createContext<ButtonContextValue | null>(null);
+
+/**
+ * Hook to consume the ButtonContext.
+ * @internal
+ * @throws Error if used outside of a Button component.
+ */
+function useButtonContext(): ButtonContextValue {
+  const context = useContext(ButtonContext);
+
+  if (!context) {
+    throw new Error('Button sub-components must be rendered within a Button component');
+  }
+
+  return context;
+}
+
+/* -----------------------------------------------------------------------------------------------
+ * Button Slots
+ * ---------------------------------------------------------------------------------------------*/
+
+const ButtonIcon = forwardRef<HTMLElement, ButtonIconProps>(
+  ({ children, className, placement = 'start', ...props }, ref): JSX.Element => {
+    const { styles, classNames } = useButtonContext();
+    const { icon } = styles;
+
+    const slotClass = placement === 'start' ? classNames?.startIcon : classNames?.endIcon;
+
+    return (
+      <span
+        ref={ref}
+        aria-hidden="true"
+        className={cn(
+          icon(),
+          placement === 'end' ? 'order-last' : 'order-first',
+          slotClass,
+          className,
+        )}
+        data-slot="button-icon"
+        {...props}
+      >
+        {children}
+      </span>
+    );
+  },
+);
+
+ButtonIcon.displayName = 'IdeasUI.Button.Icon';
+
+const ButtonSpinner = forwardRef<HTMLSpanElement, ButtonSpinnerProps>(
+  ({ className, label = 'Loading', ...props }, ref): JSX.Element => {
+    const { styles, classNames } = useButtonContext();
+    const { loader, icon } = styles;
+
+    return (
+      <span
+        ref={ref}
+        className={cn(
+          loader(),
+          icon(),
+          'inline-flex shrink-0 items-center justify-center',
+          classNames?.spinner,
+          className,
+        )}
+        data-slot="button-spinner"
+        role="status"
+        {...props}
+      >
+        <svg
+          className="size-full animate-spin"
+          fill="none"
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="2.5"
+          viewBox="0 0 24 24"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <path d="M21 12a9 9 0 1 1-6.219-8.56" />
+        </svg>
+        <span className="sr-only">{label}</span>
+      </span>
+    );
+  },
+);
+
+ButtonSpinner.displayName = 'IdeasUI.Button.Spinner';
+
+const ButtonShortcut = forwardRef<HTMLSpanElement, ButtonShortcutProps>(
+  ({ children, className, ...props }, ref): JSX.Element => {
+    const { styles, classNames } = useButtonContext();
+    const { shortcut } = styles;
+
+    return (
+      <kbd
+        ref={ref}
+        className={cn(shortcut(), classNames?.shortcut, className)}
+        data-slot="button-shortcut"
+        {...props}
+      >
+        {children}
+      </kbd>
+    );
+  },
+);
+
+ButtonShortcut.displayName = 'IdeasUI.Button.Shortcut';
+
+const ButtonLabel = forwardRef<HTMLSpanElement, ButtonLabelProps>(
+  ({ children, className, ...props }, ref): JSX.Element => {
+    const { styles, classNames } = useButtonContext();
+    const { label } = styles;
+
+    return (
+      <span
+        ref={ref}
+        className={cn(label(), classNames?.label, className)}
+        data-slot="button-label"
+        {...props}
+      >
+        {children}
+      </span>
+    );
+  },
+);
+
+ButtonLabel.displayName = 'IdeasUI.Button.Label';
+
+/* -----------------------------------------------------------------------------------------------
+ * Button Render Helpers
+ * ---------------------------------------------------------------------------------------------*/
+
+interface ButtonContentProps {
+  isLoading?: boolean;
+  loadingIndicator?: React.ReactNode;
+  loadingPosition?: 'start' | 'end' | 'center';
+  isIconOnly?: boolean;
+  startIcon?: React.ReactNode;
+  endIcon?: React.ReactNode;
+  shortcut?: React.ReactNode;
+  children: ButtonProps['children'];
+  renderProps: ButtonRenderProps;
+}
+
+const ButtonContent = ({
+  isLoading,
+  loadingIndicator,
+  loadingPosition = 'start',
+  isIconOnly,
+  startIcon,
+  endIcon,
+  shortcut,
+  children,
+  renderProps,
+}: ButtonContentProps): ReactNode => {
+  const content = typeof children === 'function' ? children(renderProps) : children;
+  const loader = loadingIndicator || <ButtonSpinner />;
+
+  if (isIconOnly || (isLoading && loadingPosition === 'center')) {
+    return isLoading ? loader : content;
+  }
+
+  const showStartLoader = isLoading && loadingPosition === 'start';
+  const showEndLoader = isLoading && loadingPosition === 'end';
+  const showStartIcon = startIcon && !showStartLoader;
+  const showEndIcon = endIcon && !showEndLoader;
+
+  return (
+    <>
+      {showStartLoader ? <ButtonIcon placement="start">{loader}</ButtonIcon> : null}
+
+      {showStartIcon ? <ButtonIcon placement="start">{startIcon}</ButtonIcon> : null}
+
+      {typeof content === 'string' || typeof content === 'number' ? (
+        <ButtonLabel>{content}</ButtonLabel>
+      ) : (
+        content
+      )}
+
+      {showEndIcon ? <ButtonIcon placement="end">{endIcon}</ButtonIcon> : null}
+
+      {showEndLoader ? <ButtonIcon placement="end">{loader}</ButtonIcon> : null}
+
+      {shortcut ? <ButtonShortcut>{shortcut}</ButtonShortcut> : null}
+    </>
+  );
+};
+
+/* -----------------------------------------------------------------------------------------------
+ * Button Base
+ * ---------------------------------------------------------------------------------------------*/
+
+const ButtonBase = forwardRef<HTMLButtonElement, ButtonProps>((originalProps, ref): JSX.Element => {
+  const {
+    isLoading,
+    loadingIndicator,
+    loadingPosition,
+    isIconOnly,
+    startIcon,
+    endIcon,
+    shortcut,
+    children,
+    className,
+    classNames,
+    ...props
+  } = originalProps;
+
+  const groupContext = useButtonGroupContext();
+  const merged = mergePropsWithContext(originalProps, groupContext);
+
+  // Specific logic for Button
+  const mergedDisabled = merged.isDisabled || isLoading;
+
+  const styles = button({
+    variant: merged.variant,
+    size: merged.size,
+    color: merged.color,
+    radius: merged.radius,
+    fullWidth: merged.fullWidth,
+    isIconOnly,
+    isDisabled: mergedDisabled,
+    isLoading,
+    disableAnimation: merged.disableAnimation,
+    isAttached: merged.isAttached,
+    isVertical: merged.isVertical,
+    elevation: merged.elevation,
+    showDivider: merged.showDivider ?? merged.isAttached,
+  });
+
+  // Ensure we have an accessible name when loading or icon-only
+  const ariaLabel = getAccessibleName(merged, typeof children === 'function' ? null : children);
+  const loadingLabel = typeof loadingIndicator === 'string' ? loadingIndicator : 'Loading';
+
+  return (
+    <ButtonPrimitive
+      ref={ref}
+      aria-busy={isLoading}
+      aria-label={isLoading && !ariaLabel ? loadingLabel : ariaLabel}
+      className={(renderProps) =>
+        styles.base({
+          className: cn(
+            typeof className === 'function' ? className(renderProps) : className,
+            classNames?.base,
+          ),
+        })
+      }
+      data-attached={merged.isAttached}
+      data-slot="button"
+      data-vertical={merged.isVertical}
+      isDisabled={mergedDisabled}
+      isPending={isLoading}
+      {...props}
+    >
+      {(renderProps) => (
+        <ButtonContext.Provider value={{ styles, classNames }}>
+          <ButtonContent
+            endIcon={endIcon}
+            isIconOnly={isIconOnly}
+            isLoading={isLoading}
+            loadingIndicator={loadingIndicator}
+            loadingPosition={loadingPosition}
+            renderProps={renderProps}
+            shortcut={shortcut}
+            startIcon={startIcon}
+          >
+            {children}
+          </ButtonContent>
+        </ButtonContext.Provider>
+      )}
+    </ButtonPrimitive>
+  );
+});
+
+ButtonBase.displayName = 'IdeasUI.Button';
+
+/* -----------------------------------------------------------------------------------------------
+ * Final Export
+ * ---------------------------------------------------------------------------------------------*/
+
+export const Button = ButtonBase as ButtonComponent;
+
+Button.Icon = ButtonIcon;
+Button.Shortcut = ButtonShortcut;
+Button.Spinner = ButtonSpinner;
+Button.Label = ButtonLabel;
+Button.Group = ButtonGroup;

package/src/button.types.ts

@@ -0,0 +1,162 @@
+import type { ButtonProps as ButtonPrimitiveProps, ButtonRenderProps } from 'react-aria-components';
+import type { ForwardRefExoticComponent, HTMLAttributes, ReactNode, RefAttributes } from 'react';
+import type { ButtonVariantProps } from '@ideasui/theme/recipes';
+import type { ButtonGroupProps } from './button-group';
+
+/**
+ * Granular class names for the Button component slots.
+ */
+export interface ButtonClassNames {
+  /** Class name for the button container. */
+  base?: string;
+  /** Class name for the button label. */
+  label?: string;
+  /** Class name for the start icon container. */
+  startIcon?: string;
+  /** Class name for the end icon container. */
+  endIcon?: string;
+  /** Class name for the loading spinner. */
+  spinner?: string;
+  /** Class name for the shortcut container. */
+  shortcut?: string;
+}
+
+/**
+ * Props for the Button component.
+ */
+export interface ButtonProps
+  extends
+    Omit<ButtonPrimitiveProps, 'className'>,
+    Omit<ButtonVariantProps, 'isLoading' | 'isDisabled'> {
+  /**
+   * Whether the button is in a loading state.
+   * @default false
+   */
+  isLoading?: boolean;
+  /**
+   * The element to display as a loading indicator.
+   * If not provided, a default spinner will be used.
+   */
+  loadingIndicator?: ReactNode;
+  /**
+   * The position of the loading indicator relative to the button content.
+   * @default 'start'
+   */
+  loadingPosition?: 'start' | 'end' | 'center';
+  /**
+   * Whether the button should be square and optimized for icons.
+   *
+   * Note: When true, you MUST provide an `aria-label` or `aria-labelledby` for accessibility.
+   * @default false
+   */
+  isIconOnly?: boolean;
+  /**
+   * Icon to display before the button content.
+   */
+  startIcon?: ReactNode;
+  /**
+   * Icon to display after the button content.
+   */
+  endIcon?: ReactNode;
+  /**
+   * The shortcut keys to display.
+   */
+  shortcut?: ReactNode;
+  /**
+   * Whether to show a divider between the buttons in a group.
+   * @default true (when isAttached is true)
+   */
+  showDivider?: boolean;
+  /**
+   * Custom class names for individual button slots.
+   */
+  classNames?: ButtonClassNames;
+  /**
+   * The CSS class name for the button.
+   * Can be a string or a function that receives the button render props.
+   */
+  className?: string | ((props: ButtonRenderProps) => string);
+  /**
+   * The content to display inside the button.
+   * Can be a ReactNode or a function that receives the button render props.
+   */
+  children?: ReactNode | ((props: ButtonRenderProps) => ReactNode);
+  /**
+   * Accessibility label for the button.
+   * Required if the button has no visible label (e.g., `isIconOnly`).
+   */
+  'aria-label'?: string;
+  /**
+   * ID of an element that serves as the accessible label for the button.
+   */
+  'aria-labelledby'?: string;
+}
+
+/**
+ * Props for the Button.Label component.
+ */
+export interface ButtonLabelProps extends HTMLAttributes<HTMLSpanElement> {}
+
+/**
+ * Props for the Button.Icon component.
+ */
+export interface ButtonIconProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * The icon content.
+   */
+  children: ReactNode;
+  /**
+   * The placement of the icon relative to the label.
+   * @default 'start'
+   */
+  placement?: 'start' | 'end';
+}
+
+/**
+ * Props for the Button.Spinner component.
+ */
+export interface ButtonSpinnerProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * Accessibility label for the spinner.
+   * @default 'Loading'
+   */
+  label?: string;
+}
+
+/**
+ * Props for the Button.Shortcut component.
+ */
+export interface ButtonShortcutProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * The shortcut keys to display.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Type for the Button component with its static compound components.
+ */
+export interface ButtonComponent extends ForwardRefExoticComponent<
+  ButtonProps & RefAttributes<HTMLButtonElement>
+> {
+  /**
+   * Component to display the button label.
+   */
+  Label: ForwardRefExoticComponent<ButtonLabelProps & RefAttributes<HTMLSpanElement>>;
+  /**
+   * Component to display an icon inside the button.
+   */
+  Icon: ForwardRefExoticComponent<ButtonIconProps & RefAttributes<HTMLElement>>;
+  /**
+   * Component to display a shortcut indicator inside the button.
+   */
+  Shortcut: ForwardRefExoticComponent<ButtonShortcutProps & RefAttributes<HTMLSpanElement>>;
+  /**
+   * Component to display a loading spinner inside the button.
+   */
+  Spinner: ForwardRefExoticComponent<ButtonSpinnerProps & RefAttributes<HTMLSpanElement>>;
+  /**
+   * Component to group multiple buttons together.
+   */
+  Group: ForwardRefExoticComponent<ButtonGroupProps & RefAttributes<HTMLDivElement>>;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './button';
+export * from './button-group';
+export * from './button-group-context';
+export type * from './button.types';