first commit

docs/ui/react/react-auth-whitelabel/src/utils/navigate-or-call.md

@@ -0,0 +1,53 @@
+# `navigateOrCall`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`navigateOrCall(target)` is the canonical helper used by every form
+component in this package to act on a "URL or click handler" prop. The
+forms accept `string | (() => void) | undefined` for affordances like
+`onForgotPassword`, `onRegister`, `onLogin`, etc. This helper centralises
+the three-branch routing so each form does not carry an inline copy of
+the same logic. Treating string values as URLs and function values as
+imperative handlers lets consumers wire either a static href or an
+in-app router callback without changing the component prop signature.
+
+## Features
+
+- String target → `window.location.href = target` (no-op outside a
+  browser).
+- Function target → invoke directly.
+- `undefined` → no-op.
+
+## Usage: Basic
+
+```ts
+navigateOrCall("/login");
+navigateOrCall(() => router.push("/login"));
+navigateOrCall(undefined);
+```
+
+## Usage: Advanced
+
+```tsx
+<button onClick={() => navigateOrCall(props.onLogin)}>
+    Sign in
+</button>
+```
+
+## API Reference
+
+- `navigateOrCall(target: string | (() => void) | undefined): void` —
+  never throws; safely handles non-browser environments by detecting
+  `typeof window`.
+
+## Implementation Notes
+
+The string branch checks `typeof window !== "undefined"` so a server-side
+or test environment that lacks `window` does not crash. The helper does
+not return the target — callers cannot observe whether the navigation
+ran; this matches the imperative redirect semantics expected at every
+call site.