@indietabletop/appkit 3.6.0-1 → 3.6.0-3

package/lib/account/LoginPage.stories.tsx

@@ -0,0 +1,318 @@
+import { Story } from "@storybook/addon-docs/blocks";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { http, HttpResponse } from "msw";
+import { fn } from "storybook/test";
+import { sleep } from "../sleep.ts";
+import type { CurrentUser, SessionInfo } from "../types.ts";
+import { LoginCard } from "./LoginPage.tsx";
+
+function createMocks(options?: { responseSpeed?: number }) {
+  const simulateNetwork = () => sleep(options?.responseSpeed ?? 2000);
+
+  const john: CurrentUser = {
+    id: "john",
+    email: "john@example.com",
+    isVerified: true,
+  };
+
+  const mary: CurrentUser = {
+    id: "mary",
+    email: "mary@example.com",
+    isVerified: true,
+  };
+
+  const sessionInfo: SessionInfo = {
+    createdTs: 123,
+    expiresTs: 123,
+  };
+
+  return {
+    data: { john, mary },
+    handlers: {
+      refreshTokens: {
+        failed: () => {
+          return http.post(
+            "http://mock.api/v1/sessions/access-tokens",
+            async () => {
+              await simulateNetwork();
+              return HttpResponse.text("Refresh token expired or missing", {
+                status: 401,
+              });
+            },
+          );
+        },
+      },
+
+      getCurrentUser: {
+        success: (currentUser: CurrentUser) => {
+          return http.get("http://mock.api/v1/users/me", async () => {
+            await simulateNetwork();
+            return HttpResponse.json(currentUser);
+          });
+        },
+
+        /**
+         * Cookie is valid, but user doesn't exist any more. This can happen
+         * after user deletion.
+         */
+        notFound: () => {
+          return http.get("http://mock.api/v1/users/me", async () => {
+            await simulateNetwork();
+            return HttpResponse.text("User not found", { status: 404 });
+          });
+        },
+
+        noConnection: () => {
+          return http.get("http://mock.api/v1/users/me", async () => {
+            return HttpResponse.error();
+          });
+        },
+
+        unknownFailure: () => {
+          return http.get("http://mock.api/v1/users/me", async () => {
+            await simulateNetwork();
+            return HttpResponse.text("Internal server error", { status: 500 });
+          });
+        },
+
+        /**
+         * Auth cookies no longer valid to make this request.
+         */
+        notAuthenticated: () => {
+          return http.get("http://mock.api/v1/users/me", async () => {
+            await simulateNetwork();
+            return HttpResponse.text("Not authenticated", { status: 401 });
+          });
+        },
+      },
+
+      createNewSession: {
+        success: (currentUser: CurrentUser) => {
+          return http.post("http://mock.api/v1/sessions", async () => {
+            await simulateNetwork();
+            return HttpResponse.json({ currentUser, sessionInfo });
+          });
+        },
+
+        invalidCredentials: () => {
+          return http.post("http://mock.api/v1/sessions", async () => {
+            await simulateNetwork();
+            return HttpResponse.text("Credentials do not match", {
+              status: 401,
+            });
+          });
+        },
+
+        userNotFound: () => {
+          return http.post("http://mock.api/v1/sessions", async () => {
+            await simulateNetwork();
+            return HttpResponse.text("User not found", { status: 404 });
+          });
+        },
+
+        unknownFailure: () => {
+          return http.post("http://mock.api/v1/sessions", async () => {
+            await simulateNetwork();
+            return HttpResponse.text("Internal server error", { status: 500 });
+          });
+        },
+      },
+    },
+  };
+}
+
+const { data, handlers } = createMocks({ responseSpeed: 700 });
+
+/**
+ * Allows the user to log into Indie Tabletop Club.
+ */
+const meta = {
+  title: "Account/Login Page",
+  component: LoginCard,
+  tags: ["autodocs"],
+  args: {
+    currentUser: null,
+    description: "Log in to Indie Tabletop Club to enable backup & sync.",
+    onLogin: fn(),
+    onLogout: fn(),
+    onClearLocalContent: fn(),
+    onServerLogout: fn(),
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        refreshTokens: handlers.refreshTokens.failed(),
+      },
+    },
+  },
+} satisfies Meta<typeof LoginCard>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The majority case where no user is stored locally, proactive user session
+ * check returns 401, and subsequently correct credentials are provided.
+ */
+export const Default: Story = {
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.notAuthenticated(),
+        createNewSession: handlers.createNewSession.success(data.john),
+      },
+    },
+  },
+};
+
+/**
+ * Similar to the default case, but invalid credentials are provided to when
+ * attempting to create a new session.
+ */
+export const InvalidCredentialsOnSubmit: Story = {
+  args: {
+    currentUser: null,
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.notAuthenticated(),
+        createNewSession: handlers.createNewSession.invalidCredentials(),
+      },
+    },
+  },
+};
+
+/**
+ * Similar to the default case, but when credentials are provided, an account
+ * email is used that is not currently in the database.
+ */
+export const UserNotFoundOnSubmit: Story = {
+  args: {
+    currentUser: null,
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.notAuthenticated(),
+        createNewSession: handlers.createNewSession.userNotFound(),
+      },
+    },
+  },
+};
+
+/**
+ * Similar to the default case, but the session creation call returns an error
+ * that doesn't have a specific meaning in the context of the login page.
+ */
+export const UnknownFailureOnSubmit: Story = {
+  args: {
+    currentUser: null,
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.notAuthenticated(),
+        createNewSession: handlers.createNewSession.unknownFailure(),
+      },
+    },
+  },
+};
+
+/**
+ * A case when user is stored locally, but their server session has expired.
+ */
+export const ReauthenticateSession: Story = {
+  args: {
+    currentUser: data.john,
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.notAuthenticated(),
+        createNewSession: handlers.createNewSession.success(data.john),
+      },
+    },
+  },
+};
+
+/**
+ * The user is already stored in the app, and proactive user-session check
+ * returns the same user (based on ID).
+ *
+ * The user is directed to app without any further steps.
+ */
+export const AlreadyLoggedIn: Story = {
+  args: {
+    currentUser: data.john,
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.success(data.john),
+      },
+    },
+  },
+};
+
+/**
+ * A user is provided, and proactive user session check returns a different
+ * user. This can happen when different users log into separate apps with
+ * different credentials.
+ */
+export const UserMismatch: Story = {
+  args: {
+    currentUser: data.john,
+  },
+
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.success(data.mary),
+      },
+    },
+  },
+};
+
+/**
+ * During the proactive user session check, the user is reportd as not found.
+ * This means that the tokens are still valid, but the user DB entity is gone.
+ * This can happen if a user closed their account.
+ */
+export const UserNotFound: Story = {
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.notFound(),
+      },
+    },
+  },
+};
+
+/**
+ * The proactive user session check has failed due to connection issues.
+ */
+export const NoConnection: Story = {
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.noConnection(),
+      },
+    },
+  },
+};
+
+/**
+ * The proactive user session check has failed due to an error that doesn't
+ * carry any special meaning.
+ */
+export const UnknownFailure: Story = {
+  parameters: {
+    msw: {
+      handlers: {
+        getCurrentUser: handlers.getCurrentUser.unknownFailure(),
+      },
+    },
+  },
+};

package/lib/account/LoginPage.tsx

@@ -0,0 +1,138 @@
+import { type ReactNode } from "react";
+import type { CurrentUser } from "../types.ts";
+import { AccountIssueView } from "./AccountIssueView.tsx";
+import { AlreadyLoggedInView } from "./AlreadyLoggedInView.tsx";
+import { FailureFallbackView } from "./FailureFallbackView.tsx";
+import { LoadingView } from "./LoadingView.tsx";
+import { LoginView } from "./LoginView.tsx";
+import { NoConnectionView } from "./NoConnectionView.tsx";
+import type {
+  DefaultFormValues,
+  EventHandler,
+  EventHandlerWithReload,
+} from "./types.ts";
+import { useCurrentUserResult } from "./useCurrentUserResult.tsx";
+import { UserMismatchView } from "./UserMismatchView.tsx";
+
+export type LoginPageProps = {
+  /**
+   * Any user data that might currently be stored in persistent storage like
+   * `localStorage` or IndexedDB.
+   *
+   * If the app contains any local data, it is important that this value is
+   * provided so that we don't run into strange user mismatch issues!
+   */
+  currentUser: CurrentUser | null;
+
+  /**
+   * A description that will appear in the default login case (i.e. when an
+   * unauthenticated user is prompted to log in).
+   *
+   * This should reinforce to the user the benefits that they are going to
+   * get by signing in. Every app has slightly different capabilities, so this
+   * should be tailored for each individual app.
+   */
+  description: ReactNode;
+
+  /**
+   * Default values for the login form.
+   *
+   * You might want to provide a value from history state or query param, so
+   * that if a user jumps between multiple pages with email field, the email
+   * address is maintained across these locations.
+   */
+  defaultValues?: DefaultFormValues;
+
+  /**
+   * Called when the login action succeeds.
+   *
+   * Typically you want to redirect the user at this point, and possibly
+   * run additional side-effects.
+   *
+   * Note that it is not necessary to save the new current user in any way,
+   * as they will already be saved via the client onCurrentUser handler.
+   */
+  onLogin: EventHandler;
+
+  /**
+   * Called when the user indicates that they would like to log out.
+   *
+   * Typically, you might want to clear all local data, perform
+   * a server logout, and redirect to some sensible new location.
+   */
+  onLogout: EventHandlerWithReload;
+
+  /**
+   * Called when there is a mismatch between local user data and data returned
+   * from the server and the user chooses to use the server account.
+   *
+   * Local content should be cleared in response to this action, but **not**
+   * server logout (as the user is choosing to continue as the user that is
+   * currently referenced in the cookie).
+   */
+  onClearLocalContent: EventHandler;
+
+  /**
+   * Called when there is a mismatch between local user data and data returned
+   * from the server and the user chooses to use the local account.
+   *
+   * A server logout should be performed in response to this event, but local
+   * data should not be touched.
+   */
+  onServerLogout: EventHandlerWithReload;
+};
+
+export function LoginCard(props: LoginPageProps) {
+  const { currentUser } = props;
+  const { result, latestAttemptTs, reload } = useCurrentUserResult();
+
+  return result.unpack(
+    (serverUser) => {
+      if (currentUser && currentUser.id !== serverUser.id) {
+        return (
+          <UserMismatchView
+            {...props}
+            serverUser={serverUser}
+            localUser={currentUser}
+            reload={reload}
+          />
+        );
+      }
+
+      return (
+        <AlreadyLoggedInView
+          {...props}
+          currentUser={serverUser}
+          reload={reload}
+        />
+      );
+    },
+
+    (failure) => {
+      if (failure.type === "API_ERROR") {
+        if (failure.code === 401) {
+          return <LoginView {...props} reload={reload} />;
+        }
+
+        if (failure.code === 404) {
+          return <AccountIssueView {...props} reload={reload} />;
+        }
+      }
+
+      if (failure.type === "NETWORK_ERROR") {
+        return (
+          <NoConnectionView
+            latestAttemptTs={latestAttemptTs}
+            onRetry={() => reload()}
+          />
+        );
+      }
+
+      return <FailureFallbackView />;
+    },
+
+    () => {
+      return <LoadingView />;
+    },
+  );
+}

package/lib/account/LoginView.tsx

@@ -0,0 +1,136 @@
+import { Button, Form, useStoreState } from "@ariakit/react";
+import type { ReactNode } from "react";
+import { Link } from "wouter";
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
+import { interactiveText } from "../common.css.ts";
+import { getSubmitFailureMessage } from "../failureMessages.ts";
+import {
+  Letterhead,
+  LetterheadHeading,
+  LetterheadParagraph,
+  LetterheadSubmitButton,
+} from "../Letterhead/index.tsx";
+import {
+  InputsStack,
+  LetterheadFormActions,
+  LetterheadHeader,
+  LetterheadSubmitError,
+  LetterheadTextField,
+} from "../LetterheadForm/index.tsx";
+import type { CurrentUser } from "../types.ts";
+import { useForm } from "../use-form.ts";
+import { validEmail } from "../validations.ts";
+import type { DefaultFormValues, EventHandlerWithReload } from "./types.ts";
+
+export function LoginView(props: {
+  defaultValues?: DefaultFormValues;
+  onLogin: EventHandlerWithReload;
+  onLogout: EventHandlerWithReload;
+  currentUser: CurrentUser | null;
+  description: ReactNode;
+  reload: () => void;
+}) {
+  const { placeholders, client, hrefs } = useAppConfig();
+  const { defaultValues, description, currentUser, onLogin, onLogout, reload } =
+    props;
+  const localUserPresent = !!currentUser?.email;
+  const defaultEmailValue = currentUser?.email ?? defaultValues?.email ?? "";
+
+  const { form, submitName } = useForm({
+    defaultValues: { email: defaultEmailValue, password: "" },
+    validate: { email: validEmail },
+    async onSubmit({ values }) {
+      const result = await client.login(values);
+
+      return result.mapFailure((failure) => {
+        return getSubmitFailureMessage(failure, {
+          401: "🔐 Username and password do not match.",
+          404: "🤔 Couldn't find a user with this email address.",
+        });
+      });
+    },
+    onSuccess() {
+      onLogin({ reload });
+    },
+  });
+
+  const emailValue = useStoreState(form, (state) => state.values.email);
+
+  return (
+    <Letterhead>
+      <LetterheadHeader>
+        <LetterheadHeading>Log in</LetterheadHeading>
+
+        {localUserPresent ? (
+          <>
+            <LetterheadParagraph>
+              Your session has expired. Please log into Indie Tabletop Club
+              again.
+            </LetterheadParagraph>
+
+            <LetterheadParagraph>
+              {"To use a different account, please "}
+              <Button
+                className={interactiveText}
+                onClick={() => onLogout({ reload })}
+              >
+                log out
+              </Button>
+              {" first."}
+            </LetterheadParagraph>
+          </>
+        ) : (
+          <LetterheadParagraph>
+            {description}
+            {" Do not have an account? "}
+            <Link
+              href={hrefs.join()}
+              className={interactiveText}
+              state={{ emailValue }}
+            >
+              Join now
+            </Link>
+            {"."}
+          </LetterheadParagraph>
+        )}
+      </LetterheadHeader>
+
+      <Form store={form} resetOnSubmit={false}>
+        <InputsStack>
+          <LetterheadTextField
+            name={form.names.email}
+            placeholder={placeholders.email}
+            label="Email"
+            type="email"
+            readOnly={localUserPresent}
+            required
+          />
+          <LetterheadTextField
+            name={form.names.password}
+            label="Password"
+            placeholder="Your password"
+            type="password"
+            required
+          />
+        </InputsStack>
+
+        <LetterheadFormActions>
+          <LetterheadSubmitError name={submitName} />
+          <LetterheadSubmitButton>Log in</LetterheadSubmitButton>
+
+          <LetterheadParagraph align="start">
+            Forgot password?{" "}
+            <Link
+              href="/password"
+              className={interactiveText}
+              state={{ emailValue }}
+            >
+              Reset it
+            </Link>
+            {"."}
+          </LetterheadParagraph>
+        </LetterheadFormActions>
+      </Form>
+    </Letterhead>
+  );
+}

package/lib/account/NoConnectionView.tsx

@@ -0,0 +1,34 @@
+import { Button } from "@ariakit/react";
+import { cx } from "../class-names.ts";
+import { interactiveText } from "../common.css.ts";
+import {
+  Letterhead,
+  LetterheadHeading,
+  LetterheadParagraph,
+} from "../Letterhead/index.tsx";
+
+export function NoConnectionView(props: {
+  latestAttemptTs: number;
+  onRetry: () => void;
+}) {
+  const { latestAttemptTs, onRetry } = props;
+
+  return (
+    <Letterhead>
+      <LetterheadHeading>No connection</LetterheadHeading>
+
+      <LetterheadParagraph>
+        {"There seems to be an issue reaching to our servers. "}
+        {"Are you connected to the internet? Last attempt at "}
+        {new Date(latestAttemptTs).toLocaleTimeString()}
+        {"."}
+      </LetterheadParagraph>
+
+      <LetterheadParagraph>
+        <Button {...cx(interactiveText)} onClick={() => onRetry()}>
+          Try again
+        </Button>
+      </LetterheadParagraph>
+    </Letterhead>
+  );
+}