@poly-x/react 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/index.cjs

@@ -1409,6 +1409,59 @@ function AuthCallback({ children = null }) {
 	return children;
 }
 //#endregion
+//#region src/components/placement.ts
+const OPPOSITE = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+/** Preference order when nothing is requested: vertical reads better for a menu than sideways. */
+const AUTO_ORDER = [
+	"bottom",
+	"top",
+	"right",
+	"left"
+];
+/** Room between the trigger and each viewport edge. */
+function spaceAround(trigger, viewport) {
+	return {
+		top: trigger.top,
+		bottom: viewport.height - trigger.bottom,
+		left: trigger.left,
+		right: viewport.width - trigger.right
+	};
+}
+function required(menu, gap) {
+	return {
+		top: menu.height + gap,
+		bottom: menu.height + gap,
+		left: menu.width + gap,
+		right: menu.width + gap
+	};
+}
+/**
+* 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.
+*/
+function resolveSide(preferred, trigger, menu, viewport, gap = 8) {
+	const space = spaceAround(trigger, viewport);
+	const need = required(menu, gap);
+	const fits = (side) => space[side] >= need[side];
+	if (preferred !== "auto") {
+		if (fits(preferred)) return preferred;
+		const opposite = OPPOSITE[preferred];
+		return fits(opposite) ? opposite : preferred;
+	}
+	const firstFitting = AUTO_ORDER.find(fits);
+	if (firstFitting) return firstFitting;
+	return AUTO_ORDER.reduce((best, side) => space[side] > space[best] ? side : best, AUTO_ORDER[0]);
+}
+//#endregion
 //#region src/components/user-avatar.tsx
 /**
 * Up to two initials from a display name. Handles the shapes the platform actually
@@ -1462,9 +1515,13 @@ function isBuiltIn(label) {
 }
 /**
 * Declarative markers. `<UserButton/>` reads their props off the element tree and renders the
-* menu itself, so these never render anything — which is also what keeps the menu's markup
-* ours and a consumer's styles out of it (FR-BRAND-1). Their public prop types come from the
-* signatures declared on the exported object below.
+* menu itself, so these never render anything. Their public prop types come from the signatures
+* declared on the exported object below.
+*
+* `Custom` and `Header` take arbitrary nodes on purpose: an app adopting this component in place
+* of its own user menu has to be able to bring its own UI, or it won't adopt it. That is
+* composition, not the style injection FR-BRAND-1 guards against — a consumer renders their own
+* subtree in a slot; they still cannot restyle the SDK's own chrome.
 */
 function MenuItems() {
 	return null;
@@ -1475,6 +1532,12 @@ function Action() {
 function Link() {
 	return null;
 }
+function Custom() {
+	return null;
+}
+function Header() {
+	return null;
+}
 /**
 * Read the declarative children into a flat item list. A custom entry naming a built-in
 * *moves* it; unnamed built-ins keep their default order at the end. This is the whole reason
@@ -1482,7 +1545,7 @@ function Link() {
 * inject arbitrary markup or styles into the menu (FR-BRAND-1).
 */
 function resolveItems(children, builtIns) {
-	const custom = [];
+	const supplied = [];
 	const placed = /* @__PURE__ */ new Set();
 	react.Children.forEach(children, (child) => {
 		if (!(0, react.isValidElement)(child) || child.type !== MenuItems) return;
@@ -1493,12 +1556,12 @@ function resolveItems(children, builtIns) {
 				if (isBuiltIn(props.label)) {
 					const builtIn = builtIns.get(props.label);
 					if (builtIn) {
-						custom.push(builtIn);
+						supplied.push(builtIn);
 						placed.add(props.label);
 					}
 					return;
 				}
-				custom.push({
+				supplied.push({
 					key: `action-${index}`,
 					label: props.label,
 					labelIcon: props.labelIcon,
@@ -1508,17 +1571,30 @@ function resolveItems(children, builtIns) {
 			}
 			if (item.type === Link) {
 				const props = item.props;
-				custom.push({
+				supplied.push({
 					key: `link-${index}`,
 					label: props.label,
 					labelIcon: props.labelIcon,
 					href: props.href
 				});
+				return;
 			}
+			if (item.type === Custom) supplied.push({
+				key: `custom-${index}`,
+				custom: item.props.children
+			});
 		});
 	});
 	const remaining = [...builtIns.entries()].filter(([name]) => !placed.has(name)).map(([, item]) => item);
-	return [...custom, ...remaining];
+	return [...supplied, ...remaining];
+}
+/** The consumer's replacement for the identity block, if they supplied one. */
+function findHeader(children) {
+	let header;
+	react.Children.forEach(children, (child) => {
+		if ((0, react.isValidElement)(child) && child.type === Header) header = child.props.children;
+	});
+	return header;
 }
 function UserButtonRoot(props) {
 	const labels = {
@@ -1529,13 +1605,25 @@ function UserButtonRoot(props) {
 	const user = useUser();
 	const [open, setOpen] = (0, react.useState)(props.defaultOpen ?? false);
 	const [focused, setFocused] = (0, react.useState)(0);
+	const [side, setSide] = (0, react.useState)(props.side && props.side !== "auto" ? props.side : "bottom");
 	const triggerRef = (0, react.useRef)(null);
+	const menuRef = (0, react.useRef)(null);
 	const itemRefs = (0, react.useRef)([]);
 	const menuId = (0, react.useId)();
+	const align = props.align ?? "end";
 	const close = (0, react.useCallback)((returnFocus) => {
 		setOpen(false);
 		if (returnFocus) triggerRef.current?.focus();
 	}, []);
+	const onOpenChange = props.onOpenChange;
+	const mounted = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		if (!mounted.current) {
+			mounted.current = true;
+			return;
+		}
+		onOpenChange?.(open);
+	}, [open, onOpenChange]);
 	(0, react.useEffect)(() => {
 		if (!open) return;
 		const onKeyDown = (event) => {
@@ -1555,6 +1643,33 @@ function UserButtonRoot(props) {
 	(0, react.useEffect)(() => {
 		if (open) itemRefs.current[focused]?.focus();
 	}, [open, focused]);
+	/**
+	* Choose the side once the menu exists and can be measured. `useLayoutEffect` runs before
+	* paint, so the correction never shows as a jump — the menu is only ever painted where it
+	* belongs. Re-measured on resize and on scroll, since either can invalidate the choice.
+	*/
+	(0, react.useLayoutEffect)(() => {
+		if (!open) return;
+		const place = () => {
+			const trigger = triggerRef.current?.getBoundingClientRect();
+			const menu = menuRef.current?.getBoundingClientRect();
+			if (!trigger || !menu) return;
+			setSide(resolveSide(props.side ?? "auto", trigger, {
+				width: menu.width,
+				height: menu.height
+			}, {
+				width: window.innerWidth,
+				height: window.innerHeight
+			}));
+		};
+		place();
+		window.addEventListener("resize", place);
+		window.addEventListener("scroll", place, true);
+		return () => {
+			window.removeEventListener("resize", place);
+			window.removeEventListener("scroll", place, true);
+		};
+	}, [open, props.side]);
 	if (!isLoaded) return props.fallback ?? null;
 	if (!isSignedIn || !user) return null;
 	const name = user.displayName ?? user.email ?? "";
@@ -1581,14 +1696,17 @@ function UserButtonRoot(props) {
 		})
 	});
 	const items = resolveItems(props.children, builtIns);
+	const customHeader = findHeader(props.children);
+	const navigable = items.map((item, index) => ({
+		item,
+		index
+	})).filter(({ item }) => !item.custom);
 	const onMenuKeyDown = (event) => {
-		if (event.key === "ArrowDown") {
-			event.preventDefault();
-			setFocused((current) => (current + 1) % items.length);
-		} else if (event.key === "ArrowUp") {
-			event.preventDefault();
-			setFocused((current) => (current - 1 + items.length) % items.length);
-		}
+		if (navigable.length === 0) return;
+		if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
+		event.preventDefault();
+		const next = (navigable.findIndex(({ index }) => index === focused) + (event.key === "ArrowDown" ? 1 : -1) + navigable.length) % navigable.length;
+		setFocused(navigable[next].index);
 	};
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: [
@@ -1597,10 +1715,10 @@ function UserButtonRoot(props) {
 			props.className
 		].filter(Boolean).join(" "),
 		"data-polyx-userbutton": open ? "open" : "closed",
-		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 			ref: triggerRef,
 			type: "button",
-			className: "polyx-userbutton__trigger",
+			className: ["polyx-userbutton__trigger", props.triggerClassName].filter(Boolean).join(" "),
 			"aria-haspopup": "menu",
 			"aria-expanded": open,
 			"aria-controls": open ? menuId : void 0,
@@ -1609,20 +1727,23 @@ function UserButtonRoot(props) {
 				setFocused(0);
 				setOpen((current) => !current);
 			},
-			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(UserAvatar, {
+			children: props.trigger ?? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(UserAvatar, {
 				src: user.avatarUrl,
 				name,
 				size: props.avatarSize
 			}), props.showName ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 				className: "polyx-userbutton__trigger-name",
 				children: name
-			}) : null]
+			}) : null] })
 		}), open ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			ref: menuRef,
 			id: menuId,
 			role: "menu",
 			className: "polyx-userbutton__menu",
+			"data-polyx-side": side,
+			"data-polyx-align": align,
 			onKeyDown: onMenuKeyDown,
-			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			children: [customHeader ?? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "polyx-userbutton__identity",
 				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(UserAvatar, {
 					src: user.avatarUrl,
@@ -1640,7 +1761,10 @@ function UserButtonRoot(props) {
 				})]
 			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
 				className: "polyx-userbutton__items",
-				children: items.map((item, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: item.href ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("a", {
+				children: items.map((item, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: item.custom ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "polyx-userbutton__custom",
+					children: item.custom
+				}) : item.href ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("a", {
 					ref: (node) => {
 						itemRefs.current[index] = node;
 					},
@@ -1725,7 +1849,9 @@ function ExitIcon() {
 const UserButton = Object.assign(UserButtonRoot, {
 	MenuItems,
 	Action,
-	Link
+	Link,
+	Custom,
+	Header
 });
 //#endregion
 //#region src/index.ts
@@ -1753,6 +1879,8 @@ exports.UserButton = UserButton;
 exports.WebLocksLock = WebLocksLock;
 exports.WindowBrowserBridge = WindowBrowserBridge;
 exports.createLoginController = createLoginController;
+exports.initialsFrom = initialsFrom;
+exports.resolveSide = resolveSide;
 exports.useAuth = useAuth;
 exports.useAuthCallback = useAuthCallback;
 exports.useSession = useSession;

package/dist/index.d.cts

@@ -386,6 +386,46 @@ 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 {
@@ -409,6 +449,9 @@ interface UserButtonLinkProps {
   labelIcon?: ReactNode;
   href: string;
 }
+interface UserButtonSlotProps {
+  children?: ReactNode;
+}
 interface UserButtonProps {
   /** Show the user's name next to the avatar. Default `false`. */
   showName?: boolean;
@@ -427,11 +470,34 @@ interface UserButtonProps {
   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 custom `<UserButton.Action>` / `<UserButton.Link>` entries. */
+  /**
+   * `<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
@@ -451,11 +517,11 @@ interface UserButtonProps {
  * ```
  */
 declare const UserButton: ((props: UserButtonProps) => ReactNode) & {
-  MenuItems: (props: {
-    children?: ReactNode;
-  }) => ReactNode;
+  MenuItems: (props: UserButtonSlotProps) => ReactNode;
   Action: (props: UserButtonActionProps) => ReactNode;
-  Link: (props: UserButtonLinkProps) => 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
@@ -469,6 +535,11 @@ interface UserAvatarProps {
   /** 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.
@@ -488,4 +559,4 @@ declare function UserAvatar({
 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, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, 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 };

package/dist/index.d.mts

@@ -386,6 +386,46 @@ 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 {
@@ -409,6 +449,9 @@ interface UserButtonLinkProps {
   labelIcon?: ReactNode;
   href: string;
 }
+interface UserButtonSlotProps {
+  children?: ReactNode;
+}
 interface UserButtonProps {
   /** Show the user's name next to the avatar. Default `false`. */
   showName?: boolean;
@@ -427,11 +470,34 @@ interface UserButtonProps {
   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 custom `<UserButton.Action>` / `<UserButton.Link>` entries. */
+  /**
+   * `<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
@@ -451,11 +517,11 @@ interface UserButtonProps {
  * ```
  */
 declare const UserButton: ((props: UserButtonProps) => ReactNode) & {
-  MenuItems: (props: {
-    children?: ReactNode;
-  }) => ReactNode;
+  MenuItems: (props: UserButtonSlotProps) => ReactNode;
   Action: (props: UserButtonActionProps) => ReactNode;
-  Link: (props: UserButtonLinkProps) => 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
@@ -469,6 +535,11 @@ interface UserAvatarProps {
   /** 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.
@@ -488,4 +559,4 @@ declare function UserAvatar({
 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, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, 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 };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 "use client";
 import { AuthClient, FetchTransport, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, createSessionEngine, generatePkce, randomState, resolveConfig } from "@poly-x/core";
-import { Children, Fragment, createContext, isValidElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { Children, Fragment, createContext, isValidElement, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/auth-channel.ts
 var BroadcastAuthChannel = class {
@@ -1408,6 +1408,59 @@ function AuthCallback({ children = null }) {
 	return children;
 }
 //#endregion
+//#region src/components/placement.ts
+const OPPOSITE = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+/** Preference order when nothing is requested: vertical reads better for a menu than sideways. */
+const AUTO_ORDER = [
+	"bottom",
+	"top",
+	"right",
+	"left"
+];
+/** Room between the trigger and each viewport edge. */
+function spaceAround(trigger, viewport) {
+	return {
+		top: trigger.top,
+		bottom: viewport.height - trigger.bottom,
+		left: trigger.left,
+		right: viewport.width - trigger.right
+	};
+}
+function required(menu, gap) {
+	return {
+		top: menu.height + gap,
+		bottom: menu.height + gap,
+		left: menu.width + gap,
+		right: menu.width + gap
+	};
+}
+/**
+* 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.
+*/
+function resolveSide(preferred, trigger, menu, viewport, gap = 8) {
+	const space = spaceAround(trigger, viewport);
+	const need = required(menu, gap);
+	const fits = (side) => space[side] >= need[side];
+	if (preferred !== "auto") {
+		if (fits(preferred)) return preferred;
+		const opposite = OPPOSITE[preferred];
+		return fits(opposite) ? opposite : preferred;
+	}
+	const firstFitting = AUTO_ORDER.find(fits);
+	if (firstFitting) return firstFitting;
+	return AUTO_ORDER.reduce((best, side) => space[side] > space[best] ? side : best, AUTO_ORDER[0]);
+}
+//#endregion
 //#region src/components/user-avatar.tsx
 /**
 * Up to two initials from a display name. Handles the shapes the platform actually
@@ -1461,9 +1514,13 @@ function isBuiltIn(label) {
 }
 /**
 * Declarative markers. `<UserButton/>` reads their props off the element tree and renders the
-* menu itself, so these never render anything — which is also what keeps the menu's markup
-* ours and a consumer's styles out of it (FR-BRAND-1). Their public prop types come from the
-* signatures declared on the exported object below.
+* menu itself, so these never render anything. Their public prop types come from the signatures
+* declared on the exported object below.
+*
+* `Custom` and `Header` take arbitrary nodes on purpose: an app adopting this component in place
+* of its own user menu has to be able to bring its own UI, or it won't adopt it. That is
+* composition, not the style injection FR-BRAND-1 guards against — a consumer renders their own
+* subtree in a slot; they still cannot restyle the SDK's own chrome.
 */
 function MenuItems() {
 	return null;
@@ -1474,6 +1531,12 @@ function Action() {
 function Link() {
 	return null;
 }
+function Custom() {
+	return null;
+}
+function Header() {
+	return null;
+}
 /**
 * Read the declarative children into a flat item list. A custom entry naming a built-in
 * *moves* it; unnamed built-ins keep their default order at the end. This is the whole reason
@@ -1481,7 +1544,7 @@ function Link() {
 * inject arbitrary markup or styles into the menu (FR-BRAND-1).
 */
 function resolveItems(children, builtIns) {
-	const custom = [];
+	const supplied = [];
 	const placed = /* @__PURE__ */ new Set();
 	Children.forEach(children, (child) => {
 		if (!isValidElement(child) || child.type !== MenuItems) return;
@@ -1492,12 +1555,12 @@ function resolveItems(children, builtIns) {
 				if (isBuiltIn(props.label)) {
 					const builtIn = builtIns.get(props.label);
 					if (builtIn) {
-						custom.push(builtIn);
+						supplied.push(builtIn);
 						placed.add(props.label);
 					}
 					return;
 				}
-				custom.push({
+				supplied.push({
 					key: `action-${index}`,
 					label: props.label,
 					labelIcon: props.labelIcon,
@@ -1507,17 +1570,30 @@ function resolveItems(children, builtIns) {
 			}
 			if (item.type === Link) {
 				const props = item.props;
-				custom.push({
+				supplied.push({
 					key: `link-${index}`,
 					label: props.label,
 					labelIcon: props.labelIcon,
 					href: props.href
 				});
+				return;
 			}
+			if (item.type === Custom) supplied.push({
+				key: `custom-${index}`,
+				custom: item.props.children
+			});
 		});
 	});
 	const remaining = [...builtIns.entries()].filter(([name]) => !placed.has(name)).map(([, item]) => item);
-	return [...custom, ...remaining];
+	return [...supplied, ...remaining];
+}
+/** The consumer's replacement for the identity block, if they supplied one. */
+function findHeader(children) {
+	let header;
+	Children.forEach(children, (child) => {
+		if (isValidElement(child) && child.type === Header) header = child.props.children;
+	});
+	return header;
 }
 function UserButtonRoot(props) {
 	const labels = {
@@ -1528,13 +1604,25 @@ function UserButtonRoot(props) {
 	const user = useUser();
 	const [open, setOpen] = useState(props.defaultOpen ?? false);
 	const [focused, setFocused] = useState(0);
+	const [side, setSide] = useState(props.side && props.side !== "auto" ? props.side : "bottom");
 	const triggerRef = useRef(null);
+	const menuRef = useRef(null);
 	const itemRefs = useRef([]);
 	const menuId = useId();
+	const align = props.align ?? "end";
 	const close = useCallback((returnFocus) => {
 		setOpen(false);
 		if (returnFocus) triggerRef.current?.focus();
 	}, []);
+	const onOpenChange = props.onOpenChange;
+	const mounted = useRef(false);
+	useEffect(() => {
+		if (!mounted.current) {
+			mounted.current = true;
+			return;
+		}
+		onOpenChange?.(open);
+	}, [open, onOpenChange]);
 	useEffect(() => {
 		if (!open) return;
 		const onKeyDown = (event) => {
@@ -1554,6 +1642,33 @@ function UserButtonRoot(props) {
 	useEffect(() => {
 		if (open) itemRefs.current[focused]?.focus();
 	}, [open, focused]);
+	/**
+	* Choose the side once the menu exists and can be measured. `useLayoutEffect` runs before
+	* paint, so the correction never shows as a jump — the menu is only ever painted where it
+	* belongs. Re-measured on resize and on scroll, since either can invalidate the choice.
+	*/
+	useLayoutEffect(() => {
+		if (!open) return;
+		const place = () => {
+			const trigger = triggerRef.current?.getBoundingClientRect();
+			const menu = menuRef.current?.getBoundingClientRect();
+			if (!trigger || !menu) return;
+			setSide(resolveSide(props.side ?? "auto", trigger, {
+				width: menu.width,
+				height: menu.height
+			}, {
+				width: window.innerWidth,
+				height: window.innerHeight
+			}));
+		};
+		place();
+		window.addEventListener("resize", place);
+		window.addEventListener("scroll", place, true);
+		return () => {
+			window.removeEventListener("resize", place);
+			window.removeEventListener("scroll", place, true);
+		};
+	}, [open, props.side]);
 	if (!isLoaded) return props.fallback ?? null;
 	if (!isSignedIn || !user) return null;
 	const name = user.displayName ?? user.email ?? "";
@@ -1580,14 +1695,17 @@ function UserButtonRoot(props) {
 		})
 	});
 	const items = resolveItems(props.children, builtIns);
+	const customHeader = findHeader(props.children);
+	const navigable = items.map((item, index) => ({
+		item,
+		index
+	})).filter(({ item }) => !item.custom);
 	const onMenuKeyDown = (event) => {
-		if (event.key === "ArrowDown") {
-			event.preventDefault();
-			setFocused((current) => (current + 1) % items.length);
-		} else if (event.key === "ArrowUp") {
-			event.preventDefault();
-			setFocused((current) => (current - 1 + items.length) % items.length);
-		}
+		if (navigable.length === 0) return;
+		if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
+		event.preventDefault();
+		const next = (navigable.findIndex(({ index }) => index === focused) + (event.key === "ArrowDown" ? 1 : -1) + navigable.length) % navigable.length;
+		setFocused(navigable[next].index);
 	};
 	return /* @__PURE__ */ jsxs("div", {
 		className: [
@@ -1596,10 +1714,10 @@ function UserButtonRoot(props) {
 			props.className
 		].filter(Boolean).join(" "),
 		"data-polyx-userbutton": open ? "open" : "closed",
-		children: [/* @__PURE__ */ jsxs("button", {
+		children: [/* @__PURE__ */ jsx("button", {
 			ref: triggerRef,
 			type: "button",
-			className: "polyx-userbutton__trigger",
+			className: ["polyx-userbutton__trigger", props.triggerClassName].filter(Boolean).join(" "),
 			"aria-haspopup": "menu",
 			"aria-expanded": open,
 			"aria-controls": open ? menuId : void 0,
@@ -1608,20 +1726,23 @@ function UserButtonRoot(props) {
 				setFocused(0);
 				setOpen((current) => !current);
 			},
-			children: [/* @__PURE__ */ jsx(UserAvatar, {
+			children: props.trigger ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(UserAvatar, {
 				src: user.avatarUrl,
 				name,
 				size: props.avatarSize
 			}), props.showName ? /* @__PURE__ */ jsx("span", {
 				className: "polyx-userbutton__trigger-name",
 				children: name
-			}) : null]
+			}) : null] })
 		}), open ? /* @__PURE__ */ jsxs("div", {
+			ref: menuRef,
 			id: menuId,
 			role: "menu",
 			className: "polyx-userbutton__menu",
+			"data-polyx-side": side,
+			"data-polyx-align": align,
 			onKeyDown: onMenuKeyDown,
-			children: [/* @__PURE__ */ jsxs("div", {
+			children: [customHeader ?? /* @__PURE__ */ jsxs("div", {
 				className: "polyx-userbutton__identity",
 				children: [/* @__PURE__ */ jsx(UserAvatar, {
 					src: user.avatarUrl,
@@ -1639,7 +1760,10 @@ function UserButtonRoot(props) {
 				})]
 			}), /* @__PURE__ */ jsx("ul", {
 				className: "polyx-userbutton__items",
-				children: items.map((item, index) => /* @__PURE__ */ jsx("li", { children: item.href ? /* @__PURE__ */ jsxs("a", {
+				children: items.map((item, index) => /* @__PURE__ */ jsx("li", { children: item.custom ? /* @__PURE__ */ jsx("div", {
+					className: "polyx-userbutton__custom",
+					children: item.custom
+				}) : item.href ? /* @__PURE__ */ jsxs("a", {
 					ref: (node) => {
 						itemRefs.current[index] = node;
 					},
@@ -1724,7 +1848,9 @@ function ExitIcon() {
 const UserButton = Object.assign(UserButtonRoot, {
 	MenuItems,
 	Action,
-	Link
+	Link,
+	Custom,
+	Header
 });
 //#endregion
 //#region src/index.ts
@@ -1735,4 +1861,4 @@ const UserButton = Object.assign(UserButtonRoot, {
 const PACKAGE_NAME = "@poly-x/react";
 const version = "0.0.0";
 //#endregion
-export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };
+export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, WebLocksLock, WindowBrowserBridge, createLoginController, initialsFrom, resolveSide, useAuth, useAuthCallback, useSession, useUser, version };

package/dist/styles.css

@@ -548,10 +548,12 @@
 	user-select: none;
 }
 
+/* Placement is expressed as data attributes and resolved in CSS: the component measures which
+   side has room and says so; where that lands is a styling concern. `--polyx-gap` is the space
+   between trigger and menu, and the JS assumes the same 8px when it measures. */
 .polyx-userbutton__menu {
+	--polyx-gap: 0.5rem;
 	position: absolute;
-	top: calc(100% + 0.5rem);
-	right: 0;
 	z-index: 50;
 	min-width: 15rem;
 	padding: 0.375rem;
@@ -561,6 +563,54 @@
 	box-shadow: var(--polyx-shadow);
 }
 
+/* Vertical sides: offset above/below, then align along the horizontal axis. */
+.polyx-userbutton__menu[data-polyx-side="bottom"] {
+	top: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="top"] {
+	bottom: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="bottom"][data-polyx-align="end"],
+.polyx-userbutton__menu[data-polyx-side="top"][data-polyx-align="end"] {
+	right: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="bottom"][data-polyx-align="start"],
+.polyx-userbutton__menu[data-polyx-side="top"][data-polyx-align="start"] {
+	left: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="bottom"][data-polyx-align="center"],
+.polyx-userbutton__menu[data-polyx-side="top"][data-polyx-align="center"] {
+	left: 50%;
+	transform: translateX(-50%);
+}
+
+/* Horizontal sides: offset left/right, then align along the vertical axis. */
+.polyx-userbutton__menu[data-polyx-side="right"] {
+	left: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="left"] {
+	right: calc(100% + var(--polyx-gap));
+}
+.polyx-userbutton__menu[data-polyx-side="right"][data-polyx-align="end"],
+.polyx-userbutton__menu[data-polyx-side="left"][data-polyx-align="end"] {
+	bottom: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="right"][data-polyx-align="start"],
+.polyx-userbutton__menu[data-polyx-side="left"][data-polyx-align="start"] {
+	top: 0;
+}
+.polyx-userbutton__menu[data-polyx-side="right"][data-polyx-align="center"],
+.polyx-userbutton__menu[data-polyx-side="left"][data-polyx-align="center"] {
+	top: 50%;
+	transform: translateY(-50%);
+}
+
+/* Consumer-supplied rows: give them room and get out of the way — no colours, no type, no
+   cursor. Whatever they render is theirs. */
+.polyx-userbutton__custom {
+	padding: 0.375rem 0.625rem;
+}
+
 .polyx-userbutton__identity {
 	display: flex;
 	align-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/react",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "description": "PolyX SDK for React SPAs - provider, hooks, drop-in auth UI",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "dependencies": {
-    "@poly-x/core": "0.1.0-alpha.10"
+    "@poly-x/core": "0.1.0-alpha.12"
   },
   "peerDependencies": {
     "react": ">=18",