Initial Commit

packages/ui/react/react-ui/src/components/toggle/toggle.variants.md

@@ -0,0 +1,59 @@
+# Toggle Variants (cva config)
+
+## Purpose
+
+`toggleVariants` is the cva (class-variance-authority) configuration powering every `<Toggle>` render. It is split from `toggle.tsx` into its own module so an ejected source copy under `npx shadcn@latest add @suaveplan/toggle` keeps the cva configuration in a dedicated file. Theme overrides flow through `useThemedVariants("Toggle", toggleVariants)`.
+
+## Features
+
+- Two visual variants (`default`, `outline`) covering the upstream shadcn surface.
+- Three sizes (`sm`, `default`, `lg`) for use in dense toolbars or roomy headers.
+- `data-[state=on]:bg-accent data-[state=on]:text-accent-foreground` flips the colour when pressed.
+- `hover:bg-muted hover:text-muted-foreground` for the pointer-hover affordance.
+- `data-icon` slot rules (`[&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0`) so child icons inherit sizing.
+- `disabled:pointer-events-none disabled:opacity-50` for the native disabled state.
+- `motion-reduce:transition-none` for users with `prefers-reduced-motion: reduce`.
+- `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` for keyboard-only focus styling.
+
+## Usage: Basic Example
+
+```ts
+import { toggleVariants } from "@suaveplan/react-ui";
+
+const className = toggleVariants({ variant: "default", size: "default" });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { toggleVariants, cn } from "@suaveplan/react-ui";
+
+export function CustomToggle({ active }: { active: boolean }) {
+    return (
+        <button
+            type="button"
+            aria-pressed={active}
+            data-state={active ? "on" : "off"}
+            className={cn(
+                toggleVariants({ variant: "outline", size: "lg" }),
+                active ? "ring-2 ring-accent" : ""
+            )}
+        >
+            Toggle
+        </button>
+    );
+}
+```
+
+## API Reference
+
+### `toggleVariants(props?: { variant?: "default" | "outline"; size?: "sm" | "default" | "lg" }): string`
+
+Returns the cva-merged class string for the supplied variant + size combination. Both fields are optional; omitted fields fall back to the cva `defaultVariants` (`variant: "default"`, `size: "default"`).
+
+## Implementation Notes
+
+- The resolver is tagged with `componentName: "Toggle"` (non-enumerable, non-writable) via `defineVariants`.
+- The cva config mirrors the visual surface of `<Button>` so toolbars combining `<Button>` + `<Toggle>` look coherent without per-component overrides.
+- The `data-icon` slot rules are duplicated between `<Button>` and `<Toggle>` because both surfaces accept the same icon-as-child pattern; consumers benefit from the consistent sizing.
+- Tokens reference theme-driven CSS custom properties (`bg-accent`, `text-accent-foreground`, `bg-muted`, `text-muted-foreground`) so the colour palette comes from the active `ThemePlugin.cssVariables` payload.