Reimplement button API to simplify usage (#102)

* Reimplement button API to simplify usage
- introduce new types for nav-button

* Improve documentation

* dd styles to support all size variants of the nav button

* introduce new doc pages for nav button types

* Split Button and Nav Button to separate sections

* Improve buttons

* Improvements after review

* style markdown table

* fix color

* update npm package

Author: piotrblaszczyk

packages/ui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@synergycodes/axiom",
   "type": "module",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.0-beta.10",
   "description": "A React library for creating node-based UIs and diagram-driven applications. Perfect for React Flow users, providing ready-to-use node templates and components that work seamlessly with React Flow's ecosystem.",
   "keywords": [
     "react",

packages/ui/src/components/accordion/accordion.tsx

@@ -78,7 +78,9 @@ export const Accordion = forwardRef<HTMLDivElement, AccordionProps>(
           aria-expanded={isOpen}
         >
           <span className="ax-public-h10">{label}</span>
-          <NavButton className={styles['header-button']} icon={<CaretUp />} />
+          <NavButton className={styles['header-button']}>
+            <CaretUp />
+          </NavButton>
         </div>
         <div
           className={clsx(styles['inner-container'], {

packages/ui/src/components/button/base-button/base-button.tsx

@@ -1,9 +1,8 @@
 import clsx from 'clsx';
 import buttonStyles from './base-button.module.css';
-import gapStyles from './gap.module.css';
 
 import { Button } from '@mui/base/Button';
-import { BaseButtonProps, CommonButtonProps } from '../types';
+import { BaseButtonProps } from '../types';
 import { forwardRef } from 'react';
 import { prepareForSlot } from '@mui/base';
 import { Tooltip } from '@ui/components/tooltip/tooltip';
@@ -12,10 +11,10 @@ type Props = {
   /** Class name meant to be used by parent components using <BaseButton /> directly */
   styles: string;
   children: React.ReactNode;
-} & CommonButtonProps;
+} & BaseButtonProps;
 
 export const BaseButton = prepareForSlot(
-  forwardRef<HTMLButtonElement, BaseButtonProps<Props>>(
+  forwardRef<HTMLButtonElement, Props>(
     (
       {
         children,
@@ -24,20 +23,14 @@ export const BaseButton = prepareForSlot(
         tooltip,
         disabled,
         tooltipType = 'default',
-        size = 'medium',
         ...props
       },
       ref,
     ) => {
       const button = (
         <Button
           ref={ref}
-          className={clsx(
-            buttonStyles['button'],
-            gapStyles[size],
-            styles,
-            className,
-          )}
+          className={clsx(buttonStyles['button'], styles, className)}
           disabled={disabled}
           {...props}
         >

packages/ui/src/components/button/buttons.v2.decision-log.md

@@ -0,0 +1,62 @@
+# Button Components Redesign: Structural Discrimination & API Simplification
+
+Proposed by: **Piotr Błaszczyk**
+
+Date: **12.06.2025**
+
+## Context
+
+The original implementation of button components involved creating four distinct components (`LabelButton`, `NavButton`, `IconButton`, and `IconLabelButton`) to cover different usage scenarios. While this provided a high degree of specificity and control, it introduced complexity in the API.
+
+Each button type had its own props, styling logic, and render behavior. While maintainable in the short term, it made the overall button API harder to learn and less adaptable to changes.
+
+With the evolution of our design system, the need emerged for a more **unified**, **simpler**, and **smarter** API that maintains strong **type safety**, and full **customizability**.
+
+## Decision
+
+To simplify the API while increasing flexibility and consistency, we refactored the button components using **structural discrimination** and **TypeScript overloads**. This led to the introduction of only two components:
+
+### `Button`
+
+### `NavButton`
+
+Both components now support three rendering modes, automatically selected based on the `children` structure:
+
+- **LabelButton** → Rendered when `children` is a plain `string`
+- **IconButton** → Rendered when `children` is a single `ReactElement` (icon)
+- **IconLabelButton** → Rendered when `children` includes both `string` and one or two icons (before/after)
+
+### Key Improvements
+
+1. **Structural Discrimination**
+
+   - The component infers the correct variant purely from the structure of `children`, not from a manual `type` prop.
+   - This significantly simplifies usage while maintaining strict prop boundaries.
+
+2. **Overload-based Props**
+
+   - TypeScript function overloads are used to expose only valid prop combinations for each type.
+   - Invalid combinations (e.g., passing label-specific props to an icon-only button) are caught at compile time.
+
+3. **API Parity**
+
+   - `NavButton` now supports the same rendering flexibility as `Button`, adapting automatically to icon-only, label-only, or mixed children.
+
+4. **Facade Design**
+
+   - Under the hood, the same internal components (`LabelButton`, `IconButton`, `IconLabelButton`) are still used.
+   - A lightweight **facade layer** determines the correct button types based on structural cues and delegates rendering to the appropriate internal component.
+   - This separation allows the internal implementation to stay clean and type-safe, while simplifying the public API.
+
+## Consequences
+
+- **Simplified Usage**: Consumers use one consistent Button API without needing to remember different component names for different content types.
+- **Strong Type Safety**: Incorrect prop usage is prevented by TypeScript at compile time.
+- **Alignment with Design System**: The new components fully match the latest design system expectations while reducing entry friction for developers.
+- **White-label Ready**: Continued use of CSS Modules ensures easy theming and customization per client.
+- **Ease of Migration**: Existing buttons can be migrated progressively by converting them to use the new `Button` or `NavButton` with the appropriate children.
+- **Future-Proofing**: The facade model allows additional internal types to be added or optimized without breaking the public API.
+
+## Status
+
+Accepted

packages/ui/src/components/button/guards.ts

@@ -0,0 +1,25 @@
+import { isValidElement, PropsWithChildren } from 'react';
+
+export function hasIconChildrenOnly<T>(
+  props: PropsWithChildren,
+): props is PropsWithChildren<T> {
+  return isValidElement(props.children) || typeof props.children === 'function';
+}
+
+export function hasChildrenWithStringAndIcons<T>(
+  props: PropsWithChildren,
+): props is PropsWithChildren<T> {
+  return (
+    Array.isArray(props.children) &&
+    props.children.length >= 2 &&
+    (typeof props.children[0] === 'string' ||
+      isValidElement(props.children[0])) &&
+    (typeof props.children[1] === 'string' || isValidElement(props.children[1]))
+  );
+}
+
+export function hasStringChildrenOnly<T>(
+  props: PropsWithChildren,
+): props is PropsWithChildren<T> {
+  return typeof (props as PropsWithChildren<T>).children === 'string';
+}