chore(docs): added SpinButton docs

Author: mlaursen

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/ControllingTheValueExample.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { SpinButton } from "@react-md/core/spinbutton/SpinButton";
+import { type SpinButtonValue } from "@react-md/core/spinbutton/types";
+import { Typography } from "@react-md/core/typography/Typography";
+import { type ReactElement, useState } from "react";
+
+export default function ControllingTheValueExample(): ReactElement {
+  const [value, setValue] = useState<SpinButtonValue>(null);
+  return (
+    <>
+      <SpinButton
+        aria-label="Example"
+        value={value}
+        min={0}
+        max={10}
+        minDigits={2}
+        onValueChange={({ value }) => setValue(value)}
+      />
+      <Typography>Current value: {`"${value}"`}</Typography>
+    </>
+  );
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/OnValueChangeCallbackExample.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import { SpinButton } from "@react-md/core/spinbutton/SpinButton";
+import { type SpinButtonValue } from "@react-md/core/spinbutton/types";
+import { Typography } from "@react-md/core/typography/Typography";
+import { type ReactElement, useState } from "react";
+
+export default function OnValueChangeCallbackExample(): ReactElement {
+  const [value, setValue] = useState<SpinButtonValue>(0);
+
+  return (
+    <>
+      <Typography>Current value: {`"${value}"`}</Typography>
+      <SpinButton
+        aria-label="Minutes"
+        min={0}
+        max={59}
+        fallback="MM"
+        defaultValue={0}
+        onValueChange={(options) => {
+          const { reason, value } = options;
+          if (reason !== "type") {
+            setValue(value);
+          }
+        }}
+      />
+    </>
+  );
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/RangedSpinButtonExample.tsx

@@ -0,0 +1,6 @@
+import { SpinButton } from "@react-md/core/spinbutton/SpinButton";
+import { type ReactElement } from "react";
+
+export default function RangedSpinButtonExample(): ReactElement {
+  return <SpinButton aria-label="Range Example" min={0} max={10} />;
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/SimpleExample.tsx

@@ -0,0 +1,6 @@
+import { SpinButton } from "@react-md/core/spinbutton/SpinButton";
+import { type ReactElement } from "react";
+
+export default function SimpleExample(): ReactElement {
+  return <SpinButton aria-label="Simple Example" />;
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/SpinButtonGroupExample.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { Box } from "@react-md/core/box/Box";
+import { SpinButton } from "@react-md/core/spinbutton/SpinButton";
+import { SpinButtonGroupProvider } from "@react-md/core/spinbutton/SpinButtonGroupProvider";
+import { useSpinButtonGroupProvider } from "@react-md/core/spinbutton/useSpinButtonGroupProvider";
+import { type ReactElement } from "react";
+
+export default function SpinButtonGroupExample(): ReactElement {
+  const { movementProps, movementContext } = useSpinButtonGroupProvider();
+  return (
+    <Box {...movementProps}>
+      <SpinButtonGroupProvider value={movementContext}>
+        <SpinButton aria-label="Hours" min={1} max={12} fallback="hh" />:
+        <SpinButton aria-label="Minutes" min={0} max={59} fallback="mm" />:
+        <SpinButton aria-label="Seconds" min={0} max={59} fallback="ss" />
+      </SpinButtonGroupProvider>
+    </Box>
+  );
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/UsingAFallbackExample.tsx

@@ -0,0 +1,22 @@
+import { SpinButton } from "@react-md/core/spinbutton/SpinButton";
+import { type ReactElement } from "react";
+
+export default function UsingAFallbackExample(): ReactElement {
+  return (
+    <>
+      <SpinButton aria-label="Fallback Example" min={1} />
+      <SpinButton
+        aria-label="Fallback Example"
+        min={1}
+        max={12}
+        minDigits={2}
+      />
+      <SpinButton
+        aria-label="Custom Fallback Example"
+        fallback="HH"
+        min={1}
+        max={12}
+      />
+    </>
+  );
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/layout.scss

@@ -0,0 +1,17 @@
+@use "everything";
+
+div[role="spinbutton"] {
+  @include everything.divider-border-style;
+  @include everything.interaction-outline;
+
+  align-items: center;
+  display: inline-flex;
+  justify-content: center;
+  min-height: 3rem;
+  min-width: 3rem;
+  padding: 0.5rem;
+
+  &:focus-visible {
+    @include everything.interaction-focus-styles;
+  }
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/layout.tsx

@@ -0,0 +1,13 @@
+import { type ReactElement, type ReactNode } from "react";
+
+import "./layout.scss";
+
+export interface LayoutProps {
+  children: ReactNode;
+}
+
+export default function Layout({
+  children,
+}: Readonly<LayoutProps>): ReactElement {
+  return <>{children}</>;
+}

apps/docs/src/app/(main)/(markdown)/(demos)/components/spin-button/page.mdx

@@ -0,0 +1,103 @@
+---
+title: Spin Button
+description: The SpinButton component can be used to implement the spinbutton role when a <TextField type="number" /> cannot be used.
+docType: Demo
+docGroup: Components
+group: Inputs
+components: [SpinButton, SpinButtonGroup, SpinButtonGroupProvider]
+hooks: [useSpinButton, useSpinButtonProvider]
+---
+
+# Spin Button
+
+> !Info! In most cases, use the [NumberField](/components/text-field#number) instead.
+
+The `SpinButton` component can be used to implement the
+[`spinbutton` role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/spinbutton_role).
+when a `<TextField type="number" />` cannot be used. The `SpinButton` does not have styles
+by default and will need to be provided manually.
+
+To help with the demos on this page, the following styles have been applied:
+
+```import source="./layout.scss"
+
+```
+
+## Simple SpinButton
+
+A `SpinButton` has no styles by default and requires an `aria-label` or
+`aria-labelledby` for accessibility. The value can be changed by:
+
+- using the `ArrowUp` or `ArrowDown` keys
+- typing a number
+- clearing the field with `Backspace` or `Delete`
+
+Any non-digit keys will be ignored.
+
+> !Info! All `SpinButton` on this page will be updated to have minimal styles
+> to help show the component.
+
+```demo source="./SimpleExample.tsx"
+
+```
+
+### Ranged SpinButton
+
+It is recommended to provide the `min` and `max` props to improve accessibility
+and limit the range. This also adds support for updating the value using the
+`Home` and `End` keys and will prevent the user from typing values outside of
+this range.
+
+```demo source="./RangedSpinButtonExample.tsx"
+
+```
+
+## Using a Fallback
+
+In the previous examples, the `SpinButton` content was either empty, a hyphen,
+or the current value. When there is no value, the `SpinButton` has a few
+default text content:
+
+- if `minDigits` is provided, return `-` for each digit
+- if `min` is provided, return `-` for each digit
+- if `fallback` is provided, use that value
+- otherwise, return an empty string
+
+```demo source="./UsingAFallbackExample.tsx"
+
+```
+
+## Controlling the value
+
+The value can be controlled by providing a `value` and `onValueChange`. The
+`onValueChange` callback provides an object with:
+
+- `event` - either a `KeyboardEvent`, `FormEvent`, or `FocusEvent`
+- `reason` - either `"type"`, `"cleared"`, `"typed-to-completion"`, or `"change"`
+- `value` - the next value
+
+```demo source="./ControllingTheValueExample.tsx"
+
+```
+
+### Setting a default value
+
+An alternative to controlling the value is to use a `defaultValue` instead.
+This can be useful alongside the `onValueChange` callback to only update a
+local state value when a specific change reason occurs.
+
+```demo source="./OnValueChangeCallbackExample.tsx"
+
+```
+
+## SpinButtonGroup Example
+
+When multiple `SpinButton` should be used together to create a single value,
+use the `SpinButtonGroupProvider` and `useSpinButtonGroupProvider` as a wrapper
+for the `SpinButton` components. When the user triggers the
+`"typed-to-completion"` event, the next `SpinButton` will automatically be
+focused.
+
+```demo source="./SpinButtonGroupExample.tsx"
+
+```

apps/docs/src/components/MainLayout/navItems.ts

@@ -123,6 +123,11 @@ export const navItems: readonly NavigationItem[] = [
         href: "/slider",
         children: "Slider",
       },
+      {
+        type: "route",
+        href: "/spin-button",
+        children: "SpinButton",
+      },
       {
         type: "route",
         href: "/switch",