Add onMouseDown / onMouseDown / onMouseLeave to ActivityButton and Button (#2763)

## Summary:
Adds support for mouse events for advanced animation purposes

Issue: WB-2006

## Test plan:
1. Review new `ActivityButton` story: /?path=/story/packages-button-activitybutton--press-duration-tracking&globals=viewport:desktop
2. Review new `Button` story: `/?path=/story/packages-button-button--press-duration-tracking`
3. Ensure tests pass

Author: marcysutton

Reviewers: marcysutton, beaesguerra

Required Reviewers:

Approved By: beaesguerra

Checks: ✅ 12 checks were successful, ⏭️  2 checks have been skipped

Pull Request URL: #2763

Author: marcysutton

.changeset/dirty-toys-dance.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-button": minor
+---
+
+Add onMouseUp, onMouseDown, and onMouseLeave to ActivityButton and Button to track duration of press before release

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

@@ -4,9 +4,11 @@ import type {Meta, StoryObj} from "@storybook/react";
 
 import magnifyingGlass from "@phosphor-icons/core/regular/magnifying-glass.svg";
 import caretRight from "@phosphor-icons/core/regular/caret-right.svg";
+import clock from "@phosphor-icons/core/regular/clock.svg";
 
 import {action} from "@storybook/addon-actions";
 import {View} from "@khanacademy/wonder-blocks-core";
+import {BodyText} from "@khanacademy/wonder-blocks-typography";
 import Button, {ActivityButton} from "@khanacademy/wonder-blocks-button";
 
 import ComponentInfo from "../components/component-info";
@@ -186,3 +188,197 @@ export const ReceivingFocusProgrammatically: Story = {
         },
     },
 };
+
+/**
+ * This story demonstrates how to use the mouse event handlers (`onMouseDown`,
+ * `onMouseUp`, and `onMouseLeave`) to track the duration of button presses.
+ *
+ * This is useful for analytics, accessibility features, or UI feedback that
+ * depends on how long a user interacts with a button.
+ *
+ * **Use cases:**
+ * - Measuring engagement time before click completion
+ * - Detecting accidental clicks vs intentional presses
+ * - Providing haptic feedback based on press duration
+ * - Analytics tracking for user interaction patterns
+ *
+ * **Try it:** Press and hold the button for different lengths of time, or
+ * press and drag away from the button to see how the events are tracked.
+ */
+export const PressDurationTracking: Story = {
+    render: function Render(args) {
+        const [pressStartTime, setPressStartTime] = React.useState<
+            number | null
+        >(null);
+        const [pressDuration, setPressDuration] = React.useState<number | null>(
+            null,
+        );
+        const [lastEvent, setLastEvent] = React.useState<string>("none");
+        const [interactionHistory, setInteractionHistory] = React.useState<
+            string[]
+        >([]);
+
+        const logEvent = (eventName: string, duration?: number) => {
+            const timestamp = new Date().toLocaleTimeString();
+            const message =
+                duration !== undefined
+                    ? `${timestamp}: ${eventName} (${duration}ms)`
+                    : `${timestamp}: ${eventName}`;
+
+            setInteractionHistory((prev) => [message, ...prev.slice(0, 4)]); // Keep last 5 events
+            setLastEvent(eventName);
+        };
+
+        const baseActions = {
+            onMouseDown: action("onMouseDown"),
+            onMouseUp: action("onMouseUp"),
+            onMouseLeave: action("onMouseLeave"),
+            onClick: action("onClick"),
+            onMouseEnter: action("onMouseEnter"),
+        };
+
+        const handleMouseDown = (e: React.MouseEvent) => {
+            const startTime = Date.now();
+            setPressStartTime(startTime);
+            setPressDuration(null);
+            logEvent("Mouse Down - Press Started");
+            baseActions.onMouseDown?.(e);
+        };
+
+        const handleMouseUp = (e: React.MouseEvent) => {
+            if (pressStartTime) {
+                const duration = Date.now() - pressStartTime;
+                setPressDuration(duration);
+                logEvent("Mouse Up - Press Completed", duration);
+            }
+            baseActions.onMouseUp?.(e);
+        };
+
+        const handleMouseEnter = (e: React.MouseEvent) => {
+            logEvent("Mouse Enter");
+            baseActions.onMouseEnter?.(e);
+        };
+
+        const handleMouseLeave = (e: React.MouseEvent) => {
+            if (pressStartTime) {
+                const duration = Date.now() - pressStartTime;
+                setPressDuration(duration);
+                logEvent("Mouse Leave - Press Abandoned", duration);
+            }
+            setPressStartTime(null);
+            baseActions.onMouseLeave?.(e);
+        };
+
+        const handleClick = (e: React.SyntheticEvent) => {
+            logEvent("Click - Action Executed");
+            baseActions.onClick?.(e);
+        };
+
+        const resetTracking = () => {
+            setPressStartTime(null);
+            setPressDuration(null);
+            setLastEvent("none");
+            setInteractionHistory([]);
+        };
+
+        const isCurrentlyPressed =
+            pressStartTime !== null &&
+            lastEvent === "Mouse Down - Press Started";
+
+        return (
+            <View style={{gap: sizing.size_240}}>
+                <View
+                    style={{
+                        gap: sizing.size_160,
+                        flexDirection: "row",
+                        alignItems: "center",
+                    }}
+                >
+                    <ActivityButton
+                        {...args}
+                        startIcon={clock}
+                        onMouseEnter={handleMouseEnter}
+                        onMouseDown={handleMouseDown}
+                        onMouseUp={handleMouseUp}
+                        onMouseLeave={handleMouseLeave}
+                        onClick={handleClick}
+                    >
+                        {isCurrentlyPressed
+                            ? "Pressed!"
+                            : "Track Press Duration"}
+                    </ActivityButton>
+
+                    <Button
+                        kind="secondary"
+                        size="small"
+                        onClick={resetTracking}
+                    >
+                        Reset
+                    </Button>
+                </View>
+
+                <View
+                    style={{
+                        gap: sizing.size_120,
+                        padding: sizing.size_160,
+                        backgroundColor:
+                            semanticColor.core.background.neutral.subtle,
+                        borderRadius: sizing.size_080,
+                        minHeight: "120px",
+                    }}
+                >
+                    <BodyText size="medium" weight="semi">
+                        Press Tracking Information
+                    </BodyText>
+
+                    <View style={{gap: sizing.size_060}}>
+                        <BodyText>
+                            <strong>Current State:</strong>{" "}
+                            {isCurrentlyPressed
+                                ? `Pressed (${pressStartTime ? Math.round((Date.now() - pressStartTime) / 10) * 10 : 0}ms+)`
+                                : "Released"}
+                        </BodyText>
+
+                        {pressDuration !== null && (
+                            <BodyText>
+                                <strong>Last Press Duration:</strong>{" "}
+                                {pressDuration}ms
+                            </BodyText>
+                        )}
+
+                        <BodyText>
+                            <strong>Last Event:</strong> {lastEvent}
+                        </BodyText>
+                    </View>
+
+                    {interactionHistory.length > 0 && (
+                        <View style={{gap: sizing.size_040}}>
+                            <BodyText weight="semi">Recent Events:</BodyText>
+                            {interactionHistory.map((event, index) => (
+                                <BodyText
+                                    key={index}
+                                    size="small"
+                                    style={{
+                                        opacity: 1 - index * 0.15,
+                                        fontFamily: "monospace",
+                                    }}
+                                >
+                                    {event}
+                                </BodyText>
+                            ))}
+                        </View>
+                    )}
+                </View>
+            </View>
+        );
+    },
+    args: {
+        kind: "primary",
+    },
+    parameters: {
+        chromatic: {
+            // Disable snapshots since this story is interactive and shows timing
+            disableSnapshot: true,
+        },
+    },
+};

__docs__/wonder-blocks-button/button-shared.argtypes.ts

@@ -44,6 +44,42 @@ export default {
             },
         },
     },
+    onMouseDown: {
+        action: "onMouseDown",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: React.MouseEvent) => unknown",
+            },
+        },
+    },
+    onMouseUp: {
+        action: "onMouseUp",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: React.MouseEvent) => unknown",
+            },
+        },
+    },
+    onMouseEnter: {
+        action: "onMouseEnter",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: React.MouseEvent) => unknown",
+            },
+        },
+    },
+    onMouseLeave: {
+        action: "onMouseLeave",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: React.MouseEvent) => unknown",
+            },
+        },
+    },
     /**
      * Navigation
      */