@poly-x/react 0.1.0-alpha.8 → 0.1.0

package/dist/index.d.cts

@@ -18,6 +18,21 @@ declare function PolyXProvider({
   children
 }: PolyXProviderProps): ReactNode;
 //#endregion
+//#region src/bff-session.d.ts
+interface BffSignOutOptions {
+  /** `everywhere` ends every session for the user (FR-SSO-5). Default `device`. */
+  scope?: "device" | "everywhere";
+  /** Where to land afterwards. Resolved here, client-side — the server takes no redirect target. */
+  redirectTo?: string;
+  /**
+   * Run consumer cleanup after the session is revoked but BEFORE the post-sign-out
+   * redirect (the page is still alive at this point) — e.g. clear app cookies, reset
+   * local state, flush a store. Awaited; a thrown/rejected hook is swallowed so a
+   * failing callback can never trap the user in a signed-out-but-not-redirected state.
+   */
+  onSignOut?: () => void | Promise<void>;
+}
+//#endregion
 //#region src/auth-channel.d.ts
 /**
  * Same-origin popup→opener handoff of the authorization `code` (F006). The
@@ -115,8 +130,11 @@ interface UseAuth {
   isLoaded: boolean;
   isSignedIn: boolean;
   signIn: (options?: SignInOptions) => Promise<void>;
-  signOut: () => Promise<void>;
-  /** Current access token, refreshing if needed; null when signed out. */
+  signOut: (options?: BffSignOutOptions) => Promise<void>;
+  /**
+   * Current access token, refreshing if needed; null when signed out — and always null under
+   * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
+   */
   getToken: () => Promise<string | null>;
 }
 declare function useAuth(): UseAuth;
@@ -201,6 +219,9 @@ interface SignInLabels {
   emailPlaceholder: string;
   passwordLabel: string;
   passwordPlaceholder: string;
+  /** Reveal-toggle a11y labels (aria-label / tooltip on the show-hide button). */
+  showPassword: string;
+  hidePassword: string;
   submit: string;
   submitting: string;
   forgotPassword: string;
@@ -241,6 +262,13 @@ interface SignInProps {
    * "Forgot password?" link appears under the password field. Omit to hide it.
    */
   forgotPasswordUrl?: string;
+  /**
+   * v6 (FR-CNST): capture precise location for security/presence. When enabled, sign-in asks the
+   * browser for a position — the browser's own native permission prompt is the consent gate (no
+   * in-form checkbox), and it's remembered per-origin after the first choice. A block, denial, or
+   * timeout never blocks sign-in (coarse IP fallback). Off by default.
+   */
+  captureLocation?: boolean;
   /** Where to send the browser after success. Overrides the server's default redirect. */
   afterSignInPath?: string;
   /** Pre-scope the login to a single organization (skips org discovery). */
@@ -278,7 +306,13 @@ interface ForgotPasswordLabels {
   submitting: string;
   /** Shown after submit — always, regardless of whether the account exists. */
   sentHeading: string;
-  /** Confirmation body. `{email}` is replaced with the entered address, emphasized. */
+  /**
+   * Confirmation body. `{email}` is replaced with the entered address, emphasized.
+   * Kept deliberately uniform (no account-existence / mail-config signal, per the
+   * anti-enumeration reset design) and points the user at their administrator for
+   * the cases where no mail can arrive (org has reset email disabled, no provider
+   * configured, or a send failure) — none of which the response is allowed to reveal.
+   */
   sentSubheading: string;
   differentEmail: string;
   backToSignIn: string;
@@ -372,6 +406,293 @@ declare function AuthCallback({
   children
 }: AuthCallbackProps): ReactNode;
 //#endregion
+//#region src/geolocation.d.ts
+/**
+ * @poly-x/react/geolocation — browser precise-location capture for sign-in (v6, FR-CNST/FR-LOC).
+ *
+ * The consent-gated bridge to `navigator.geolocation`. It NEVER rejects: a missing API resolves
+ * to `{ consent: "denied" }` with no coordinates so the caller can always proceed — sign-in must
+ * never block on location (D52).
+ *
+ * Consent vs. fix are kept SEPARATE. `consent` reflects the browser PERMISSION decision only:
+ * `denied` means the user actually said no (`PERMISSION_DENIED`). A position that is merely
+ * unavailable or times out (common on desktops with no GPS) is NOT a denial — the user consented,
+ * we just couldn't get coordinates, so consent stays `granted` with no coords and the platform
+ * uses the coarse (IP) fallback. Conflating the two is why an allowed login could be stored as
+ * `denied` + coarse. On a no-fix (not a denial) we retry once at low accuracy (network-based),
+ * which is far more reliable than high-accuracy GPS on desktop browsers.
+ */
+/** Minimal shape of the browser Geolocation API we depend on (injectable for testing). */
+interface GeolocationLike {
+  getCurrentPosition(success: (position: {
+    coords: {
+      latitude: number;
+      longitude: number;
+      accuracy?: number;
+    };
+  }) => void, error?: (err: {
+    code?: number;
+  } | unknown) => void, options?: {
+    enableHighAccuracy?: boolean;
+    timeout?: number;
+    maximumAge?: number;
+  }): void;
+}
+/** The consent-labelled result of a capture attempt. Coordinates present only on a successful fix. */
+interface CapturedGeo {
+  latitude?: string;
+  longitude?: string;
+  accuracyMeters?: number;
+  /** The browser PERMISSION decision only — never downgraded by a failed/timed-out fix. */
+  consent: "granted" | "denied";
+}
+interface CaptureOptions {
+  /** High-accuracy (GPS) attempt budget before the network-based retry. Default 8000ms. */
+  timeoutMs?: number;
+  /** Low-accuracy (network) retry budget when the first attempt gets no fix. Default 12000ms. */
+  fallbackTimeoutMs?: number;
+  /** Override the geolocation source (tests). Defaults to `navigator.geolocation`. */
+  geolocation?: GeolocationLike;
+}
+/**
+ * Capture the browser's precise location. Resolves to a consent-labelled result and never
+ * throws/rejects. High-accuracy first; on a no-fix (not a denial) retries once at low accuracy.
+ */
+declare function capturePreciseLocation(consented: boolean, opts?: CaptureOptions): Promise<CapturedGeo>;
+//#endregion
+//#region src/components/placement.d.ts
+/**
+ * Collision-aware placement for the SDK's popovers.
+ *
+ * A menu pinned to one side is wrong somewhere: an avatar in a page header wants to open
+ * down-and-left, the same component in a sidebar footer has to open up-and-right. Rather than
+ * make every consumer work that out, measure the trigger against the viewport and pick.
+ *
+ * Deliberately hand-rolled: `@poly-x/react` has no runtime dependency but `@poly-x/core`, and a
+ * full positioning engine is a lot of surface to inherit for one menu. The component only needs
+ * to know *which side* — CSS does the actual placing — so this stays a pure function over
+ * rectangles, and is unit-testable without a layout engine.
+ */
+type Side = "top" | "bottom" | "left" | "right";
+type SideOption = Side | "auto";
+type Align = "start" | "center" | "end";
+interface Rect {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+interface Size {
+  width: number;
+  height: number;
+}
+interface Viewport {
+  width: number;
+  height: number;
+}
+/**
+ * Which side the menu should open on.
+ *
+ * An explicit side is honoured when it fits and flipped to its opposite when it doesn't — a
+ * requested side that runs off-screen is a worse answer than the one that doesn't. `auto` takes
+ * the first side that fits, and if none do, the roomiest: something has to be chosen, and the
+ * least-bad option beats an arbitrary default.
+ */
+declare function resolveSide(preferred: SideOption, trigger: Rect, menu: Size, viewport: Viewport, gap?: number): Side;
+//#endregion
+//#region src/components/user-button.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface UserButtonLabels {
+  trigger: string;
+  manageAccount: string;
+  signOut: string;
+  signOutEverywhere: string;
+}
+interface UserButtonActionProps {
+  /**
+   * The menu entry's text — or the name of a built-in (`manageAccount`, `signOut`,
+   * `signOutEverywhere`) to place it at this position instead of appending a second copy.
+   */
+  label: string;
+  /** Icon rendered before the label. */
+  labelIcon?: ReactNode;
+  onClick?: () => void;
+}
+interface UserButtonLinkProps {
+  label: string;
+  labelIcon?: ReactNode;
+  href: string;
+}
+interface UserButtonSlotProps {
+  children?: ReactNode;
+}
+interface UserButtonProps {
+  /** Show the user's name next to the avatar. Default `false`. */
+  showName?: boolean;
+  /** Where to land after signing out. Default the app root. */
+  afterSignOutUrl?: string;
+  /**
+   * Consumer cleanup run after the session is revoked but before the redirect —
+   * clear app cookies, reset local stores, etc. Awaited; errors are swallowed so a
+   * failing hook can't trap the user. Applies to both "Sign out" and "Sign out everywhere".
+   */
+  onSignOut?: () => void | Promise<void>;
+  /**
+   * Destination for the "Manage account" entry. Omitted entirely when unset — PolyX has no
+   * hosted profile page, so the destination is the consumer's to own.
+   */
+  manageAccountUrl?: string;
+  /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
+  showSignOutEverywhere?: boolean;
+  /** Start with the menu open. Default `false`. */
+  defaultOpen?: boolean;
+  /** Rendered while the session resolves, so the header doesn't jump. */
+  fallback?: ReactNode;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  /**
+   * Appended to the trigger button's class list. The SDK owns that button, so without this a
+   * consumer could style everything except the one element they place in their own layout.
+   */
+  triggerClassName?: string;
+  /** Notified when the menu opens or closes — hosts often coordinate their own chrome around it. */
+  onOpenChange?: (open: boolean) => void;
+  labels?: Partial<UserButtonLabels>;
+  /**
+   * `<UserButton.MenuItems>` with `<UserButton.Action>` / `<UserButton.Link>` / `<UserButton.Custom>`
+   * entries, and/or a `<UserButton.Header>` replacing the identity block.
+   */
+  children?: ReactNode;
+  /** Avatar size in pixels. Default 32. */
+  avatarSize?: number;
+  /**
+   * What the trigger shows. Replaces the avatar (and `showName`); the SDK still owns the button
+   * and its menu semantics, so a custom trigger costs no accessibility.
+   */
+  trigger?: ReactNode;
+  /**
+   * Which side the menu opens on. Default `auto` — measured against the viewport, because the
+   * right answer differs by where the trigger sits (a header avatar opens down, a sidebar-footer
+   * one has to open up). An explicit side is flipped only if it would run off-screen.
+   */
+  side?: SideOption;
+  /** Alignment along the chosen side. Default `end`. */
+  align?: Align;
+}
+/**
+ * The signed-in user surface: avatar trigger + a menu with their identity and sign-out
+ * (FR-SIGNIN-6). Reads only the hooks, so it behaves identically under either custody model
+ * — an httpOnly BFF session or an in-memory SPA one — and needs no provider in a
+ * `@poly-x/next` app.
+ *
+ * Custom entries compose declaratively:
+ *
+ * ```tsx
+ * <UserButton manageAccountUrl="/account">
+ *   <UserButton.MenuItems>
+ *     <UserButton.Action label="signOut" />          // reposition a built-in
+ *     <UserButton.Link label="Docs" href="/docs" />
+ *   </UserButton.MenuItems>
+ * </UserButton>
+ * ```
+ */
+declare const UserButton: ((props: UserButtonProps) => ReactNode) & {
+  MenuItems: (props: UserButtonSlotProps) => ReactNode;
+  Action: (props: UserButtonActionProps) => ReactNode;
+  Link: (props: UserButtonLinkProps) => ReactNode; /** Arbitrary JSX as a menu row — bring your own controls. */
+  Custom: (props: UserButtonSlotProps) => ReactNode; /** Replaces the built-in identity block. */
+  Header: (props: UserButtonSlotProps) => ReactNode;
+};
+//#endregion
+//#region src/components/user-avatar.d.ts
+interface UserAvatarProps {
+  /** Image URL. Falls back to initials when absent or when the image fails to load. */
+  src?: string;
+  /** The name initials are derived from; also the image's alt text. */
+  name?: string;
+  /** Pixel size of the (square) avatar. Default 32. */
+  size?: number;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+}
+/**
+ * Up to two initials from a display name. Handles the shapes the platform actually
+ * produces — "Ali Ikram", a bare username, an email address.
+ */
+declare function initialsFrom(name: string | undefined): string;
+/**
+ * The user's picture, or their initials. A missing avatar is the ordinary case rather than
+ * an error, so initials are a first-class state, not a broken image.
+ */
+declare function UserAvatar({
+  src,
+  name,
+  size,
+  className
+}: UserAvatarProps): ReactNode;
+//#endregion
+//#region src/live-authz.d.ts
+/**
+ * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
+ *
+ * Orchestrates the refresh triggers behind ADR-0008/0009: the platform `authz:changed` signal
+ * (instant), window focus / tab-visible, network reconnect, and a **hidden-pausing safety poll**
+ * (~60s) as the staleness ceiling. Every refresh coalesces through a **single-flight** guard;
+ * focus/reconnect are throttled so churn never storms the platform; the push signal is never
+ * throttled (it's an explicit change). The injected `refresh` reports whether claims actually
+ * changed, so `onChanged` (which drives `useAuthzChanged`) fires only on a real change (FR-REACT-5).
+ *
+ * Pure of React — unit-testable with injected window/document + fake timers.
+ */
+interface LiveAuthzOptions {
+  /** Bring claims current; resolves `true` if the claims actually changed. Errors are swallowed
+   *  (keep last-known — FR-LIVE-1 / EC-LIVE-1). */
+  refresh: () => Promise<boolean>;
+  /** Subscribe to the platform `authz:changed` signal; return an unsubscribe fn (ADR-0008). */
+  subscribeSignal?: (onSignal: () => void) => () => void;
+  /** Fired after a triggered refresh that changed claims (drives `useAuthzChanged`). */
+  onChanged?: () => void;
+  /** Background safety-poll interval in ms. Default 60000; `<= 0` disables the poll. */
+  pollMs?: number;
+  /** Throttle window (ms) for focus/reconnect/visibility refreshes. Default 5000. */
+  focusThrottleMs?: number;
+  /** Injectable window (tests). Defaults to the global `window` when present. */
+  win?: Pick<Window, "addEventListener" | "removeEventListener">;
+  /** Injectable document (tests). Defaults to the global `document` when present. */
+  doc?: Pick<Document, "addEventListener" | "removeEventListener"> & {
+    readonly visibilityState: DocumentVisibilityState;
+  };
+}
+interface LiveAuthzHandle {
+  /** Trigger a coalesced refresh immediately (used by the push signal). */
+  refreshNow: () => void;
+  /** Detach every listener + timer. Idempotent. */
+  stop: () => void;
+}
+/** Wire the triggers and return a handle. Safe to call with no window/document (SSR → no-op wiring). */
+declare function startLiveAuthz(opts: LiveAuthzOptions): LiveAuthzHandle;
+//#endregion
+//#region src/live-session.d.ts
+interface UseLiveAuthzOptions {
+  /** Optional push transport (ADR-0008). Omit to run passive-only (focus/reconnect/poll). */
+  subscribeSignal?: LiveAuthzOptions["subscribeSignal"];
+  /** Safety-poll interval (ms). Default 60000; `<= 0` disables. */
+  pollMs?: number;
+  /** Throttle window (ms) for focus/reconnect refreshes. Default 5000. */
+  focusThrottleMs?: number;
+}
+/**
+ * Start the live-authz orchestrator for this app's BFF session. Mount once (e.g. in the app root).
+ * Returns nothing; drives `useUser()` reactivity + fires `useAuthzChanged` callbacks on a change.
+ */
+declare function useLiveAuthz(options?: UseLiveAuthzOptions): void;
+/**
+ * Register a callback fired when the user's authorization changes (FR-REACT-1) — for apps that keep
+ * their own ability/route model and need to re-run their guard or refetch view data. Apps that gate
+ * on `useUser()` do not need this. Requires `useLiveAuthz` to be mounted somewhere in the tree.
+ */
+declare function useAuthzChanged(callback: () => void): void;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -380,4 +701,4 @@ declare function AuthCallback({
 declare const PACKAGE_NAME = "@poly-x/react";
 declare const version = "0.0.0";
 //#endregion
-export { AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };