@flow-industries/id 0.21.0 → 0.21.1

package/README.md

@@ -47,6 +47,38 @@ Full documentation at **[docs.flow.industries/en/auth](https://docs.flow.industr
 - [JWT verify](https://docs.flow.industries/en/auth/jwt-verify) - verify Flow sessions on your backend
 - [API reference](https://docs.flow.industries/en/auth/api) and [self-hosting](https://docs.flow.industries/en/auth/self-hosting)
 
+## Public profile overlays
+
+```ts
+import { closeProfile, openProfile } from "@flow-industries/id";
+import { isValidUsername } from "@flow-industries/id/usernames";
+
+if (isValidUsername(username)) {
+  openProfile(username, { onClose: () => resumeInput() });
+}
+
+closeProfile();
+```
+
+`@flow-industries/id/usernames` also exports `USERNAME_REGEX` and
+`MAX_USERNAME_LENGTH`. It has no browser or server dependencies.
+
+`OpenProfileOptions.onClose?: () => void` fires once after the overlay stops
+accepting input, before its exit animation finishes. It covers the close button,
+backdrop, Escape, `closeProfile()`, and sign-in/sign-out handoffs. The latest
+successful `openProfile` call owns the callback, even when switching profiles
+while open; an omitted callback clears the previous one. Invalid usernames and
+SSR return `false` without replacing it. Closing an already closed overlay is a
+no-op. A callback may open another profile.
+
+React callers pass the same option to
+`useOpenProfile({ onClose: () => resumeInput() })` from
+`@flow-industries/id/react`; the callback is captured when its returned opener
+is called. The overlay belongs to the page and survives component unmounts.
+
+Open from the document that owns the full viewport. Canvas hosts must release
+pointer lock before opening, then use `onClose` to restore their input state.
+
 ## License
 
 MIT

package/dist/sdk/client/open-profile.js

@@ -21,6 +21,7 @@ function createViewer(options) {
     // meant for the page underneath with nothing on screen to explain it.
     let ready = false;
     let visible = false;
+    let onClose;
     function applyHitTesting() {
         if (frame)
             frame.style.pointerEvents = ready && visible ? "auto" : "none";
@@ -78,7 +79,7 @@ function createViewer(options) {
         });
         return opened;
     }
-    function open(username) {
+    function open(username, nextOnClose) {
         const mounted = bridge;
         const live = mounted ?? mount(username);
         // A frame created just now is already on this profile; an existing one is
@@ -93,6 +94,8 @@ function createViewer(options) {
             type: "profile-identity",
             identity: hostIdentity(flow),
         });
+        window.addEventListener("keydown", onKeyDown);
+        onClose = nextOnClose;
         visible = true;
         applyHitTesting();
         void live.send("__internal", { type: "dialog-shown" });
@@ -104,11 +107,21 @@ function createViewer(options) {
     // always-rendered, transparent and click-through while hidden keeps every
     // open animation reliable, on the second open and the tenth.
     function close() {
-        if (!frame || !bridge)
+        if (!visible || !frame || !bridge)
             return;
         visible = false;
+        window.removeEventListener("keydown", onKeyDown);
         applyHitTesting();
         void bridge.send("__internal", { type: "dialog-hidden" });
+        const notifyClose = onClose;
+        onClose = undefined;
+        notifyClose?.();
+    }
+    function onKeyDown(event) {
+        if (event.key !== "Escape" || event.defaultPrevented)
+            return;
+        event.preventDefault();
+        close();
     }
     function setTheme(next) {
         if (next === theme)
@@ -163,7 +176,7 @@ export function openProfile(username, options = {}) {
     viewer = live;
     if (options.theme)
         live.setTheme(options.theme);
-    live.open(username);
+    live.open(username, options.onClose);
     return true;
 }
 /**

package/dist/sdk/react/open-profile.js

@@ -19,6 +19,6 @@ import { useFlow } from "./hooks";
  */
 export function useOpenProfile(options = {}) {
     const flow = useFlow();
-    const { host, theme } = options;
-    return useCallback((username) => openProfile(username, { flow, host, theme }), [flow, host, theme]);
+    const { host, theme, onClose } = options;
+    return useCallback((username) => openProfile(username, { flow, host, theme, onClose }), [flow, host, theme, onClose]);
 }

package/dist/sdk/types/sdk.d.ts

@@ -230,6 +230,14 @@ export type ProfileButtonHandle = {
     destroy: () => void;
 };
 export type OpenProfileOptions = {
+    /**
+     * Called once when the overlay closes, including its close button, backdrop,
+     * Escape, closeProfile(), or a sign-in/sign-out handoff. Runs after the
+     * overlay stops accepting input, without waiting for the exit animation.
+     * The latest successful open replaces this callback; omitting it clears the
+     * previous callback. Rejected opens and repeated closes do not notify.
+     */
+    onClose?: () => void;
     /**
      * The Flow ID origin serving the overlay (e.g. https://id.flow.industries).
      * Defaults to the resolved Flow instance's `host`, then the SDK default.
@@ -249,12 +257,7 @@ export type OpenProfileOptions = {
      */
     flow?: Flow;
 };
-export type UseOpenProfileOptions = {
-    /** Override the Flow ID origin; defaults to the resolved Flow's `host`. */
-    host?: string;
-    /** Color scheme for the dialog chrome; defaults to "light dark" (the OS). */
-    theme?: ColorScheme;
-};
+export type UseOpenProfileOptions = Pick<OpenProfileOptions, "host" | "theme" | "onClose">;
 /** The inline Flow ID widgets an embedder can mount alongside its own UI. */
 export type FlowWidgetName = "xp" | "action-timer";
 export type MountFlowWidgetOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -19,6 +19,10 @@
       "types": "./dist/sdk/client/index.d.ts",
       "import": "./dist/sdk/client/index.js"
     },
+    "./usernames": {
+      "types": "./dist/sdk/usernames.d.ts",
+      "import": "./dist/sdk/usernames.js"
+    },
     "./react": {
       "types": "./dist/sdk/react/index.d.ts",
       "import": "./dist/sdk/react/index.js"
@@ -69,6 +73,7 @@
     "usernames:refresh": "bun run scripts/generate-reserved-usernames.ts",
     "lint": "biome check",
     "test": "bun test src",
+    "test:sdk-package": "bash scripts/test-sdk-package.sh",
     "format": "biome format --write",
     "check": "biome check --write",
     "typecheck": "tsr generate && tsc --noEmit"