@poly-x/react 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -136,6 +136,16 @@ interface UseAuth {
    * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
    */
   getToken: () => Promise<string | null>;
+  /**
+   * Re-read the session's authorization from the server and resolve whether it actually
+   * changed (FR-CLIENT-3).
+   *
+   * This capability already existed on the BFF store but was not reachable from the public
+   * surface, so both consuming apps wrote their own refresher — and they already differ:
+   * one treats a module change as an authorization change, the other only a permission
+   * change. Pair it with `useLiveAuthz`/`startLiveAuthz`, which single-flights callers.
+   */
+  refresh: () => Promise<boolean>;
 }
 declare function useAuth(): UseAuth;
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
@@ -239,6 +249,8 @@ interface SignInLabels {
   noAccess: string;
   passwordChangeRequired: string;
   genericError: string;
+  /** Reserved second-factor step (F020). Unreachable until MFA ships. */
+  verificationRequired?: string;
 }
 /**
  * `card` renders just the card — drop it into your own layout.
@@ -500,6 +512,70 @@ interface Viewport {
  */
 declare function resolveSide(preferred: SideOption, trigger: Rect, menu: Size, viewport: Viewport, gap?: number): Side;
 //#endregion
+//#region src/components/user-profile.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling (FR-BRAND-4). */
+interface UserProfileLabels {
+  trigger: string;
+  title: string;
+  description: string;
+  firstName: string;
+  lastName: string;
+  phoneNumber: string;
+  cnic: string;
+  gender: string;
+  photo: string;
+  changePhoto: string;
+  optional: string;
+  save: string;
+  saving: string;
+  cancel: string;
+  close: string;
+  loading: string;
+  loadFailed: string;
+  saveFailed: string;
+  saved: string;
+  signedOut: string;
+  genderUnset: string;
+  genderMale: string;
+  genderFemale: string;
+  genderOther: string;
+}
+interface UserProfileProps {
+  /** Replaces the trigger's contents. The SDK still owns the button and its dialog semantics. */
+  trigger?: ReactNode;
+  /** Render no trigger at all and control the dialog from outside (`open` / `onOpenChange`). */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Notified after a successful save, with the saved profile (FR-PROF-10). */
+  onSaved?: (user: Record<string, unknown>) => void;
+  /** Appended to the root element's class list. */
+  className?: string;
+  /** Appended to the trigger button's class list — the element a consumer places in their layout. */
+  triggerClassName?: string;
+  /** Appended to the dialog's class list. */
+  dialogClassName?: string;
+  labels?: Partial<UserProfileLabels>;
+}
+/**
+ * The signed-in person's own profile, as a dialog (v0.4 / FR-PROF).
+ *
+ * Every application that wanted this had to build the same four things: a form, a validation
+ * ruleset guessed at from error messages, a file upload, and — because the browser holds no
+ * credential under BFF custody — a server route to carry the call. The last of those is
+ * security-adjacent work that had no business being duplicated per app.
+ *
+ * The credential never comes near this component: it posts to the SDK's own route, which
+ * attaches the session server-side and takes the identity from the sealed session rather than
+ * from anything sent here. This surface cannot be aimed at another person's profile even if a
+ * caller tries (FR-CUSTODY-4 / D24).
+ *
+ * ```tsx
+ * <UserProfile onSaved={() => router.refresh()} />
+ * ```
+ */
+declare function UserProfile(props: UserProfileProps): ReactNode;
+//#endregion
 //#region src/components/user-button.d.ts
 /** Every user-facing string, overridable for i18n / white-labelling. */
 interface UserButtonLabels {
@@ -542,6 +618,17 @@ interface UserButtonProps {
    * hosted profile page, so the destination is the consumer's to own.
    */
   manageAccountUrl?: string;
+  /**
+   * Make "Manage account" open the SDK's own `<UserProfile/>` dialog instead of navigating
+   * (v0.4 / FR-PROF-8). Opt-in, so an app that already links its menu to its own account page
+   * keeps that behavior untouched (FR-COMPAT-2).
+   *
+   * Ignored when `manageAccountUrl` is set — a menu entry that both navigates and opens a
+   * dialog is a bug, so the explicit destination wins and this is a no-op.
+   */
+  showUserProfile?: boolean;
+  /** Passed through to the dialog `showUserProfile` opens. */
+  userProfileProps?: Omit<UserProfileProps, "open" | "onOpenChange">;
   /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
   showSignOutEverywhere?: boolean;
   /** Start with the menu open. Default `false`. */
@@ -631,6 +718,23 @@ declare function UserAvatar({
   className
 }: UserAvatarProps): ReactNode;
 //#endregion
+//#region src/auth-event.d.ts
+/**
+ * Read a one-shot auth event published by the BFF (F017 / FR-CLIENT-5).
+ *
+ * Sign-in and sign-out are full-page navigations, so an app cannot simply react in the
+ * handler that triggered them — the page is gone. The BFF leaves a short-lived, readable
+ * cookie; the destination page consumes it once.
+ */
+type AuthEventKind = "signed-in" | "signed-out";
+/**
+ * Read the pending auth event and clear it, so it fires exactly once.
+ *
+ * Returns `null` when there is nothing pending — which is the normal case on almost every
+ * page load. Safe to call during render or in an effect; it is a no-op on the server.
+ */
+declare function consumeAuthEvent(): AuthEventKind | null;
+//#endregion
 //#region src/live-authz.d.ts
 /**
  * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
@@ -699,6 +803,7 @@ declare function useAuthzChanged(callback: () => void): void;
  * F006; this entry is the state foundation (provider, hooks, browser seams).
  */
 declare const PACKAGE_NAME = "@poly-x/react";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-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 };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, 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, UserProfile, type UserProfileLabels, type UserProfileProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };

package/dist/index.d.mts

@@ -136,6 +136,16 @@ interface UseAuth {
    * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
    */
   getToken: () => Promise<string | null>;
+  /**
+   * Re-read the session's authorization from the server and resolve whether it actually
+   * changed (FR-CLIENT-3).
+   *
+   * This capability already existed on the BFF store but was not reachable from the public
+   * surface, so both consuming apps wrote their own refresher — and they already differ:
+   * one treats a module change as an authorization change, the other only a permission
+   * change. Pair it with `useLiveAuthz`/`startLiveAuthz`, which single-flights callers.
+   */
+  refresh: () => Promise<boolean>;
 }
 declare function useAuth(): UseAuth;
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
@@ -239,6 +249,8 @@ interface SignInLabels {
   noAccess: string;
   passwordChangeRequired: string;
   genericError: string;
+  /** Reserved second-factor step (F020). Unreachable until MFA ships. */
+  verificationRequired?: string;
 }
 /**
  * `card` renders just the card — drop it into your own layout.
@@ -500,6 +512,70 @@ interface Viewport {
  */
 declare function resolveSide(preferred: SideOption, trigger: Rect, menu: Size, viewport: Viewport, gap?: number): Side;
 //#endregion
+//#region src/components/user-profile.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling (FR-BRAND-4). */
+interface UserProfileLabels {
+  trigger: string;
+  title: string;
+  description: string;
+  firstName: string;
+  lastName: string;
+  phoneNumber: string;
+  cnic: string;
+  gender: string;
+  photo: string;
+  changePhoto: string;
+  optional: string;
+  save: string;
+  saving: string;
+  cancel: string;
+  close: string;
+  loading: string;
+  loadFailed: string;
+  saveFailed: string;
+  saved: string;
+  signedOut: string;
+  genderUnset: string;
+  genderMale: string;
+  genderFemale: string;
+  genderOther: string;
+}
+interface UserProfileProps {
+  /** Replaces the trigger's contents. The SDK still owns the button and its dialog semantics. */
+  trigger?: ReactNode;
+  /** Render no trigger at all and control the dialog from outside (`open` / `onOpenChange`). */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Notified after a successful save, with the saved profile (FR-PROF-10). */
+  onSaved?: (user: Record<string, unknown>) => void;
+  /** Appended to the root element's class list. */
+  className?: string;
+  /** Appended to the trigger button's class list — the element a consumer places in their layout. */
+  triggerClassName?: string;
+  /** Appended to the dialog's class list. */
+  dialogClassName?: string;
+  labels?: Partial<UserProfileLabels>;
+}
+/**
+ * The signed-in person's own profile, as a dialog (v0.4 / FR-PROF).
+ *
+ * Every application that wanted this had to build the same four things: a form, a validation
+ * ruleset guessed at from error messages, a file upload, and — because the browser holds no
+ * credential under BFF custody — a server route to carry the call. The last of those is
+ * security-adjacent work that had no business being duplicated per app.
+ *
+ * The credential never comes near this component: it posts to the SDK's own route, which
+ * attaches the session server-side and takes the identity from the sealed session rather than
+ * from anything sent here. This surface cannot be aimed at another person's profile even if a
+ * caller tries (FR-CUSTODY-4 / D24).
+ *
+ * ```tsx
+ * <UserProfile onSaved={() => router.refresh()} />
+ * ```
+ */
+declare function UserProfile(props: UserProfileProps): ReactNode;
+//#endregion
 //#region src/components/user-button.d.ts
 /** Every user-facing string, overridable for i18n / white-labelling. */
 interface UserButtonLabels {
@@ -542,6 +618,17 @@ interface UserButtonProps {
    * hosted profile page, so the destination is the consumer's to own.
    */
   manageAccountUrl?: string;
+  /**
+   * Make "Manage account" open the SDK's own `<UserProfile/>` dialog instead of navigating
+   * (v0.4 / FR-PROF-8). Opt-in, so an app that already links its menu to its own account page
+   * keeps that behavior untouched (FR-COMPAT-2).
+   *
+   * Ignored when `manageAccountUrl` is set — a menu entry that both navigates and opens a
+   * dialog is a bug, so the explicit destination wins and this is a no-op.
+   */
+  showUserProfile?: boolean;
+  /** Passed through to the dialog `showUserProfile` opens. */
+  userProfileProps?: Omit<UserProfileProps, "open" | "onOpenChange">;
   /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
   showSignOutEverywhere?: boolean;
   /** Start with the menu open. Default `false`. */
@@ -631,6 +718,23 @@ declare function UserAvatar({
   className
 }: UserAvatarProps): ReactNode;
 //#endregion
+//#region src/auth-event.d.ts
+/**
+ * Read a one-shot auth event published by the BFF (F017 / FR-CLIENT-5).
+ *
+ * Sign-in and sign-out are full-page navigations, so an app cannot simply react in the
+ * handler that triggered them — the page is gone. The BFF leaves a short-lived, readable
+ * cookie; the destination page consumes it once.
+ */
+type AuthEventKind = "signed-in" | "signed-out";
+/**
+ * Read the pending auth event and clear it, so it fires exactly once.
+ *
+ * Returns `null` when there is nothing pending — which is the normal case on almost every
+ * page load. Safe to call during render or in an effect; it is a no-op on the server.
+ */
+declare function consumeAuthEvent(): AuthEventKind | null;
+//#endregion
 //#region src/live-authz.d.ts
 /**
  * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
@@ -699,6 +803,7 @@ declare function useAuthzChanged(callback: () => void): void;
  * F006; this entry is the state foundation (provider, hooks, browser seams).
  */
 declare const PACKAGE_NAME = "@poly-x/react";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-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 };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, 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, UserProfile, type UserProfileLabels, type UserProfileProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };