Add programmatic focus to Button (#2765)

## Summary:
[WB-2038] Add programmatic focus to Button

Issue: WB-2038

## Test plan:
1. Review story for programmatic focus: /?path=/story/packages-button-button--receiving-focus-programmatically&globals=viewport:desktop;
2. Compare to ActivityButton: /?path=/story/packages-button-activitybutton--receiving-focus-programmatically&globals=viewport:desktop;

[WB-2038]: https://khanacademy.atlassian.net/browse/WB-2038?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: marcysutton

Reviewers: beaesguerra

Required Reviewers:

Approved By: beaesguerra

Checks: ✅ 13 checks were successful, ⏭️  5 checks have been skipped, ⏹️  6 checks were cancelled

Pull Request URL: #2765

Author: marcysutton

.changeset/busy-seals-strive.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-button": patch
+---
+
+Add support for programmatic focus

__docs__/wonder-blocks-button/activity-button.stories.tsx

@@ -179,4 +179,10 @@ export const ReceivingFocusProgrammatically: Story = {
         startIcon: magnifyingGlass,
         endIcon: caretRight,
     },
+    parameters: {
+        chromatic: {
+            // Disable since it requires user interaction to see the focus ring.
+            disableSnapshot: true,
+        },
+    },
 };

__docs__/wonder-blocks-button/button.stories.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import {StyleSheet} from "aphrodite";
 import type {Meta, StoryObj} from "@storybook/react";
+import {action} from "@storybook/addon-actions";
 
 import {MemoryRouter} from "react-router-dom";
 import {CompatRouter, Route, Routes} from "react-router-dom-v5-compat";
@@ -10,10 +11,12 @@ import type {StyleDeclaration} from "aphrodite";
 import pencilSimple from "@phosphor-icons/core/regular/pencil-simple.svg";
 import pencilSimpleBold from "@phosphor-icons/core/bold/pencil-simple-bold.svg";
 import plus from "@phosphor-icons/core/regular/plus.svg";
+import magnifyingGlass from "@phosphor-icons/core/regular/magnifying-glass.svg";
+import caretRight from "@phosphor-icons/core/regular/caret-right.svg";
 
 import {View} from "@khanacademy/wonder-blocks-core";
 import {Strut} from "@khanacademy/wonder-blocks-layout";
-import {color, spacing} from "@khanacademy/wonder-blocks-tokens";
+import {color, sizing, spacing} from "@khanacademy/wonder-blocks-tokens";
 import {LabelMedium, LabelLarge} from "@khanacademy/wonder-blocks-typography";
 
 import Button from "@khanacademy/wonder-blocks-button";
@@ -657,3 +660,52 @@ WithRouter.parameters = {
         disableSnapshot: true,
     },
 };
+
+/**
+ * This button can receive focus programmatically. This is useful for cases where
+ * you want to focus the button when the user interacts with another
+ * component, such as a form field or another button.
+ *
+ * To do this, we use a `ref` to the button and call the `focus()` method
+ * on it, so the `ActivityButton` receives focus.
+ */
+export const ReceivingFocusProgrammatically: StoryComponentType = {
+    render: function Render(args) {
+        // This story is used to test the focus ring when the button receives
+        // focus programmatically. The button is focused when the story is
+        // rendered.
+        const buttonRef = React.useRef<HTMLButtonElement | null>(null);
+
+        return (
+            <View style={{gap: sizing.size_160, flexDirection: "row"}}>
+                <Button
+                    {...args}
+                    ref={buttonRef}
+                    onClick={(e) => action("clicked")(e)}
+                />
+                <Button
+                    onClick={() => {
+                        // Focus the button when the button is clicked.
+                        if (buttonRef.current) {
+                            buttonRef.current.focus();
+                        }
+                    }}
+                    kind="secondary"
+                >
+                    Focus on the Button (left)
+                </Button>
+            </View>
+        );
+    },
+    args: {
+        children: "Search",
+        startIcon: magnifyingGlass,
+        endIcon: caretRight,
+    },
+    parameters: {
+        chromatic: {
+            // Disable since it requires user interaction to see the focus ring.
+            disableSnapshot: true,
+        },
+    },
+};

packages/wonder-blocks-button/src/components/button-core.tsx

@@ -64,6 +64,8 @@ const ButtonCore: React.ForwardRefExoticComponent<
         buttonStyles.default,
         disabled && buttonStyles.disabled,
         !disabled && pressed && buttonStyles.pressed,
+        // Enables programmatic focus.
+        !disabled && !pressed && focused && buttonStyles.focused,
         size === "small" && sharedStyles.small,
         size === "large" && sharedStyles.large,
     ];
@@ -231,7 +233,7 @@ const sharedStyles = StyleSheet.create({
     },
 });
 
-type ButtonStylesKey = "default" | "pressed" | "disabled";
+type ButtonStylesKey = "default" | "pressed" | "disabled" | "focused";
 
 const styles: Record<string, Record<ButtonStylesKey, object>> = {};
 
@@ -379,6 +381,8 @@ export const _generateStyles = (
                 : {}),
         },
         pressed: pressStyles,
+        // To receive programmatic focus.
+        focused: focusStyles.focus[":focus-visible"],
         disabled: {
             cursor: "not-allowed",
             ...disabledStatesStyles,