@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.12

package/src/auth/components/confirmActions.tsx

@@ -0,0 +1,114 @@
+import type { ReactNode } from 'react';
+import type { AuthUserRecord } from 'pyric/auth';
+import { useConfirm } from '../../primitives/useConfirm.js';
+
+/** Shared trigger contract for the confirm-gated destructive actions. */
+interface TriggerProps {
+  onClick: () => void;
+}
+
+export interface DeleteUserWithConfirmProps {
+  user: AuthUserRecord;
+  /** Runs after the user confirms. Wire to `useAuthUsers().deleteUser`. */
+  onDelete: (uid: string) => void;
+  title?: string;
+  body?: ReactNode;
+  confirmLabel?: string;
+  /** Trigger override; default is a plain destructive `<button>`. */
+  renderTrigger?: (props: TriggerProps) => ReactNode;
+  className?: string;
+}
+
+function identifierOf(user: AuthUserRecord): string {
+  return user.email ?? user.phoneNumber ?? user.displayName ?? user.uid;
+}
+
+/**
+ * Confirm-gated single-user delete (the emulator UI's row-menu
+ * "Delete user"). Requires a `<ConfirmProvider>` ancestor.
+ */
+export function DeleteUserWithConfirm({
+  user,
+  onDelete,
+  title = 'Delete user',
+  body,
+  confirmLabel = 'Delete',
+  renderTrigger,
+  className,
+}: DeleteUserWithConfirmProps) {
+  const confirm = useConfirm();
+  const handleClick = async () => {
+    const ok = await confirm({
+      title,
+      body: body ?? `This will permanently delete ${identifierOf(user)}.`,
+      destructive: true,
+      confirmLabel,
+    });
+    if (ok) onDelete(user.uid);
+  };
+  if (renderTrigger) return <>{renderTrigger({ onClick: handleClick })}</>;
+  return (
+    <button
+      type="button"
+      className={className}
+      data-pyric-ui="delete-user"
+      data-pyric-destructive
+      onClick={handleClick}
+    >
+      Delete user
+    </button>
+  );
+}
+
+export interface ClearUsersWithConfirmProps {
+  /** Runs after the user confirms. Wire to `useAuthUsers().clearUsers`. */
+  onClear: () => void;
+  /** Current user count, interpolated into the default body. */
+  count?: number;
+  title?: string;
+  body?: ReactNode;
+  confirmLabel?: string;
+  renderTrigger?: (props: TriggerProps) => ReactNode;
+  className?: string;
+}
+
+/**
+ * Confirm-gated clear-all (the emulator UI's "Clear all data").
+ * Requires a `<ConfirmProvider>` ancestor.
+ */
+export function ClearUsersWithConfirm({
+  onClear,
+  count,
+  title = 'Clear all users',
+  body,
+  confirmLabel = 'Clear',
+  renderTrigger,
+  className,
+}: ClearUsersWithConfirmProps) {
+  const confirm = useConfirm();
+  const handleClick = async () => {
+    const ok = await confirm({
+      title,
+      body:
+        body ??
+        (count != null
+          ? `This will permanently delete all ${count} users.`
+          : 'This will permanently delete every user.'),
+      destructive: true,
+      confirmLabel,
+    });
+    if (ok) onClear();
+  };
+  if (renderTrigger) return <>{renderTrigger({ onClick: handleClick })}</>;
+  return (
+    <button
+      type="button"
+      className={className}
+      data-pyric-ui="clear-users"
+      data-pyric-destructive
+      onClick={handleClick}
+    >
+      Clear all users
+    </button>
+  );
+}

package/src/auth/controller.ts

@@ -0,0 +1,173 @@
+/**
+ * Sign-in helper controller — the host side of `pyric/auth`'s
+ * `AuthFlowResolver` seam.
+ *
+ * `pyric/auth` stays UI-free: `signInWithPopup` / `signInWithRedirect`
+ * delegate to a resolver. This controller IS that resolver's host
+ * implementation — it parks the SDK's promise, drives a host UI (an
+ * account picker + add-account form, e.g. `<AuthSignInHelper>`), and
+ * settles the promise when the user picks an identity, adds one, or
+ * cancels. React components stay thin presentational shells over this;
+ * all the settle/seed logic lives here so it's testable without a DOM.
+ *
+ * Faithful to the Firebase emulator: "add account" mints a sandbox
+ * identity with optional custom claims (the emulator's
+ * `customAttributes`), so a rule gated on `request.auth.token.<claim>`
+ * works against live sandbox traffic. Credential + token synthesis is
+ * backend-owned (`sandbox.createSignInCredential`) — this controller
+ * only drives the UI flow and settles the parked promise.
+ */
+import {
+  sandbox as authSandbox,
+  type Auth,
+  type AuthFlowRequest,
+  type AuthFlowResolver,
+  type UserCredential,
+} from 'pyric/auth';
+
+/** A field set for "add new account" — mirrors the emulator's add-user form. */
+export interface NewIdentitySpec {
+  email: string;
+  displayName?: string;
+  /** Parsed custom claims (the emulator's `customAttributes`). */
+  customClaims?: Record<string, unknown>;
+}
+
+/** One pickable identity, as reported by `sandbox.listIdentities`. */
+export type SandboxIdentity = ReturnType<typeof authSandbox.listIdentities>[number];
+
+/** Snapshot the helper UI renders from. */
+export interface HelperState {
+  /** The in-flight request, or null when the helper is closed. */
+  request: AuthFlowRequest | null;
+  /** Existing identities to pick from (seeded + previously created). */
+  identities: SandboxIdentity[];
+}
+
+type Pending = {
+  req: AuthFlowRequest;
+  resolve: (c: UserCredential) => void;
+  reject: (e: unknown) => void;
+};
+
+export class AuthFlowController {
+  private pending: Pending | null = null;
+  private readonly listeners = new Set<() => void>();
+  /** Memoized {@link snapshot} result, invalidated by {@link emit}.
+   *  `useSyncExternalStore` compares consecutive `getSnapshot()` results
+   *  with `Object.is` — an uncached object here re-renders forever. */
+  private cached: HelperState | null = null;
+
+  constructor(private readonly auth: Auth) {}
+
+  /** Wire this controller's resolver into the auth handle. Paired with
+   *  {@link uninstall} for use in a React effect (install in the body,
+   *  uninstall in the cleanup) — StrictMode-safe. */
+  install(): void {
+    authSandbox.setAuthFlowResolver(this.auth, this.resolver());
+  }
+
+  uninstall(): void {
+    authSandbox.setAuthFlowResolver(this.auth, null);
+  }
+
+  /** The resolver to hand to `sandbox.setAuthFlowResolver`. Popup and
+   *  redirect share one implementation (the sandbox has no navigation). */
+  resolver(): AuthFlowResolver {
+    const open = (req: AuthFlowRequest): Promise<UserCredential> =>
+      new Promise<UserCredential>((resolve, reject) => {
+        // One helper at a time: a new request supersedes any stale pending.
+        if (this.pending) this.cancel();
+        this.pending = { req, resolve, reject };
+        this.emit();
+      });
+    return { openPopup: open, openRedirect: open };
+  }
+
+  // ─── React glue (subscribe + snapshot) ──────────────────────────────
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  snapshot(): HelperState {
+    this.cached ??= {
+      request: this.pending?.req ?? null,
+      identities: authSandbox.listIdentities(this.auth),
+    };
+    return this.cached;
+  }
+
+  private emit(): void {
+    this.cached = null;
+    for (const l of this.listeners) l();
+  }
+
+  // ─── UI actions ─────────────────────────────────────────────────────
+  /** Pick an existing identity (by uid). The backend mints the credential
+   *  (and records the provider on the identity). */
+  pick(uid: string): void {
+    const pending = this.pending;
+    if (!pending) return;
+    let cred: UserCredential;
+    try {
+      cred = authSandbox.createSignInCredential(this.auth, {
+        providerId: pending.req.providerId,
+        uid,
+      });
+    } catch (e) {
+      this.take()?.reject(e);
+      return;
+    }
+    this.take()?.resolve(cred);
+  }
+
+  /** Add + sign in as a new identity. The backend creates the identity
+   *  (so claims resolve in rules and it shows up in the picker next time)
+   *  and mints the credential in one step.
+   *
+   *  Credential creation happens BEFORE {@link take}'s emit: subscribers
+   *  recompute the snapshot synchronously on emit, so creating after would
+   *  publish a stale identity list (a `useSyncExternalStore` consumer
+   *  would miss the new account until the next unrelated emit). */
+  add(spec: NewIdentitySpec): void {
+    const pending = this.pending;
+    if (!pending) return;
+    let cred: UserCredential;
+    try {
+      cred = authSandbox.createSignInCredential(this.auth, {
+        providerId: pending.req.providerId,
+        spec: {
+          email: spec.email,
+          displayName: spec.displayName,
+          customClaims: spec.customClaims,
+        },
+      });
+    } catch (e) {
+      this.take()?.reject(e);
+      return;
+    }
+    this.take()?.resolve(cred);
+  }
+
+  /** Dismiss — rejects with the faithful `auth/popup-closed-by-user`. */
+  cancel(): void {
+    const p = this.take();
+    if (!p) return;
+    p.reject(authError('auth/popup-closed-by-user', 'The popup has been closed by the user before finalizing the operation.'));
+  }
+
+  private take(): Pending | null {
+    const p = this.pending;
+    this.pending = null;
+    this.emit();
+    return p;
+  }
+}
+
+function authError(code: string, message: string): Error & { code: string } {
+  const e = new Error(message) as Error & { code: string };
+  e.name = 'FirebaseError';
+  e.code = code;
+  return e;
+}

package/src/auth/hooks/index.ts

@@ -0,0 +1,36 @@
+export {
+  useAuthFlowHelper,
+  type UseAuthFlowHelperResult,
+} from './useAuthFlowHelper.js';
+export {
+  useAuthUsers,
+  type UseAuthUsersResult,
+} from './useAuthUsers.js';
+export {
+  useAuthProviderConfig,
+  type AuthProviderConfigEntry,
+  type UseAuthProviderConfigResult,
+} from './useAuthProviderConfig.js';
+export {
+  useAuthUserEditor,
+  type UseAuthUserEditorOptions,
+  type UseAuthUserEditorResult,
+} from './useAuthUserEditor.js';
+export {
+  authUserEditorReducer,
+  initAuthUserEditorState,
+  fieldsFromRecord,
+  validateAuthUserFields,
+  toCreateRequest,
+  toUpdateRequest,
+  type AuthUserEditorAction,
+  type AuthUserEditorErrors,
+  type AuthUserEditorFields,
+  type AuthUserEditorState,
+} from '../reducers/userEditor.js';
+export {
+  AuthFlowController,
+  type HelperState,
+  type NewIdentitySpec,
+  type SandboxIdentity,
+} from '../controller.js';

package/src/auth/hooks/useAuthFlowHelper.ts

@@ -0,0 +1,55 @@
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
+import type { Auth } from 'pyric/auth';
+import {
+  AuthFlowController,
+  type HelperState,
+  type NewIdentitySpec,
+} from '../controller.js';
+
+export interface UseAuthFlowHelperResult {
+  /** Render snapshot: the in-flight request (or null) + pickable identities. */
+  state: HelperState;
+  /** Settle the flow with an existing identity (by uid). */
+  pick: (uid: string) => void;
+  /** Create + sign in as a new identity (seeds it for next time). */
+  add: (spec: NewIdentitySpec) => void;
+  /** Dismiss — rejects the app's sign-in promise with
+   *  `auth/popup-closed-by-user` (faithful to `firebase/auth`). */
+  cancel: () => void;
+}
+
+/**
+ * Emulator-style sign-in helper for a sandbox `Auth` handle.
+ *
+ * Installs an {@link AuthFlowController} as the handle's
+ * `AuthFlowResolver` for the lifetime of the calling component — the
+ * analog of browser `getAuth` wiring `browserPopupRedirectResolver`.
+ * While mounted, any `signInWithPopup` / `signInWithRedirect` call made
+ * against `auth` parks on `state.request`; render an account-picker UI
+ * (e.g. `<AuthSignInHelper>`) from `state` and settle with
+ * `pick` / `add` / `cancel`.
+ *
+ * Install/uninstall is a paired effect, so the StrictMode double-mount
+ * installs and cleanly uninstalls. Sandbox-only: the controller throws
+ * `failed-precondition` if `auth` is prod-backed.
+ */
+export function useAuthFlowHelper(auth: Auth): UseAuthFlowHelperResult {
+  const controller = useMemo(() => new AuthFlowController(auth), [auth]);
+
+  useEffect(() => {
+    controller.install();
+    return () => controller.uninstall();
+  }, [controller]);
+
+  const state = useSyncExternalStore(
+    useCallback((cb: () => void) => controller.subscribe(cb), [controller]),
+    () => controller.snapshot(),
+    () => controller.snapshot(),
+  );
+
+  const pick = useCallback((uid: string) => controller.pick(uid), [controller]);
+  const add = useCallback((spec: NewIdentitySpec) => controller.add(spec), [controller]);
+  const cancel = useCallback(() => controller.cancel(), [controller]);
+
+  return { state, pick, add, cancel };
+}

package/src/auth/hooks/useAuthProviderConfig.ts

@@ -0,0 +1,139 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { Auth } from 'pyric/auth';
+import { useAuthApi } from '../authApi.js';
+
+/** One provider's current enablement, as the hook exposes it. */
+export interface AuthProviderConfigEntry {
+  providerId: string;
+  enabled: boolean;
+}
+
+export interface UseAuthProviderConfigResult {
+  /** Every provider this sandbox has an explicit enablement for. Unknown
+   *  providers (never toggled) are simply absent — `isEnabled` treats an
+   *  absent entry as enabled, matching the backend default. */
+  config: AuthProviderConfigEntry[];
+  isLoading: boolean;
+  error: Error | undefined;
+  /** Convenience lookup: `true` for a provider that's never been toggled. */
+  isEnabled: (providerId: string) => boolean;
+  /** Toggle a provider on/off. Sync (in-process) failures throw to the
+   *  caller, same policy as `useAuthUsers`'s mutation callbacks; an ASYNC
+   *  (worker-RPC) failure can't reach a sync caller, so it surfaces on the
+   *  hook's `error` state instead — never an unhandled rejection. */
+  setEnabled: (providerId: string, enabled: boolean) => void;
+  /** Re-read manually. Rarely needed — every mutation (this hook's own
+   *  `setEnabled`, another handle, the agent) already triggers the
+   *  subscription re-list. */
+  refresh: () => void;
+}
+
+/**
+ * Live sign-in provider config view over a sandbox `Auth` handle:
+ * `sandbox.getAuthProviderConfig` + `sandbox.subscribeAuthProviderConfig` +
+ * `sandbox.setAuthProviderConfig`. Mirrors `useAuthUsers`'s shape exactly
+ * (coarse "something changed, re-list" subscription; sync in-process,
+ * tolerates a promise over the SharedWorker client).
+ *
+ * Sandbox-only: throws `failed-precondition` on a prod-backed handle (the
+ * hook surfaces that via `error`, same as `useAuthUsers`).
+ */
+export function useAuthProviderConfig(auth: Auth): UseAuthProviderConfigResult {
+  const {
+    getAuthProviderConfig,
+    setAuthProviderConfig: apiSetAuthProviderConfig,
+    subscribeAuthProviderConfig,
+  } = useAuthApi();
+
+  const [config, setConfig] = useState<AuthProviderConfigEntry[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | undefined>(undefined);
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    setError(undefined);
+    const apply = (c: AuthProviderConfigEntry[]) => {
+      if (cancelled) return;
+      setConfig(c);
+      setIsLoading(false);
+    };
+    const applyErr = (e: unknown) => {
+      if (cancelled) return;
+      setConfig([]);
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setIsLoading(false);
+    };
+    // `getAuthProviderConfig` is SYNC in-process, ASYNC (RPC) over the worker
+    // — same thenable-tolerant branch `useAuthUsers` uses for `listUsers`.
+    const relist = () => {
+      try {
+        const r = getAuthProviderConfig(auth) as
+          | AuthProviderConfigEntry[]
+          | Promise<AuthProviderConfigEntry[]>;
+        if (r && typeof (r as Promise<AuthProviderConfigEntry[]>).then === 'function') {
+          (r as Promise<AuthProviderConfigEntry[]>).then(apply).catch(applyErr);
+        } else {
+          apply(r as AuthProviderConfigEntry[]);
+        }
+      } catch (e) {
+        applyErr(e);
+      }
+    };
+    let unsub: (() => void) | undefined;
+    try {
+      relist();
+      unsub = subscribeAuthProviderConfig(auth, relist);
+    } catch (e) {
+      applyErr(e);
+    }
+    return () => {
+      cancelled = true;
+      unsub?.();
+    };
+  }, [auth, getAuthProviderConfig, subscribeAuthProviderConfig]);
+
+  const isEnabled = useCallback(
+    (providerId: string) => config.find((c) => c.providerId === providerId)?.enabled ?? true,
+    [config],
+  );
+
+  const toError = (e: unknown) => (e instanceof Error ? e : new Error(String(e)));
+
+  const setEnabled = useCallback(
+    (providerId: string, enabled: boolean) => {
+      // Over the worker this is an RPC promise — a fire-and-forget caller
+      // would otherwise leave a rejection unhandled and the toggle silently
+      // dead. Route async failures into the hook's error state; sync throws
+      // still propagate (in-process policy, matching useAuthUsers).
+      const r = apiSetAuthProviderConfig(auth, providerId, enabled) as void | Promise<void>;
+      if (r && typeof (r as Promise<void>).then === 'function') {
+        (r as Promise<void>).catch((e) => setError(toError(e)));
+      }
+    },
+    [auth, apiSetAuthProviderConfig],
+  );
+
+  const refresh = useCallback(() => {
+    try {
+      const r = getAuthProviderConfig(auth) as
+        | AuthProviderConfigEntry[]
+        | Promise<AuthProviderConfigEntry[]>;
+      if (r && typeof (r as Promise<AuthProviderConfigEntry[]>).then === 'function') {
+        void (r as Promise<AuthProviderConfigEntry[]>)
+          .then((c) => {
+            setConfig(c);
+            setError(undefined);
+          })
+          .catch((e) => setError(toError(e)));
+      } else {
+        setConfig(r as AuthProviderConfigEntry[]);
+        setError(undefined);
+      }
+    } catch (e) {
+      setError(toError(e));
+    }
+  }, [auth, getAuthProviderConfig]);
+
+  return { config, isLoading, error, isEnabled, setEnabled, refresh };
+}

package/src/auth/hooks/useAuthUserEditor.ts

@@ -0,0 +1,76 @@
+import { useCallback, useMemo, useReducer } from 'react';
+import type { AuthUserRecord, CreateUserRequest, UpdateUserRequest } from 'pyric/auth';
+import {
+  authUserEditorReducer,
+  initAuthUserEditorState,
+  isDirty as computeDirty,
+  toCreateRequest,
+  toUpdateRequest,
+  validateAuthUserFields,
+  type AuthUserEditorAction,
+  type AuthUserEditorErrors,
+  type AuthUserEditorFields,
+} from '../reducers/userEditor.js';
+
+export interface UseAuthUserEditorOptions {
+  /** Existing record to edit. Omit for create mode. */
+  initial?: AuthUserRecord;
+}
+
+export interface UseAuthUserEditorResult {
+  fields: AuthUserEditorFields;
+  /** Per-field validation messages (emulator-UI wording). Empty when valid. */
+  errors: AuthUserEditorErrors;
+  isDirty: boolean;
+  isValid: boolean;
+  setField: <K extends keyof AuthUserEditorFields>(
+    field: K,
+    value: AuthUserEditorFields[K],
+  ) => void;
+  /** Back to the initial snapshot. */
+  reset: () => void;
+  /** Full payload for `createUser` (every non-empty field). */
+  toCreateRequest: () => CreateUserRequest;
+  /** Delta payload for `updateUser` (only changed fields). */
+  toUpdateRequest: () => UpdateUserRequest;
+  /** Raw reducer access for advanced consumers. */
+  dispatch: (action: AuthUserEditorAction) => void;
+}
+
+/**
+ * Headless add/edit-user state machine (reducer-based, like
+ * `useDocumentEditor`): field edits, claims-JSON validation with
+ * emulator-grade messages, dirtiness vs the initial record, and payload
+ * builders for `useAuthUsers`' `createUser` / `updateUser`.
+ */
+export function useAuthUserEditor(
+  options: UseAuthUserEditorOptions = {},
+): UseAuthUserEditorResult {
+  const [state, dispatch] = useReducer(
+    authUserEditorReducer,
+    options.initial,
+    initAuthUserEditorState,
+  );
+
+  const errors = useMemo(() => validateAuthUserFields(state.fields), [state.fields]);
+  const dirty = useMemo(() => computeDirty(state), [state]);
+
+  const setField = useCallback(
+    <K extends keyof AuthUserEditorFields>(field: K, value: AuthUserEditorFields[K]) =>
+      dispatch({ type: 'setField', field, value }),
+    [],
+  );
+  const reset = useCallback(() => dispatch({ type: 'reset' }), []);
+
+  return {
+    fields: state.fields,
+    errors,
+    isDirty: dirty,
+    isValid: Object.keys(errors).length === 0,
+    setField,
+    reset,
+    toCreateRequest: () => toCreateRequest(state),
+    toUpdateRequest: () => toUpdateRequest(state),
+    dispatch,
+  };
+}