@varialkit/buttongroup 0.1.1

package/docs.md

@@ -0,0 +1,95 @@
+# ButtonGroup
+
+The ButtonGroup component arranges multiple `@solara/button` buttons into a unified control with shared borders and smart corner rounding. Use it for grouped actions, toolbars, and split-button patterns.
+
+## How to Use
+
+Import the component from `@solara/buttongroup` and pass `Button` elements or the `buttons` array prop.
+
+```tsx
+import { Button } from "@solara/button";
+import { ButtonGroup } from "@solara/buttongroup";
+
+export function Example() {
+  return (
+    <ButtonGroup>
+      <Button label="Save" variant="primary" />
+      <Button label="Duplicate" variant="default" />
+      <Button label="Delete" variant="ghost" destructive />
+    </ButtonGroup>
+  );
+}
+```
+
+## Features
+
+- **Flush layout** with overlap for seamless borders.
+- **Smart corner rounding** that keeps the outer radius while flattening inner edges.
+- **Orientation support** for horizontal and vertical stacks.
+- **Shared props** to update every button consistently.
+- **Optional spacing control** to add gaps between buttons.
+- **Icon support** through the underlying Button props (`iconLeft`, `iconRight`, `iconOnly`).
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction of the button group layout. |
+| `fullWidth` | `boolean` | `false` | Stretch the group to fill its container. |
+| `gap` | `number \| string` | `0` | Spacing between buttons. Use `0` for flush borders. |
+| `radius` | `"default" \| "none" \| "full"` | `undefined` | Radius applied to every button in the group. |
+| `buttonProps` | `Partial<ButtonProps>` | `undefined` | Props applied to every button (child props win). |
+| `buttons` | `ButtonProps[]` | `undefined` | Optional button definitions appended after children. |
+| `children` | `React.ReactNode` | `undefined` | Button elements to render inside the group. |
+| `className` | `string` | `undefined` | Additional class name for the group container. |
+
+## Examples
+
+### Vertical Stack with Full Width
+
+```tsx
+<ButtonGroup orientation="vertical" fullWidth>
+  <Button label="Top" />
+  <Button label="Middle" />
+  <Button label="Bottom" />
+</ButtonGroup>
+```
+
+### Shared Props
+
+```tsx
+<ButtonGroup buttonProps={{ size: "small", variant: "tertiary", iconLeft: "arrow_swap_16" }}>
+  <Button label="Left" />
+  <Button label="Center" />
+  <Button label="Right" />
+</ButtonGroup>
+```
+
+### Icon-Only Buttons
+
+```tsx
+<ButtonGroup gap={8} buttons={[
+  { iconOnly: "arrow_line_up_16", "aria-label": "Upload" },
+  { iconOnly: "arrow_line_down_16", "aria-label": "Download" },
+]} />
+```
+
+### Using the `buttons` Prop
+
+```tsx
+<ButtonGroup
+  gap={8}
+  radius="full"
+  buttons={[
+    { label: "Today", variant: "default" },
+    { label: "Week", variant: "default" },
+    { label: "Month", variant: "default" },
+  ]}
+/>
+```
+
+## Accessibility
+
+- `role="group"` is applied to the container for screen readers.
+- Each button keeps its own `aria-*` attributes and focus styles.
+- Provide `aria-label` for icon-only buttons.

package/examples.tsx

@@ -0,0 +1,187 @@
+import React from "react";
+import { Button } from "@solara/button";
+import type { ButtonRadius, ButtonSize, ButtonVariant } from "@solara/button";
+import { iconNames } from "@solara/icons";
+import type { SolaraIconName } from "@solara/icons";
+import { ButtonGroup } from "./src/ButtonGroup";
+import type { ButtonGroupOrientation } from "./src/ButtonGroup.types";
+
+type PlaygroundProps = {
+  orientation: ButtonGroupOrientation;
+  fullWidth: boolean;
+  gap: number;
+  radius: ButtonRadius;
+  size: ButtonSize;
+  variant: ButtonVariant;
+  iconLeft: SolaraIconName | "";
+};
+
+const ButtonGroupPlayground = ({
+  orientation,
+  fullWidth,
+  gap,
+  radius,
+  size,
+  variant,
+  iconLeft,
+}: PlaygroundProps) => {
+  const resolvedIconLeft = iconLeft || undefined;
+
+  return (
+    <ButtonGroup
+      orientation={orientation}
+      fullWidth={fullWidth}
+      gap={gap}
+      radius={radius}
+      buttonProps={{ size, variant, iconLeft: resolvedIconLeft }}
+    >
+      <Button label="Save" />
+      <Button label="Duplicate" />
+      <Button label="Delete" destructive />
+    </ButtonGroup>
+  );
+};
+
+export const stories = {
+  playground: {
+    title: "Playground",
+    description: "Adjust orientation, spacing, and shared button props.",
+    render: (props: PlaygroundProps) => <ButtonGroupPlayground {...props} />,
+    controls: [
+      {
+        name: "orientation",
+        type: "select",
+        options: ["horizontal", "vertical"],
+      },
+      {
+        name: "fullWidth",
+        type: "boolean",
+        label: "Full Width",
+      },
+      {
+        name: "gap",
+        type: "number",
+        label: "Gap (px)",
+        min: 0,
+        max: 24,
+        step: 1,
+      },
+      {
+        name: "radius",
+        type: "select",
+        options: ["default", "none", "full"],
+      },
+      {
+        name: "size",
+        type: "select",
+        options: ["small", "medium", "large"],
+      },
+      {
+        name: "variant",
+        type: "select",
+        options: ["default", "primary", "tertiary", "ghost", "accent"],
+      },
+      {
+        name: "iconLeft",
+        label: "Icon Left",
+        type: "select",
+        options: ["", ...iconNames],
+      },
+    ],
+    initialProps: {
+      orientation: "horizontal",
+      fullWidth: false,
+      gap: 0,
+      radius: "default",
+      size: "medium",
+      variant: "default",
+      iconLeft: "",
+    },
+  },
+  buttonsProp: {
+    title: "Buttons Prop",
+    description: "Provide button definitions without manual children.",
+    showProps: false,
+    render: () => (
+      <ButtonGroup
+        gap={8}
+        radius="full"
+        buttons={[
+          { label: "Today", variant: "default" },
+          { label: "Week", variant: "default" },
+          { label: "Month", variant: "default" },
+        ]}
+      />
+    ),
+    code: `import { ButtonGroup } from "@solara/buttongroup";
+
+export function Example() {
+  return (
+    <ButtonGroup
+      gap={8}
+      radius="full"
+      buttons={[
+        { label: "Today", variant: "default" },
+        { label: "Week", variant: "default" },
+        { label: "Month", variant: "default" },
+      ]}
+    />
+  );
+}
+`,
+  },
+  vertical: {
+    title: "Vertical",
+    description: "Stack buttons vertically and stretch to full width.",
+    showProps: false,
+    render: () => (
+      <div style={{ width: 260 }}>
+        <ButtonGroup orientation="vertical" fullWidth>
+          <Button label="Move" />
+          <Button label="Rename" />
+          <Button label="Archive" />
+        </ButtonGroup>
+      </div>
+    ),
+    code: `import { Button } from "@solara/button";
+import { ButtonGroup } from "@solara/buttongroup";
+
+export function Example() {
+  return (
+    <div style={{ width: 260 }}>
+      <ButtonGroup orientation="vertical" fullWidth>
+        <Button label="Move" />
+        <Button label="Rename" />
+        <Button label="Archive" />
+      </ButtonGroup>
+    </div>
+  );
+}
+`,
+  },
+  icons: {
+    title: "Icons",
+    description: "Use icon props on buttons inside the group.",
+    showProps: false,
+    render: () => (
+      <ButtonGroup gap={8} radius="full" buttonProps={{ iconLeft: "arrow_swap_16" }}>
+        <Button label="Sync" />
+        <Button label="Replace" />
+        <Button label="Merge" />
+      </ButtonGroup>
+    ),
+    code: `import { Button } from "@solara/button";
+import { ButtonGroup } from "@solara/buttongroup";
+
+export function Example() {
+  return (
+    <ButtonGroup gap={8} radius="full" buttonProps={{ iconLeft: "arrow_swap_16" }}>
+      <Button label="Sync" />
+      <Button label="Replace" />
+      <Button label="Merge" />
+    </ButtonGroup>
+  );
+}
+`,
+  },
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@varialkit/buttongroup",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples.tsx"
+  },
+  "dependencies": {
+    "@varialkit/button": "0.1.1",
+    "@varialkit/icons": "0.1.1"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}

package/src/ButtonGroup.scss

@@ -0,0 +1,92 @@
+.solara-button-group {
+  --button-group-gap: 1px;
+  --button-group-overlap: 0px;
+
+  display: inline-flex;
+  align-items: center;
+  position: relative;
+}
+
+.solara-button-group--horizontal {
+  flex-direction: row;
+}
+
+.solara-button-group--vertical {
+  flex-direction: column;
+  align-items: stretch;
+}
+
+.solara-button-group--horizontal > .solara-button-group__button + .solara-button-group__button {
+  margin-left: calc(
+    (var(--button-group-gap) * var(--spacing-multiplier)) -
+      (var(--button-group-overlap) * var(--spacing-multiplier))
+  );
+}
+
+.solara-button-group--vertical > .solara-button-group__button + .solara-button-group__button {
+  margin-top: calc(
+    (var(--button-group-gap) * var(--spacing-multiplier)) -
+      (var(--button-group-overlap) * var(--spacing-multiplier))
+  );
+}
+
+.solara-button-group__button {
+  position: relative;
+  z-index: 1;
+  flex-shrink: 0;
+}
+
+.solara-button-group__button:hover,
+.solara-button-group__button:focus {
+  z-index: 2;
+}
+
+.solara-button-group__button:active {
+  z-index: 3;
+}
+
+.solara-button-group__button:focus-visible {
+  z-index: 4;
+}
+
+.solara-button-group--horizontal .solara-button-group__button--first {
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.solara-button-group--horizontal .solara-button-group__button--middle {
+  border-radius: 0;
+}
+
+.solara-button-group--horizontal .solara-button-group__button--last {
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
+.solara-button-group--vertical .solara-button-group__button--first {
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+.solara-button-group--vertical .solara-button-group__button--middle {
+  border-radius: 0;
+}
+
+.solara-button-group--vertical .solara-button-group__button--last {
+  border-top-left-radius: 0;
+  border-top-right-radius: 0;
+}
+
+.solara-button-group--full-width {
+  width: 100%;
+}
+
+.solara-button-group--full-width.solara-button-group--horizontal
+  > .solara-button-group__button {
+  flex: 1 1 0%;
+}
+
+.solara-button-group--full-width.solara-button-group--vertical
+  > .solara-button-group__button {
+  width: 100%;
+}

package/src/ButtonGroup.tsx

@@ -0,0 +1,133 @@
+import React, { Children, cloneElement, isValidElement, useMemo } from "react";
+import { Button } from "@solara/button";
+import type { ButtonProps } from "@solara/button";
+import type { ButtonGroupProps } from "./ButtonGroup.types";
+import "./ButtonGroup.scss";
+
+const classNames = (...classes: Array<string | false | null | undefined>) =>
+  classes.filter(Boolean).join(" ");
+
+const isZeroGap = (gap: ButtonGroupProps["gap"]) => {
+  if (gap === undefined || gap === null) return true;
+  if (typeof gap === "number") return gap === 0;
+  const trimmed = gap.trim();
+  return trimmed === "0" || trimmed === "0px" || trimmed === "0rem" || trimmed === "0em";
+};
+
+const resolveGapValue = (gap: ButtonGroupProps["gap"]) => {
+  if (gap === undefined || gap === null) return "0px";
+  return typeof gap === "number" ? `${gap}px` : gap;
+};
+
+const isButtonElement = (
+  child: React.ReactNode
+): child is React.ReactElement<ButtonProps> => isValidElement(child) && child.type === Button;
+
+const mergeButtonProps = (
+  sharedProps: Partial<ButtonProps>,
+  childProps: ButtonProps,
+  className: string
+) => {
+  return {
+    ...sharedProps,
+    ...childProps,
+    className: classNames(sharedProps.className, childProps.className, className),
+  } as ButtonProps;
+};
+
+export const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
+  (
+    {
+      orientation = "horizontal",
+      fullWidth = false,
+      gap,
+      radius,
+      buttonProps,
+      buttons,
+      className,
+      children,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const sharedButtonProps = useMemo(() => {
+      if (!buttonProps && !radius) return undefined;
+      const shared: Partial<ButtonProps> = { ...(buttonProps ?? {}) };
+      if (radius) shared.radius = radius;
+      return shared;
+    }, [buttonProps, radius]);
+
+    const renderedButtons = useMemo(
+      () =>
+        (buttons ?? []).map((button, index) => (
+          <Button key={button.key ?? index} {...button} />
+        )),
+      [buttons]
+    );
+
+    const combinedChildren = useMemo(() => {
+      const baseChildren = Children.toArray(children);
+      if (renderedButtons.length === 0) return baseChildren;
+      return baseChildren.concat(renderedButtons);
+    }, [children, renderedButtons]);
+
+    const totalButtons = useMemo(
+      () => combinedChildren.filter((child) => isButtonElement(child)).length,
+      [combinedChildren]
+    );
+
+    if (combinedChildren.length === 0) return null;
+
+    let buttonIndex = 0;
+    const processedChildren = combinedChildren.map((child) => {
+      if (!isButtonElement(child)) return child;
+
+      const isSingle = totalButtons === 1;
+      const isFirst = buttonIndex === 0;
+      const isLast = buttonIndex === totalButtons - 1;
+      const isMiddle = !isFirst && !isLast;
+      buttonIndex += 1;
+
+      const positionClass = classNames(
+        "solara-button-group__button",
+        !isSingle && isFirst && "solara-button-group__button--first",
+        !isSingle && isMiddle && "solara-button-group__button--middle",
+        !isSingle && isLast && "solara-button-group__button--last"
+      );
+
+      if (!sharedButtonProps) {
+        return cloneElement(child, {
+          ...child.props,
+          className: classNames(child.props.className, positionClass),
+        });
+      }
+
+      return cloneElement(child, mergeButtonProps(sharedButtonProps, child.props, positionClass));
+    });
+
+    const mergedStyle = {
+      ...style,
+    } as React.CSSProperties;
+
+    return (
+      <div
+        ref={ref}
+        className={classNames(
+          "solara-button-group",
+          `solara-button-group--${orientation}`,
+          fullWidth && "solara-button-group--full-width",
+          className
+        )}
+        role="group"
+        aria-orientation={orientation}
+        style={mergedStyle}
+        {...props}
+      >
+        {processedChildren}
+      </div>
+    );
+  }
+);
+
+ButtonGroup.displayName = "ButtonGroup";

package/src/ButtonGroup.types.ts

@@ -0,0 +1,44 @@
+import type React from "react";
+import type { ButtonProps, ButtonRadius } from "@solara/button";
+
+export type ButtonGroupOrientation = "horizontal" | "vertical";
+
+export type ButtonGroupButton = ButtonProps & { key?: React.Key };
+
+export interface ButtonGroupProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+  /**
+   * The orientation of the button group.
+   * @default "horizontal"
+   */
+  orientation?: ButtonGroupOrientation;
+  /**
+   * Whether the button group should take up the full width of its container.
+   * @default false
+   */
+  fullWidth?: boolean;
+  /**
+   * Spacing between buttons. Use `0` for flush edges (default).
+   */
+  gap?: number | string;
+  /**
+   * Override the radius for the grouped buttons.
+   */
+  radius?: ButtonRadius;
+  /**
+   * Props applied to every button in the group. Individual button props win.
+   */
+  buttonProps?: Partial<ButtonProps>;
+  /**
+   * Optional button definitions appended after children.
+   */
+  buttons?: ButtonGroupButton[];
+  /**
+   * Button elements to render inside the group.
+   */
+  children?: React.ReactNode;
+  /**
+   * Optional class name to add to the button group.
+   */
+  className?: string;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { ButtonGroup } from "./ButtonGroup";
+export type {
+  ButtonGroupProps,
+  ButtonGroupButton,
+  ButtonGroupOrientation,
+} from "./ButtonGroup.types";