update the RFC and provide and example/showcase for button component

Author: dmytrokirpa

docs/react-v9/contributing/rfcs/react-components/convergence/unstyled-components.md

@@ -0,0 +1,7 @@
+import { ButtonUnstyled } from '@fluentui/react-button';
+
+console.log(ButtonUnstyled);
+
+export default {
+  name: 'ButtonUnstyled',
+};

packages/react-components/react-button/library/bundle-size/ButtonUnstyled.fixture.js

@@ -16,6 +16,18 @@ import type { SlotClassNames } from '@fluentui/react-utilities';
 // @public
 export const Button: ForwardRefComponent<ButtonProps>;
 
+// @public (undocumented)
+export type ButtonBaseProps = ComponentProps<ButtonSlots> & {
+    disabledFocusable?: boolean;
+    disabled?: boolean;
+    iconPosition?: 'before' | 'after';
+};
+
+// @public (undocumented)
+export type ButtonBaseState = ComponentState<ButtonSlots> & Required<Pick<ButtonBaseProps, 'disabledFocusable' | 'disabled' | 'iconPosition'>> & {
+    iconOnly: boolean;
+};
+
 // @public (undocumented)
 export const buttonClassNames: SlotClassNames<ButtonSlots>;
 
@@ -29,11 +41,8 @@ export interface ButtonContextValue {
 }
 
 // @public (undocumented)
-export type ButtonProps = ComponentProps<ButtonSlots> & {
+export type ButtonProps = ButtonBaseProps & {
     appearance?: 'secondary' | 'primary' | 'outline' | 'subtle' | 'transparent';
-    disabledFocusable?: boolean;
-    disabled?: boolean;
-    iconPosition?: 'before' | 'after';
     shape?: 'rounded' | 'circular' | 'square';
     size?: ButtonSize;
 };
@@ -45,9 +54,10 @@ export type ButtonSlots = {
 };
 
 // @public (undocumented)
-export type ButtonState = ComponentState<ButtonSlots> & Required<Pick<ButtonProps, 'appearance' | 'disabledFocusable' | 'disabled' | 'iconPosition' | 'shape' | 'size'>> & {
-    iconOnly: boolean;
-};
+export type ButtonState = ButtonBaseState & Required<Pick<ButtonProps, 'appearance' | 'disabledFocusable' | 'disabled' | 'iconPosition' | 'shape' | 'size'>>;
+
+// @public
+export const ButtonUnstyled: React_2.ForwardRefExoticComponent<ButtonBaseProps & React_2.RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
 
 // @public
 export const CompoundButton: ForwardRefComponent<CompoundButtonProps>;
@@ -133,7 +143,10 @@ export type ToggleButtonProps = ButtonProps & {
 export type ToggleButtonState = ButtonState & Required<Pick<ToggleButtonProps, 'checked'>>;
 
 // @public
-export const useButton_unstable: (props: ButtonProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonState;
+export const useButton_unstable: (props: ButtonProps, ref: React.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonState;
+
+// @public
+export const useButtonBehavior_unstable: (props: ButtonBaseProps, ref: React_2.Ref<HTMLButtonElement | HTMLAnchorElement>) => ButtonBaseState;
 
 // @internal
 export const useButtonContext: () => ButtonContextValue;

packages/react-components/react-button/library/etc/react-button.api.md

@@ -1,8 +1,16 @@
-export type { ButtonProps, ButtonSlots, ButtonState } from './components/Button/index';
+export type {
+  ButtonBaseProps,
+  ButtonBaseState,
+  ButtonProps,
+  ButtonSlots,
+  ButtonState,
+} from './components/Button/index';
 export {
   Button,
+  ButtonUnstyled,
   buttonClassNames,
   renderButton_unstable,
   useButtonStyles_unstable,
   useButton_unstable,
+  useButtonBehavior_unstable,
 } from './components/Button/index';

packages/react-components/react-button/library/src/Button.tsx

@@ -18,19 +18,10 @@ export type ButtonSlots = {
  */
 export type ButtonSize = 'small' | 'medium' | 'large';
 
-export type ButtonProps = ComponentProps<ButtonSlots> & {
-  /**
-   * A button can have its content and borders styled for greater emphasis or to be subtle.
-   * - 'secondary' (default): Gives emphasis to the button in such a way that it indicates a secondary action.
-   * - 'primary': Emphasizes the button as a primary action.
-   * - 'outline': Removes background styling.
-   * - 'subtle': Minimizes emphasis to blend into the background until hovered or focused.
-   * - 'transparent': Removes background and border styling.
-   *
-   * @default 'secondary'
-   */
-  appearance?: 'secondary' | 'primary' | 'outline' | 'subtle' | 'transparent';
-
+/**
+ * Defines the base props for the Button component (behavior only, no design props).
+ */
+export type ButtonBaseProps = ComponentProps<ButtonSlots> & {
   /**
    * When set, allows the button to be focusable even when it has been disabled. This is used in scenarios where it
    * is important to keep a consistent tab order for screen reader and keyboard users. The primary example of this
@@ -53,6 +44,20 @@ export type ButtonProps = ComponentProps<ButtonSlots> & {
    * @default 'before'
    */
   iconPosition?: 'before' | 'after';
+};
+
+export type ButtonProps = ButtonBaseProps & {
+  /**
+   * A button can have its content and borders styled for greater emphasis or to be subtle.
+   * - 'secondary' (default): Gives emphasis to the button in such a way that it indicates a secondary action.
+   * - 'primary': Emphasizes the button as a primary action.
+   * - 'outline': Removes background styling.
+   * - 'subtle': Minimizes emphasis to blend into the background until hovered or focused.
+   * - 'transparent': Removes background and border styling.
+   *
+   * @default 'secondary'
+   */
+  appearance?: 'secondary' | 'primary' | 'outline' | 'subtle' | 'transparent';
 
   /**
    * A button can be rounded, circular, or square.
@@ -69,12 +74,18 @@ export type ButtonProps = ComponentProps<ButtonSlots> & {
   size?: ButtonSize;
 };
 
-export type ButtonState = ComponentState<ButtonSlots> &
-  Required<Pick<ButtonProps, 'appearance' | 'disabledFocusable' | 'disabled' | 'iconPosition' | 'shape' | 'size'>> & {
+/**
+ * Defines the base state for the Button component (behavior only, no design state).
+ */
+export type ButtonBaseState = ComponentState<ButtonSlots> &
+  Required<Pick<ButtonBaseProps, 'disabledFocusable' | 'disabled' | 'iconPosition'>> & {
     /**
      * A button can contain only an icon.
      *
      * @default false
      */
     iconOnly: boolean;
   };
+
+export type ButtonState = ButtonBaseState &
+  Required<Pick<ButtonProps, 'appearance' | 'disabledFocusable' | 'disabled' | 'iconPosition' | 'shape' | 'size'>>;

packages/react-components/react-button/library/src/components/Button/Button.types.ts

@@ -0,0 +1,21 @@
+'use client';
+
+import * as React from 'react';
+import { renderButton_unstable } from './renderButton';
+import type { ButtonBaseProps, ButtonState } from './Button.types';
+import { useButtonBehavior_unstable } from './useButtonBehavior';
+
+/**
+ * ButtonUnstyled - an unstyled version of the Button component, has no default Fluent styles applied but provides
+ * the necessary structure and behavior.
+ *
+ * @param props - Button props
+ * @param ref - Ref to the button element
+ */
+export const ButtonUnstyled = React.forwardRef<HTMLButtonElement | HTMLAnchorElement, ButtonBaseProps>((props, ref) => {
+  const state = useButtonBehavior_unstable(props, ref);
+
+  return renderButton_unstable(state as ButtonState);
+});
+
+ButtonUnstyled.displayName = 'ButtonUnstyled';

packages/react-components/react-button/library/src/components/Button/ButtonUnstyled.tsx

@@ -1,6 +1,8 @@
 export { Button } from './Button';
+export { ButtonUnstyled } from './ButtonUnstyled';
 // Explicit exports to omit ButtonCommons
-export type { ButtonProps, ButtonSlots, ButtonState } from './Button.types';
+export type { ButtonBaseProps, ButtonBaseState, ButtonProps, ButtonSlots, ButtonState } from './Button.types';
 export { renderButton_unstable } from './renderButton';
 export { useButton_unstable } from './useButton';
+export { useButtonBehavior_unstable } from './useButtonBehavior';
 export { buttonClassNames, useButtonStyles_unstable } from './useButtonStyles.styles';

packages/react-components/react-button/library/src/components/Button/index.ts

@@ -1,13 +1,11 @@
 'use client';
 
-import * as React from 'react';
-import { ARIAButtonSlotProps, useARIAButtonProps } from '@fluentui/react-aria';
-import { getIntrinsicElementProps, slot } from '@fluentui/react-utilities';
 import { useButtonContext } from '../../contexts/ButtonContext';
+import { useButtonBehavior_unstable } from './useButtonBehavior';
 import type { ButtonProps, ButtonState } from './Button.types';
 
 /**
- * Given user props, defines default props for the Button, calls useButtonState, and returns processed state.
+ * Given user props, defines default props for the Button, calls useButtonBehavior_unstable, and returns processed state.
  * @param props - User provided props to the Button component.
  * @param ref - User provided ref to be passed to the Button component.
  */
@@ -16,34 +14,13 @@ export const useButton_unstable = (
   ref: React.Ref<HTMLButtonElement | HTMLAnchorElement>,
 ): ButtonState => {
   const { size: contextSize } = useButtonContext();
-  const {
-    appearance = 'secondary',
-    as = 'button',
-    disabled = false,
-    disabledFocusable = false,
-    icon,
-    iconPosition = 'before',
-    shape = 'rounded',
-    size = contextSize ?? 'medium',
-  } = props;
-  const iconShorthand = slot.optional(icon, { elementType: 'span' });
+  const { appearance = 'secondary', shape = 'rounded', size = contextSize ?? 'medium' } = props;
+  const state = useButtonBehavior_unstable(props, ref);
+
   return {
-    // Props passed at the top-level
+    ...state,
     appearance,
-    disabled,
-    disabledFocusable,
-    iconPosition,
     shape,
-    size, // State calculated from a set of props
-    iconOnly: Boolean(iconShorthand?.children && !props.children), // Slots definition
-    components: { root: 'button', icon: 'span' },
-    root: slot.always<ARIAButtonSlotProps<'a'>>(getIntrinsicElementProps(as, useARIAButtonProps(props.as, props)), {
-      elementType: 'button',
-      defaultProps: {
-        ref: ref as React.Ref<HTMLButtonElement & HTMLAnchorElement>,
-        type: as === 'button' ? 'button' : undefined,
-      },
-    }),
-    icon: iconShorthand,
+    size,
   };
 };

packages/react-components/react-button/library/src/components/Button/useButton.ts

@@ -0,0 +1,104 @@
+import * as React from 'react';
+import { render, renderHook } from '@testing-library/react';
+import { mergeClasses } from '@griffel/react';
+import { useButtonBehavior_unstable } from './useButtonBehavior';
+import type { ButtonBaseProps } from './Button.types';
+
+describe('useButtonBehavior', () => {
+  it('returns the correct initial state', () => {
+    const { result } = renderHook(() => useButtonBehavior_unstable({}, React.createRef()));
+    expect(result.current).toMatchObject({
+      components: { root: 'button', icon: 'span' },
+      disabled: false,
+      disabledFocusable: false,
+      iconPosition: 'before',
+      iconOnly: false,
+      root: { type: 'button' },
+      icon: undefined,
+    });
+  });
+
+  it('returns the correct state with passed props', () => {
+    const { result } = renderHook(() =>
+      useButtonBehavior_unstable({ disabled: true, icon: 'icon' }, React.createRef()),
+    );
+    expect(result.current).toMatchObject({
+      components: { root: 'button', icon: 'span' },
+      disabled: true,
+      disabledFocusable: false,
+      iconPosition: 'before',
+      iconOnly: true,
+      root: { type: 'button' },
+      icon: {
+        children: 'icon',
+      },
+    });
+  });
+
+  describe('used as a headless hook to build a custom component', () => {
+    type CustomButtonProps = ButtonBaseProps & {
+      appearance?: 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'link';
+      size?: 'tiny' | 'small' | 'medium' | 'large' | 'huge';
+    };
+
+    const CustomButton = React.forwardRef<HTMLButtonElement | HTMLAnchorElement, CustomButtonProps>(
+      ({ appearance = 'primary', size = 'medium', className, ...props }, ref) => {
+        // Used as a headless hook to build a custom component
+        const state = useButtonBehavior_unstable(
+          {
+            className: mergeClasses('btn', `btn-${appearance}`, `btn-${size}`, className),
+            ...props,
+          },
+          ref,
+        );
+
+        // Render the root slot as an anchor or button based on the as prop
+        if (state.root.as === 'a') {
+          return <a {...state.root} />;
+        }
+
+        // Render the root slot as a button
+        return <button {...state.root} />;
+      },
+    );
+
+    it('renders a button when as is not provided', () => {
+      const { getByRole } = render(
+        <CustomButton appearance="tertiary" size="medium">
+          Button
+        </CustomButton>,
+      );
+      const button = getByRole('button', { name: 'Button' });
+      expect(button).toBeDefined();
+      expect(button.getAttribute('type')).toBe('button');
+      expect(button.getAttribute('disabled')).toBeFalsy();
+    });
+
+    it('renders an anchor when as is provided', () => {
+      const { getByRole } = render(
+        <CustomButton as="a" href="#">
+          Link
+        </CustomButton>,
+      );
+      const anchor = getByRole('link', { name: 'Link' });
+      expect(anchor).toBeDefined();
+      expect(anchor.getAttribute('href')).toBe('#');
+    });
+
+    it('disables the button when "disabled" is passed as a prop', () => {
+      const { getByRole } = render(<CustomButton disabled>Button</CustomButton>);
+      const button = getByRole('button', { name: 'Button' });
+      expect(button.hasAttribute('disabled')).toBe(true);
+    });
+
+    it('disables the anchor when "disabled" is passed as a prop', () => {
+      const { getByRole } = render(
+        <CustomButton as="a" href="#" disabled>
+          Link
+        </CustomButton>,
+      );
+      const anchor = getByRole('link');
+      expect(anchor.hasAttribute('aria-disabled')).toBe(true);
+    });
+  });
+});

packages/react-components/react-button/library/src/components/Button/useButtonBehavior.test.tsx

@@ -0,0 +1,40 @@
+'use client';
+
+import * as React from 'react';
+import { type ARIAButtonSlotProps, useARIAButtonProps } from '@fluentui/react-aria';
+import { getIntrinsicElementProps, slot } from '@fluentui/react-utilities';
+import { ButtonBaseProps, ButtonBaseState } from './Button.types';
+
+/**
+ * Given user props, defines default props for the Button behavior state and returns it.
+ *
+ * @param props - User provided props to the Button component.
+ * @param ref - User provided ref to be passed to the Button component.
+ * @returns Button behavior state
+ */
+export const useButtonBehavior_unstable = (
+  props: ButtonBaseProps,
+  ref: React.Ref<HTMLButtonElement | HTMLAnchorElement>,
+): ButtonBaseState => {
+  const { as = 'button', disabled = false, disabledFocusable = false, icon, iconPosition = 'before' } = props;
+  const iconShorthand = slot.optional(icon, { elementType: 'span' });
+
+  return {
+    disabled,
+    disabledFocusable,
+    iconPosition,
+    iconOnly: Boolean(iconShorthand?.children && !props.children),
+    root: slot.always<ARIAButtonSlotProps<'a'>>(
+      getIntrinsicElementProps(as, useARIAButtonProps(props.as, props as ARIAButtonSlotProps<'a'>)),
+      {
+        elementType: as,
+        defaultProps: {
+          ref: ref as React.Ref<HTMLButtonElement & HTMLAnchorElement>,
+          type: as === 'button' ? 'button' : undefined,
+        },
+      },
+    ),
+    icon: iconShorthand,
+    components: { root: as, icon: 'span' },
+  };
+};