@poly-x/react 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/index.d.mts

@@ -18,6 +18,14 @@ 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;
+}
+//#endregion
 //#region src/auth-channel.d.ts
 /**
  * Same-origin popup→opener handoff of the authorization `code` (F006). The
@@ -115,8 +123,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;
@@ -191,16 +202,179 @@ declare function Protected({
 }: ProtectedProps): ReactNode;
 //#endregion
 //#region src/components/sign-in.d.ts
-interface SignInProps extends SignInOptions {
-  children?: ReactNode;
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface SignInLabels {
+  heading: string;
+  subheading: string;
+  /** Headline on the `page` variant's brand panel. Empty renders a clean brand panel. */
+  tagline: string;
+  emailLabel: string;
+  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;
+  chooseWorkspace: string;
+  chooseWorkspaceSubheading: string;
+  securedBy: string;
+  setPasswordHeading: string;
+  setPasswordSubheading: string;
+  newPasswordLabel: string;
+  confirmPasswordLabel: string;
+  setPasswordSubmit: string;
+  passwordMismatch: string;
+  weakPassword: string;
+  invalidCredentials: string;
+  noAccess: string;
+  passwordChangeRequired: string;
+  genericError: string;
+}
+/**
+ * `card` renders just the card — drop it into your own layout.
+ * `page` owns the viewport — a split layout with a brand panel beside the form
+ * (the panel collapses away under 64rem, leaving the form on its own).
+ */
+type SignInVariant = "card" | "page";
+interface SignInProps {
+  /** Layout preset. Default `card`. */
+  variant?: SignInVariant;
+  /**
+   * Content for the `page` variant's brand panel. Defaults to your `logo` plus
+   * `labels.tagline`; pass your own node to take the panel over completely.
+   * Ignored by the `card` variant.
+   */
+  panel?: ReactNode;
+  /** BFF endpoint backed by `createAuthHandlers().authenticate`. Default `/api/polyx/authenticate`. */
+  action?: string;
+  /**
+   * URL of your reset flow (where `<ForgotPassword/>` lives). When set, a
+   * "Forgot password?" link appears under the password field. Omit to hide it.
+   */
+  forgotPasswordUrl?: string;
+  /** 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). */
+  organizationCode?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Appended to the root element's class list, for escape-hatch styling. */
   className?: string;
+  labels?: Partial<SignInLabels>;
+  /** Fired when the backend requires the user to set a new password before continuing. */
+  onPasswordChangeRequired?: (userId: string) => void;
 }
-/** Minimal sign-in trigger — popup by default. Style via `className`/children. */
-declare function SignIn({
-  children,
-  className,
-  ...options
-}: SignInProps): ReactNode;
+/**
+ * The embedded, Clerk-style sign-in form (D2b). Renders email/password inside the
+ * consuming app and POSTs to the SDK's BFF (`@poly-x/next` `authenticate`), which
+ * runs the credential authorize server-side and seals an httpOnly session — no
+ * redirect to a hosted PolyX login page, no tokens or credentials in the browser
+ * after submit. Handles the workspace picker (select_tenant) inline.
+ *
+ * Ships styled: `import "@poly-x/react/styles.css"` once, then theme it by
+ * overriding the `--polyx-*` custom properties on any ancestor.
+ */
+declare function SignIn(props: SignInProps): ReactNode;
+//#endregion
+//#region src/components/forgot-password.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface ForgotPasswordLabels {
+  heading: string;
+  subheading: string;
+  emailLabel: string;
+  emailPlaceholder: string;
+  submit: string;
+  submitting: string;
+  /** Shown after submit — always, regardless of whether the account exists. */
+  sentHeading: string;
+  /** Confirmation body. `{email}` is replaced with the entered address, emphasized. */
+  sentSubheading: string;
+  differentEmail: string;
+  backToSignIn: string;
+  securedBy: string;
+  genericError: string;
+}
+interface ForgotPasswordProps {
+  /** BFF endpoint backed by `createAuthHandlers().forgotPassword`. Default `/api/polyx/forgot-password`. */
+  action?: string;
+  /** Where the "back to sign in" link points. Default `/sign-in`. */
+  signInPath?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<ForgotPasswordLabels>;
+}
+/**
+ * The self-service "forgot password" form (poly-x v5 / F040). Renders an email field
+ * inside the consuming app and POSTs to the SDK's BFF (`@poly-x/next` `forgotPassword`),
+ * which asks poly-auth to email a single-use reset link SERVER-SIDE. The response is
+ * always the same — no token, no account-existence signal — so after submit the form
+ * shows an identical "check your email" state whether or not the account exists.
+ *
+ * Reuses the `<SignIn/>` styling: `import "@poly-x/react/styles.css"` once, then theme
+ * via the `--polyx-*` custom properties. Target `.polyx-forgot` for form-specific tweaks.
+ */
+declare function ForgotPassword(props: ForgotPasswordProps): ReactNode;
+//#endregion
+//#region src/components/reset-password.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface ResetPasswordLabels {
+  heading: string;
+  subheading: string;
+  newPasswordLabel: string;
+  confirmPasswordLabel: string;
+  passwordPlaceholder: string;
+  submit: string;
+  submitting: string;
+  successHeading: string;
+  successSubheading: string;
+  invalidHeading: string;
+  invalidSubheading: string;
+  requestNewLink: string;
+  backToSignIn: string;
+  securedBy: string;
+  passwordMismatch: string;
+  weakPassword: string;
+  genericError: string;
+}
+interface ResetPasswordProps {
+  /** BFF endpoint backed by `createAuthHandlers().resetPassword`. Default `/api/polyx/reset-password`. */
+  action?: string;
+  /** The opaque reset token. Defaults to `?token=` from the URL (client-side). */
+  token?: string;
+  /** Where to send the browser after a successful reset. Default `/sign-in`. */
+  afterResetPath?: string;
+  /** Where "request a new link" / "back to sign in" point. Default `/forgot-password` and `/sign-in`. */
+  forgotPasswordPath?: string;
+  signInPath?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Client-side minimum password length (the backend enforces the real floor). Default 8. */
+  minLength?: number;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<ResetPasswordLabels>;
+}
+/**
+ * The reset-completion form (poly-x v5 / F040). Reads the opaque token from the URL,
+ * collects a new password, and POSTs to the SDK's BFF (`@poly-x/next` `resetPassword`),
+ * which redeems the token single-use server-side. The token is never decoded in the
+ * browser — identity, validity, and expiry are all enforced by the backend.
+ *
+ * Reuses the `<SignIn/>` styling: `import "@poly-x/react/styles.css"` once, then theme
+ * via the `--polyx-*` custom properties. Target `.polyx-reset` for form-specific tweaks.
+ */
+declare function ResetPassword(props: ResetPasswordProps): ReactNode;
 //#endregion
 //#region src/components/auth-callback.d.ts
 interface AuthCallbackProps {
@@ -212,6 +386,164 @@ declare function AuthCallback({
   children
 }: AuthCallbackProps): ReactNode;
 //#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;
+  /**
+   * 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;
+  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/index.d.ts
 /**
  * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -220,4 +552,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, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, SessionStoragePkceStore, SignIn, type SignInOptions, type SignInProps, 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, 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, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, WebLocksLock, WindowBrowserBridge, createLoginController, initialsFrom, resolveSide, useAuth, useAuthCallback, useSession, useUser, version };