first commit

docs/ui/react/react-ui/src/components/toast/toast.md

@@ -0,0 +1,77 @@
+# `Toast` (legacy alias)
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Case-folded legacy alias for the canonical chassis `toast()` function
+re-exported by `<Sonner>`. Pre-suaveplan consumer code imported a
+capital-T `Toast` named export; the Wave 3g rewrite consolidates onto
+the `sonner`-native lowercase `toast` callable, but the alias survives
+so callers do not have to retire their import statements in lock-step
+with the chassis migration. The two identifiers reference the same
+runtime function — there is zero behavioural difference, and the OTel
+metric attribution is identical.
+
+## Features
+
+- `Toast` === `toast` at runtime (single source, single instrumentation
+  path).
+- Marked `@deprecated` so editor tooling surfaces the migration hint.
+- Slated for removal at `1.0.0`. The alias has zero overhead, so the
+  removal is a SemVer-major churn issue, not a runtime cost issue.
+
+## Usage: Basic Example
+
+```ts
+import { Toast } from "@suaveplan/react-ui";
+
+Toast("Saved");
+Toast.success("Success");
+Toast.error("Failed", { description: "Network error" });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { Toast, toast } from "@suaveplan/react-ui";
+
+// Both identifiers reference the same callable.
+const id = Toast.loading("Working…");
+try {
+    await doWork();
+    toast.success("Done", { id });
+} catch (err) {
+    Toast.error("Failed", { id, description: String(err) });
+}
+```
+
+## API Reference
+
+### `Toast`
+
+`Toast` is `sonner.toast` re-exported via the chassis observability
+shim. The full method surface (`success`, `error`, `info`, `warning`,
+`loading`, `promise`, `dismiss`, `message`, `custom`, `getHistory`,
+`getToasts`) is forwarded.
+
+See `sonner.md` for the canonical API documentation.
+
+### Type re-exports
+
+- `ToastKind` — `'default' | 'success' | 'error' | 'info' | 'warning'`,
+  the discriminator recorded into
+  `react_ui.toast.shown_total{toast.kind=...}`.
+
+## Implementation Notes
+
+- The alias is a single-line re-export. There is no wrapper layer, no
+  forwarder closure, no extra observability hook — keeping the alias
+  cost at zero is the entire point of the file.
+- We DO NOT alias `useToast` to `useSonner` because the chassis
+  `useToast` hook predates sonner and exposes a different shape; the
+  bridge component (`use-toast-sonner-bridge`) handles that contract
+  separately.
+- Removing the alias at `1.0.0` is an explicit deprecation warning so
+  consumers can migrate at their own pace before the major bump.