[docs] Rewrite ButtonGroup docs

packages/core/src/components/button/button-group.md

@@ -1,65 +1,82 @@
 @# Button group
 
-__ButtonGroup__ arranges multiple buttons in a horizontal or vertical group.
-
-@reactExample ButtonGroupExample
+The **ButtonGroup** component arranges related buttons in a horizontal row or
+vertical stack, providing alignment and consistent spacing for a layout of related actions.
 
 @## Usage
 
-Most of __ButtonGroup__'s props are also supported by __Button__ directly; setting these props on __ButtonGroup__ will
-apply the same value to all buttons in the group. Note that most modifiers, once enabled on the group, cannot be
-overridden on child buttons (due to the cascading nature of CSS).
+```ts
+import { ButtonGroup } from "@blueprintjs/core";
+```
 
-The component also supports all HTML `<div>` props.
+@## Basic button group
 
-```tsx
-<ButtonGroup minimal={true} onMouseEnter={...}>
-    <Button icon="database">Queries</Button>
-    <Button icon="function">Functions</Button>
-    <AnchorButton rightIcon="caret-down">Options</AnchorButton>
-</ButtonGroup>
-```
+Wrap buttons in a **ButtonGroup** to arrange them together horizontally.
 
-@## Props interface
+@reactCodeExample ButtonGroupBasicExample
 
-@interface ButtonGroupProps
+@## Intent
 
-@## Usage with popovers
+Use the `intent` prop on individual buttons to convey purpose. For a consistent
+visual style, it’s recommended to apply the same `intent` to all buttons within the same group.
 
-__Button__ elements inside a __ButtonGroup__ can trivially be wrapped with a [__Popover__](#core/components/popover) to
-create complex toolbars.
+@reactCodeExample ButtonGroupIntentExample
 
-@reactExample ButtonGroupPopoverExample
+@## Outlined and minimal
+
+Most of **ButtonGroup**'s props are also supported by **Button** directly.
+Setting these props on **ButtonGroup** will apply the same value to all buttons
+in the group. Note that most modifiers, once enabled on the group, cannot be
+overridden on child buttons (due to the cascading nature of CSS).
+
+@reactCodeExample ButtonGroupVariantsExample
 
 @## Flex layout
 
-__ButtonGroup__ renders a CSS inline flex row (or column if vertical) and provides some modifer props for common
-flexbox patterns:
+**ButtonGroup** renders a CSS flex row (or column if `vertical` is enabled) and
+includes modifier props for common flexbox patterns:
 
-- Enable the `fill` prop on a button group to make all buttons expand equally to
-  fill the available space.
-    - Buttons will expand horizontally by default, or vertically if the `vertical` prop is enabled.
-    - Add the class `Classes.FIXED` to individual buttons to revert them to their initial sizes.
+-   Use the `fill` prop to make all buttons expand equally to fill the available space.
+    -   Buttons will expand horizontally by default or vertically if `vertical` is enabled.
+    -   Add the `Classes.FIXED` class to specific buttons to maintain their initial sizes.
+-   Alternatively, enable `fill` on specific buttons to selectively expand them while others retain their original size.
 
-- Alternatively, enable the `fill` prop on specific buttons (instead of on the
-  group) to expand them equally to fill the available space while other
-  buttons retain their original sizes.
+For precise size adjustments, use the `flex-basis` or `width` CSS properties on individual buttons.
 
-You can adjust the specific size of a button with the `flex-basis` or `width` CSS properties.
+@reactCodeExample ButtonGroupFlexExample
 
 @## Vertical layout
 
-Buttons in a vertical group all have the same width as the widest button in the group.
+Enable the `vertical` prop to stack buttons vertically. Buttons in a vertical
+group automatically adjust to the width of the widest button in the group.
+
+Use the `alignText` prop to control text and icon alignment within the buttons.
+Set it at the group level for uniform alignment or on individual buttons for specific adjustments.
 
-Use the `alignText` prop to control icon and text alignment in the buttons. Set this prop on __ButtonGroup__ to affect
-all buttons in the group, or set the prop on individual buttons directly.
+@reactCodeExample ButtonGroupVerticalExample
+
+@## Usage with popovers
+
+**Button** elements inside a **ButtonGroup** can be wrapped with a
+[**Popover**](#core/components/popover) to create complex toolbars.
+
+@reactExample ButtonGroupPopoverExample
+
+@## Interactive Playground
+
+@reactExample ButtonGroupPlaygroundExample
+
+@## Props interface
+
+@interface ButtonGroupProps
 
 @## CSS API
 
 <div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign @ns-callout-has-body-content">
     <h5 class="@ns-heading">
 
 Deprecated API: use [`<ButtonGroup>`](#core/components/button-group)
+
 </h5>
 
 CSS APIs for Blueprint components are considered deprecated, as they are verbose, error-prone, and they

packages/docs-app/src/examples/core-examples/buttonExamples.tsx

@@ -2,6 +2,7 @@
  * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
  */
 
+import dedent from "dedent";
 import * as React from "react";
 
 import { AnchorButton, Button, Icon, Tooltip } from "@blueprintjs/core";
@@ -17,10 +18,11 @@ export const ButtonBasicExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonIntentExample: React.FC<ExampleProps> = props => {
-    const code = `<Button text="Primary" intent="primary" />
-<Button text="Success" intent="success" />
-<Button text="Warning" intent="warning" />
-<Button text="Danger" intent="danger" />`;
+    const code = dedent`
+        <Button text="Primary" intent="primary" />
+        <Button text="Success" intent="success" />
+        <Button text="Warning" intent="warning" />
+        <Button text="Danger" intent="danger" />`;
     return (
         <CodeExample code={code} {...props}>
             <Button text="Primary" intent="primary" />
@@ -32,9 +34,10 @@ export const ButtonIntentExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonMinimalExample: React.FC<ExampleProps> = props => {
-    const code = `<Button text="Minimal" minimal={true} />
-<Button text="Primary" minimal={true} intent="primary" />
-<Button text="Disabled" minimal={true} disabled={true} />`;
+    const code = dedent`
+        <Button text="Minimal" minimal={true} />
+        <Button text="Primary" minimal={true} intent="primary" />
+        <Button text="Disabled" minimal={true} disabled={true} />`;
     return (
         <CodeExample code={code} {...props}>
             <Button text="Minimal" minimal={true} />
@@ -45,9 +48,10 @@ export const ButtonMinimalExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonOutlinedExample: React.FC<ExampleProps> = props => {
-    const code = `<Button text="Outlined" outlined={true} />
-<Button text="Primary" outlined={true} intent="primary" />
-<Button text="Disabled" minimal={true} disabled={true} />`;
+    const code = dedent`
+        <Button text="Outlined" outlined={true} />
+        <Button text="Primary" outlined={true} intent="primary" />
+        <Button text="Disabled" minimal={true} disabled={true} />`;
     return (
         <CodeExample code={code} {...props}>
             <Button text="Outlined" outlined={true} />
@@ -58,9 +62,10 @@ export const ButtonOutlinedExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonSizeExample: React.FC<ExampleProps> = props => {
-    const code = `<Button text="Small" small={true} />
-<Button text="Default" />
-<Button text="Large" large={true} />`;
+    const code = dedent`
+        <Button text="Small" small={true} />
+        <Button text="Default" />
+        <Button text="Large" large={true} />`;
     return (
         <CodeExample code={code} {...props}>
             <Button text="Small" small={true} />
@@ -80,9 +85,10 @@ export const ButtonFillExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonAlignTextExample: React.FC<ExampleProps> = props => {
-    const code = `<Button text="Left Aligned" alignText="left" icon="align-left" rightIcon="caret-down" />
-<Button text="Center Aligned" alignText="center" icon="align-center" rightIcon="caret-down" />
-<Button text="Right Aligned" alignText="right" icon="align-right" rightIcon="caret-down" />`;
+    const code = dedent`
+        <Button text="Left Aligned" alignText="left" icon="align-left" rightIcon="caret-down" />
+        <Button text="Center Aligned" alignText="center" icon="align-center" rightIcon="caret-down" />
+        <Button text="Right Aligned" alignText="right" icon="align-right" rightIcon="caret-down" />`;
     return (
         <CodeExample code={code} {...props}>
             <Button text="Left Aligned" alignText="left" icon="align-left" rightIcon="caret-down" />
@@ -102,12 +108,13 @@ export const ButtonEllipsizeTextExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonIconWithTextExample: React.FC<ExampleProps> = props => {
-    const code = `<Button icon="refresh" intent="danger" text="Reset" />
-<Button icon="user" rightIcon="caret-down" text="Profile settings" />
-<Button rightIcon="arrow-right" intent="success" text="Next step" />
-<Button>
-    <Icon icon="document" /> Upload... <Icon icon="small-cross" />
-</Button>`;
+    const code = dedent`
+        <Button icon="refresh" intent="danger" text="Reset" />
+        <Button icon="user" rightIcon="caret-down" text="Profile settings" />
+        <Button rightIcon="arrow-right" intent="success" text="Next step" />
+        <Button>
+            <Icon icon="document" /> Upload... <Icon icon="small-cross" />
+        </Button>`;
     return (
         <CodeExample code={code} {...props}>
             <Button icon="refresh" intent="danger" text="Reset" />
@@ -121,11 +128,12 @@ export const ButtonIconWithTextExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonIconExample: React.FC<ExampleProps> = props => {
-    const code = `<Button icon="edit" aria-label="edit" />
-<Button icon="share" outlined={true} aria-label="share" />
-<Button icon="filter" intent="primary" minimal={true} aria-label="filter" />
-<Button icon="add" intent="success" aria-label="add" />
-<Button icon="trash" disabled={true} intent="danger" aria-label="delete" />`;
+    const code = dedent`
+        <Button icon="edit" aria-label="edit" />
+        <Button icon="share" outlined={true} aria-label="share" />
+        <Button icon="filter" intent="primary" minimal={true} aria-label="filter" />
+        <Button icon="add" intent="success" aria-label="add" />
+        <Button icon="trash" disabled={true} intent="danger" aria-label="delete" />`;
     return (
         <CodeExample code={code} {...props}>
             <Button icon="edit" aria-label="edit" />
@@ -138,10 +146,11 @@ export const ButtonIconExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonStatesExample: React.FC<ExampleProps> = props => {
-    const code = `<Button text="Default" />
-<Button text="Active" active={true} />
-<Button text="Disabled" disabled={true} />
-<Button text="Loading..." loading={true} />`;
+    const code = dedent`
+        <Button text="Default" />
+        <Button text="Active" active={true} />
+        <Button text="Disabled" disabled={true} />
+        <Button text="Loading..." loading={true} />`;
     return (
         <CodeExample code={code} {...props}>
             <Button text="Default" />
@@ -162,9 +171,10 @@ export const ButtonAnchorButtonExample: React.FC<ExampleProps> = props => {
 };
 
 export const ButtonDisabledButtonTooltipExample: React.FC<ExampleProps> = props => {
-    const code = `<Tooltip content="This button is disabled">
-    <AnchorButton text="Disabled" disabled={true} />
-</Tooltip>`;
+    const code = dedent`
+        <Tooltip content="This button is disabled">
+            <AnchorButton text="Disabled" disabled={true} />
+        </Tooltip>`;
     return (
         <CodeExample code={code} {...props}>
             <Tooltip content="This button is disabled">

packages/docs-app/src/examples/core-examples/buttonGroupExamples.tsx

@@ -0,0 +1,127 @@
+/* !
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ */
+
+import dedent from "dedent";
+import * as React from "react";
+
+import { Button, ButtonGroup } from "@blueprintjs/core";
+import { CodeExample, type ExampleProps } from "@blueprintjs/docs-theme";
+
+export const ButtonGroupBasicExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <ButtonGroup>
+            <Button text="One" />
+            <Button text="Two" />
+            <Button text="Three" />
+        </ButtonGroup>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <ButtonGroup>
+                <Button text="One" />
+                <Button text="Two" />
+                <Button text="Three" />
+            </ButtonGroup>
+        </CodeExample>
+    );
+};
+
+export const ButtonGroupIntentExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <ButtonGroup>
+            <Button intent="primary" text="One" />
+            <Button intent="primary" text="Two" />
+            <Button intent="primary" text="Three" />
+        </ButtonGroup>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <ButtonGroup>
+                <Button intent="primary" text="One" />
+                <Button intent="primary" text="Two" />
+                <Button intent="primary" text="Three" />
+            </ButtonGroup>
+        </CodeExample>
+    );
+};
+
+export const ButtonGroupVariantsExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <ButtonGroup outlined={true}>
+            <Button text="One" />
+            <Button text="Two" />
+            <Button text="Three" />
+        </ButtonGroup>
+        <ButtonGroup minimal={true}>
+            <Button text="One" />
+            <Button text="Two" />
+            <Button text="Three" />
+        </ButtonGroup>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <ButtonGroup outlined={true}>
+                <Button text="One" />
+                <Button text="Two" />
+                <Button text="Three" />
+            </ButtonGroup>
+            <ButtonGroup minimal={true}>
+                <Button text="One" />
+                <Button text="Two" />
+                <Button text="Three" />
+            </ButtonGroup>
+        </CodeExample>
+    );
+};
+
+export const ButtonGroupFlexExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <ButtonGroup fill={true}>
+            <Button text="One" />
+            <Button text="Two" />
+            <Button text="Three" />
+        </ButtonGroup>
+        <ButtonGroup fill={true}>
+            <Button fill={true} intent="primary" text="Select one" />
+            <Button icon="caret-down" intent="primary" aria-label="More" />
+        </ButtonGroup>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <ButtonGroup fill={true}>
+                <Button text="One" />
+                <Button text="Two" />
+                <Button text="Three" />
+            </ButtonGroup>
+            <ButtonGroup fill={true}>
+                <Button fill={true} intent="primary" text="Select one" />
+                <Button icon="caret-down" intent="primary" aria-label="More" />
+            </ButtonGroup>
+        </CodeExample>
+    );
+};
+
+export const ButtonGroupVerticalExample: React.FC<ExampleProps> = props => {
+    const code = dedent`
+        <ButtonGroup vertical={true}>
+            <Button text="One" />
+            <Button text="Two" />
+            <Button text="Three" />
+        </ButtonGroup>
+        <ButtonGroup outlined={true} vertical={true}>
+            <Button alignText="left" icon="align-left" text="Left" />
+            <Button alignText="center" icon="align-center" text="Center" />
+            <Button alignText="right" rightIcon="align-right" text="Right" />
+        </ButtonGroup>`;
+    return (
+        <CodeExample code={code} {...props}>
+            <ButtonGroup vertical={true}>
+                <Button text="One" />
+                <Button text="Two" />
+                <Button text="Three" />
+            </ButtonGroup>
+            <ButtonGroup outlined={true} vertical={true}>
+                <Button alignText="left" icon="align-left" text="Left" />
+                <Button alignText="center" icon="align-center" text="Center" />
+                <Button alignText="right" rightIcon="align-right" text="Right" />
+            </ButtonGroup>
+        </CodeExample>
+    );
+};