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

package/src/auth/hooks/useAuthUsers.ts

@@ -0,0 +1,154 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import type {
+  Auth,
+  AuthUserRecord,
+  CreateUserRequest,
+  UpdateUserRequest,
+} from 'pyric/auth';
+import { useAuthApi } from '../authApi.js';
+
+export interface UseAuthUsersResult {
+  /** Users matching {@link filter} (everyone when the filter is empty). */
+  users: AuthUserRecord[];
+  /** Unfiltered count: lets a list distinguish "no users at all" from
+   *  "no results for this filter". */
+  totalCount: number;
+  isLoading: boolean;
+  error: Error | undefined;
+  /** Case-insensitive substring match over uid, email, display name and
+   *  phone number (the emulator UI's search semantics). */
+  filter: string;
+  setFilter: (filter: string) => void;
+  createUser: (request: CreateUserRequest) => AuthUserRecord;
+  updateUser: (uid: string, update: UpdateUserRequest) => AuthUserRecord;
+  deleteUser: (uid: string) => void;
+  clearUsers: () => void;
+  /** Re-list manually. Rarely needed, every mutation (including ones made
+   *  by the agent or the running app) already triggers `subscribeUsers`. */
+  refresh: () => void;
+}
+
+function matches(user: AuthUserRecord, needle: string): boolean {
+  return [user.uid, user.email, user.displayName, user.phoneNumber].some(
+    (v) => v != null && v.toLowerCase().includes(needle),
+  );
+}
+
+/**
+ * Live user-admin view over a sandbox `Auth` handle:
+ * `sandbox.listUsers` + `sandbox.subscribeUsers` + CRUD actions.
+ *
+ * The subscription is coarse ("something changed"): any user-DB
+ * mutation (from these actions, the running app's sign-ups, the
+ * agent's seeding) triggers a re-list, so the view stays live without
+ * per-row bookkeeping. Filtering is client-side (the sandbox is
+ * in-process; there is no server to push the query to).
+ *
+ * Mutation errors (e.g. `auth/uid-already-exists`) throw to the caller:
+ * handle them at the call site like the firestore hooks' `createDocument`.
+ * Sandbox-only: throws `failed-precondition` on a prod-backed handle (the
+ * hook surfaces that via `error`).
+ */
+export function useAuthUsers(auth: Auth): UseAuthUsersResult {
+  // The sandbox auth ops, injected: in-process `pyric/auth` by default, or the
+  // SharedWorker client bundle when a consumer (Pyric Studio served mode) wraps
+  // the tree in an `AuthApiProvider`.
+  const {
+    listUsers,
+    subscribeUsers,
+    createUser: apiCreateUser,
+    updateUser: apiUpdateUser,
+    deleteUser: apiDeleteUser,
+    clearUsers: apiClearUsers,
+  } = useAuthApi();
+  const [all, setAll] = useState<AuthUserRecord[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [filter, setFilter] = useState('');
+
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    setError(undefined);
+    const applyUsers = (u: AuthUserRecord[]) => {
+      if (cancelled) return;
+      setAll(u);
+      setIsLoading(false);
+    };
+    const applyErr = (e: unknown) => {
+      if (cancelled) return;
+      setAll([]);
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setIsLoading(false);
+    };
+    // `listUsers` is SYNC in-process (apply immediately, preserving the sync
+    // contract existing consumers + tests rely on) but ASYNC over the worker (an
+    // RPC), so branch on a thenable. The subscription is coarse: re-list on any
+    // change.
+    const relist = () => {
+      try {
+        const r = listUsers(auth) as AuthUserRecord[] | Promise<AuthUserRecord[]>;
+        if (r && typeof (r as Promise<AuthUserRecord[]>).then === 'function') {
+          (r as Promise<AuthUserRecord[]>).then(applyUsers).catch(applyErr);
+        } else {
+          applyUsers(r as AuthUserRecord[]);
+        }
+      } catch (e) {
+        applyErr(e);
+      }
+    };
+    let unsub: (() => void) | undefined;
+    try {
+      relist();
+      unsub = subscribeUsers(auth, relist);
+    } catch (e) {
+      applyErr(e);
+    }
+    return () => {
+      cancelled = true;
+      unsub?.();
+    };
+  }, [auth, listUsers, subscribeUsers]);
+
+  const users = useMemo(() => {
+    const needle = filter.trim().toLowerCase();
+    if (!needle) return all;
+    return all.filter((u) => matches(u, needle));
+  }, [all, filter]);
+
+  const createUser = useCallback(
+    (request: CreateUserRequest) => apiCreateUser(auth, request),
+    [auth, apiCreateUser],
+  );
+  const updateUser = useCallback(
+    (uid: string, update: UpdateUserRequest) => apiUpdateUser(auth, uid, update),
+    [auth, apiUpdateUser],
+  );
+  const deleteUser = useCallback(
+    (uid: string) => apiDeleteUser(auth, uid),
+    [auth, apiDeleteUser],
+  );
+  const clearUsers = useCallback(() => apiClearUsers(auth), [auth, apiClearUsers]);
+  const refresh = useCallback(() => {
+    const r = listUsers(auth) as AuthUserRecord[] | Promise<AuthUserRecord[]>;
+    if (r && typeof (r as Promise<AuthUserRecord[]>).then === 'function') {
+      void (r as Promise<AuthUserRecord[]>).then((u) => setAll(u)).catch(() => {});
+    } else {
+      setAll(r as AuthUserRecord[]);
+    }
+  }, [auth, listUsers]);
+
+  return {
+    users,
+    totalCount: all.length,
+    isLoading,
+    error,
+    filter,
+    setFilter,
+    createUser,
+    updateUser,
+    deleteUser,
+    clearUsers,
+    refresh,
+  };
+}

package/src/auth/index.ts

@@ -0,0 +1,42 @@
+export * from './hooks/index.js';
+
+// Injectable auth API bundle (Pyric Studio data-backend swap): defaults to
+// in-process `pyric/auth`; a consumer can provide the SharedWorker client.
+export { AuthApiProvider, useAuthApi, type AuthApi } from './authApi.js';
+export {
+  AuthSignInHelper,
+  type AuthSignInHelperProps,
+} from './components/AuthSignInHelper.js';
+export {
+  AuthUserList,
+  type AuthUserListProps,
+} from './components/AuthUserList.js';
+export {
+  AuthProviderToggles,
+  DEFAULT_KNOWN_PROVIDER_IDS,
+  type AuthProviderTogglesProps,
+} from './components/AuthProviderToggles.js';
+export {
+  AuthUserForm,
+  type AuthUserFormField,
+  type AuthUserFormFieldName,
+  type AuthUserFormProps,
+  type AuthUserFormSubmit,
+} from './components/AuthUserForm.js';
+export {
+  ClaimsField,
+  type ClaimsFieldProps,
+} from './components/ClaimsField.js';
+export {
+  DeleteUserWithConfirm,
+  type DeleteUserWithConfirmProps,
+  ClearUsersWithConfirm,
+  type ClearUsersWithConfirmProps,
+} from './components/confirmActions.js';
+export {
+  validateSerializedClaims,
+  FORBIDDEN_CUSTOM_CLAIMS,
+  CUSTOM_CLAIMS_MAX_LENGTH,
+  type ClaimsValidationResult,
+} from './claims.js';
+export { PROVIDER_LABELS, providerLabel } from './providers.js';

package/src/auth/providers.ts

@@ -0,0 +1,28 @@
+/**
+ * Provider-id → human label mapping, mirroring the provider set the
+ * Firebase emulator UI recognizes (it maps the same ids to icons; a
+ * headless library maps them to text and leaves icons to the consumer
+ * via `data-pyric-provider-id`).
+ */
+export const PROVIDER_LABELS: Record<string, string> = {
+  'google.com': 'Google',
+  'apple.com': 'Apple',
+  'gc.apple.com': 'Game Center',
+  'facebook.com': 'Facebook',
+  'github.com': 'GitHub',
+  'microsoft.com': 'Microsoft',
+  'playgames.google.com': 'Play Games',
+  'twitter.com': 'Twitter',
+  'yahoo.com': 'Yahoo',
+  password: 'Email/Password',
+  phone: 'Phone',
+  anonymous: 'Anonymous',
+  oidc: 'OIDC',
+  saml: 'SAML',
+};
+
+/** Label for a provider id; falls back to the raw id for custom
+ *  `OAuthProvider` ids the map doesn't know. */
+export function providerLabel(providerId: string): string {
+  return PROVIDER_LABELS[providerId] ?? providerId;
+}

package/src/auth/reducers/userEditor.ts

@@ -0,0 +1,186 @@
+/**
+ * Reducer behind `useAuthUserEditor` — pure, React-free (drivable from
+ * tests or non-React hosts, like the firestore `documentEditor` reducer).
+ *
+ * Validation messages match the Firebase emulator UI:
+ * - email pattern → "Invalid email"
+ * - password length → "Password should be at least 6 characters"
+ * - password without email → "Email is required for password authentication"
+ * - claims → `validateSerializedClaims` messages
+ */
+import type { AuthUserRecord, CreateUserRequest, UpdateUserRequest } from 'pyric/auth';
+import { validateSerializedClaims } from '../claims.js';
+
+/** Editable field set. `claimsText` is the raw textarea JSON.
+ *  `providerIds` are the linked FEDERATED providers (`google.com`,
+ *  `apple.com`, …) — `password` is credential-derived (the password
+ *  field) and never appears here. */
+export interface AuthUserEditorFields {
+  email: string;
+  password: string;
+  displayName: string;
+  phoneNumber: string;
+  photoUrl: string;
+  emailVerified: boolean;
+  disabled: boolean;
+  claimsText: string;
+  providerIds: string[];
+}
+
+export interface AuthUserEditorState {
+  fields: AuthUserEditorFields;
+  /** What {@link reset} returns to; dirtiness is measured against this. */
+  initial: AuthUserEditorFields;
+}
+
+export type AuthUserEditorAction =
+  | {
+      type: 'setField';
+      field: keyof AuthUserEditorFields;
+      value: AuthUserEditorFields[keyof AuthUserEditorFields];
+    }
+  | { type: 'reset' };
+
+export interface AuthUserEditorErrors {
+  email?: string;
+  password?: string;
+  claims?: string;
+}
+
+const EMPTY_FIELDS: AuthUserEditorFields = {
+  email: '',
+  password: '',
+  displayName: '',
+  phoneNumber: '',
+  photoUrl: '',
+  emailVerified: false,
+  disabled: false,
+  claimsText: '',
+  providerIds: [],
+};
+
+/** Credential-derived / token-level ids — sign-in methods, not linkable
+ *  federated entries (mirrors the sandbox backend's rule). */
+const NON_FEDERATED_IDS = new Set(['password', 'anonymous', 'phone']);
+
+/** Same permissive shape the emulator UI uses (`pattern` validation). */
+const EMAIL_REGEX = /^[^@]+@[^@]+\.[^@]+$/;
+const PASSWORD_MIN_LENGTH = 6;
+
+export function fieldsFromRecord(record?: AuthUserRecord): AuthUserEditorFields {
+  if (!record) return { ...EMPTY_FIELDS };
+  return {
+    email: record.email ?? '',
+    password: '',
+    displayName: record.displayName ?? '',
+    phoneNumber: record.phoneNumber ?? '',
+    photoUrl: record.photoUrl ?? '',
+    emailVerified: record.emailVerified,
+    disabled: record.disabled,
+    claimsText: Object.keys(record.customClaims).length
+      ? JSON.stringify(record.customClaims, null, 2)
+      : '',
+    providerIds: record.providerUserInfo
+      .map((p) => p.providerId)
+      .filter((id) => !NON_FEDERATED_IDS.has(id)),
+  };
+}
+
+export function initAuthUserEditorState(initial?: AuthUserRecord): AuthUserEditorState {
+  const fields = fieldsFromRecord(initial);
+  return { fields, initial: { ...fields } };
+}
+
+export function authUserEditorReducer(
+  state: AuthUserEditorState,
+  action: AuthUserEditorAction,
+): AuthUserEditorState {
+  switch (action.type) {
+    case 'setField':
+      return { ...state, fields: { ...state.fields, [action.field]: action.value } };
+    case 'reset':
+      return { ...state, fields: { ...state.initial } };
+  }
+}
+
+export function validateAuthUserFields(fields: AuthUserEditorFields): AuthUserEditorErrors {
+  const errors: AuthUserEditorErrors = {};
+  const email = fields.email.trim();
+  const password = fields.password;
+  if (email && !EMAIL_REGEX.test(email)) {
+    errors.email = 'Invalid email';
+  }
+  if (password && password.length < PASSWORD_MIN_LENGTH) {
+    errors.password = `Password should be at least ${PASSWORD_MIN_LENGTH} characters`;
+  }
+  if (password && !email) {
+    errors.password = 'Email is required for password authentication';
+  }
+  const claims = validateSerializedClaims(fields.claimsText);
+  if (!claims.ok) errors.claims = claims.message;
+  return errors;
+}
+
+export function isDirty(state: AuthUserEditorState): boolean {
+  const { fields, initial } = state;
+  return (Object.keys(fields) as Array<keyof AuthUserEditorFields>).some((k) =>
+    k === 'providerIds'
+      ? !sameIds(fields.providerIds, initial.providerIds)
+      : fields[k] !== initial[k],
+  );
+}
+
+/** Order-insensitive id-list equality (toggling A then B ≡ B then A). */
+function sameIds(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  const sorted = [...b].sort();
+  return [...a].sort().every((id, i) => id === sorted[i]);
+}
+
+function parsedClaims(fields: AuthUserEditorFields): Record<string, unknown> | undefined {
+  const r = validateSerializedClaims(fields.claimsText);
+  return r.ok ? r.claims : undefined;
+}
+
+/** Full payload for `sandbox.createUser` — every non-empty field. */
+export function toCreateRequest(state: AuthUserEditorState): CreateUserRequest {
+  const f = state.fields;
+  const req: CreateUserRequest = {
+    emailVerified: f.emailVerified,
+    disabled: f.disabled,
+  };
+  if (f.email.trim()) req.email = f.email.trim();
+  if (f.password) req.password = f.password;
+  if (f.displayName.trim()) req.displayName = f.displayName.trim();
+  if (f.phoneNumber.trim()) req.phoneNumber = f.phoneNumber.trim();
+  if (f.photoUrl.trim()) req.photoUrl = f.photoUrl.trim();
+  const claims = parsedClaims(f);
+  if (claims) req.customClaims = claims;
+  if (f.providerIds.length) {
+    req.providerUserInfo = f.providerIds.map((providerId) => ({ providerId }));
+  }
+  return req;
+}
+
+/** Delta payload for `sandbox.updateUser` — only fields that changed
+ *  from the initial record. A cleared displayName maps to `null`
+ *  (the update API's clear semantics). */
+export function toUpdateRequest(state: AuthUserEditorState): UpdateUserRequest {
+  const { fields: f, initial: i } = state;
+  const req: UpdateUserRequest = {};
+  if (f.email.trim() !== i.email && f.email.trim()) req.email = f.email.trim();
+  if (f.password && f.password !== i.password) req.password = f.password;
+  if (f.displayName.trim() !== i.displayName) {
+    req.displayName = f.displayName.trim() || null;
+  }
+  if (f.emailVerified !== i.emailVerified) req.emailVerified = f.emailVerified;
+  if (f.disabled !== i.disabled) req.disabled = f.disabled;
+  if (f.claimsText !== i.claimsText) {
+    req.customClaims = parsedClaims(f) ?? {};
+  }
+  if (!sameIds(f.providerIds, i.providerIds)) {
+    // Replacement semantics; the backend re-derives the password entry.
+    req.providerUserInfo = f.providerIds.map((providerId) => ({ providerId }));
+  }
+  return req;
+}

package/src/events/components/ActivityActionItems.tsx

@@ -0,0 +1,136 @@
+import type { ReactNode } from 'react';
+import type { ActivityDigest, ActivityRow } from '../digest.js';
+
+/** A single action item — a mechanical fact that invites a decision. */
+export interface ActivityActionItem {
+  /** Stable key. */
+  key: string;
+  /** What it is — drives `data-pyric-action-type`. Today: `denied`. */
+  type: 'denied';
+  /** The headline (mechanical: "4 writes to /notes were denied"). */
+  title: string;
+  /** Sub-line — attribution / cause. */
+  meta?: string;
+  /** The rows this item summarizes — for drill-in / linking into the
+   *  matching Activity band (items LINK to bands, they don't duplicate). */
+  rows: ActivityRow[];
+}
+
+export interface ActivityActionItemsProps {
+  digest: ActivityDigest;
+  /** Render the action button/affordance for an item (e.g. a "Debug"
+   *  link). Returns `null` to render no action. */
+  renderAction?: (item: ActivityActionItem) => ReactNode;
+  /** Override item-title composition (host owns app-semantic copy). */
+  renderTitle?: (item: ActivityActionItem) => ReactNode;
+  className?: string;
+  /** Rendered when there are no action items — default renders nothing
+   *  (calm by default; the region collapses). */
+  emptyState?: ReactNode;
+}
+
+/**
+ * Group denial rows by collection prefix so the headline aggregates
+ * ("4 writes to /notes were denied") rather than listing each row.
+ */
+function buildDenialItems(digest: ActivityDigest): ActivityActionItem[] {
+  if (digest.denials.length === 0) return [];
+  const byPrefix = new Map<string, ActivityRow[]>();
+  for (const r of digest.denials) {
+    // Collection prefix = everything up to the last segment.
+    const i = r.target.lastIndexOf('/');
+    const prefix = i === -1 ? r.target : r.target.slice(0, i);
+    const key = prefix ? `/${prefix.replace(/^\/+/, '')}` : '(root)';
+    const list = byPrefix.get(key);
+    if (list) list.push(r);
+    else byPrefix.set(key, [r]);
+  }
+  const items: ActivityActionItem[] = [];
+  for (const [prefix, rows] of byPrefix) {
+    const subjects = new Set(
+      rows.map((r) => r.subjectUid).filter((u): u is string => !!u),
+    );
+    const n = rows.length;
+    const noun = n === 1 ? 'write' : 'writes';
+    const title = `${n} ${noun} to ${prefix} ${n === 1 ? 'was' : 'were'} denied`;
+    const meta =
+      subjects.size === 1
+        ? `All by ${[...subjects][0]}.`
+        : subjects.size > 1
+          ? `By ${subjects.size} users.`
+          : undefined;
+    const item: ActivityActionItem = {
+      key: `denied:${prefix}`,
+      type: 'denied',
+      title,
+      rows,
+    };
+    if (meta) item.meta = meta;
+    items.push(item);
+  }
+  // Most denials first.
+  items.sort((a, b) => b.rows.length - a.rows.length);
+  return items;
+}
+
+/**
+ * The action-items tier — the few things wanting a decision, surfaced
+ * ABOVE the activity grid (design-ideation Tier 2 / "Needs you").
+ * Denials lead and are first-class. Mechanical copy by default; the host
+ * supplies the action affordance (e.g. a "Debug" link into the rules
+ * debugger) via `renderAction`.
+ *
+ * Data contract:
+ * - `[data-pyric-ui="activity-action-items"]` — the root (absent when
+ *   empty and no `emptyState`).
+ * - `[data-pyric-action-item]` (+ `data-pyric-action-type`,
+ *   `data-pyric-action-count`) — one item.
+ * - `[data-pyric-action-title]` / `[data-pyric-action-meta]` — the copy.
+ * - `[data-pyric-action-affordance]` — wraps the host's action node.
+ */
+export function ActivityActionItems({
+  digest,
+  renderAction,
+  renderTitle,
+  className,
+  emptyState,
+}: ActivityActionItemsProps): ReactNode {
+  const items = buildDenialItems(digest);
+
+  if (items.length === 0) {
+    return emptyState ? (
+      <div
+        className={className}
+        data-pyric-ui="activity-action-items"
+        data-pyric-empty=""
+      >
+        {emptyState}
+      </div>
+    ) : null;
+  }
+
+  return (
+    <div className={className} data-pyric-ui="activity-action-items">
+      {items.map((item) => (
+        <div
+          key={item.key}
+          data-pyric-action-item=""
+          data-pyric-action-type={item.type}
+          data-pyric-action-count={item.rows.length}
+        >
+          <div data-pyric-action-what="">
+            <div data-pyric-action-title="">
+              {renderTitle ? renderTitle(item) : item.title}
+            </div>
+            {item.meta ? (
+              <div data-pyric-action-meta="">{item.meta}</div>
+            ) : null}
+          </div>
+          {renderAction ? (
+            <div data-pyric-action-affordance="">{renderAction(item)}</div>
+          ) : null}
+        </div>
+      ))}
+    </div>
+  );
+}