@indietabletop/appkit 3.2.0-0 → 3.2.0-10

package/lib/client.ts

@@ -0,0 +1,288 @@
+import { type Infer, mask, object, string, Struct } from "superstruct";
+import { Failure, Success } from "./async-op.js";
+import { currentUser, sessionInfo } from "./structs.js";
+import type { CurrentUser, FailurePayload, SessionInfo } from "./types.js";
+
+export class IndieTabletopClient {
+  origin: string;
+  private onCurrentUser?: (currentUser: CurrentUser) => void;
+  private onSessionInfo?: (sessionInfo: SessionInfo) => void;
+  private onSessionExpired?: () => void;
+  private refreshTokenPromise?: Promise<
+    Success<{ sessionInfo: SessionInfo }> | Failure<FailurePayload>
+  >;
+
+  constructor(props: {
+    apiOrigin: string;
+
+    /**
+     * Runs every time the current user is fetched from the API. Typically, this
+     * happens during login, signup, and when the current user is fetched.
+     */
+    onCurrentUser?: (currentUser: CurrentUser) => void;
+
+    /**
+     * Runs ever time new session info is fetched from the API. Typically, this
+     * happends during login, signup, and when tokens are refreshed.
+     */
+    onSessionInfo?: (sessionInfo: SessionInfo) => void;
+
+    /**
+     * Runs when token refresh is attempted, but fails due to 401 error.
+     */
+    onSessionExpired?: () => void;
+  }) {
+    this.origin = props.apiOrigin;
+    this.onCurrentUser = props.onCurrentUser;
+    this.onSessionInfo = props.onSessionInfo;
+    this.onSessionExpired = props.onSessionExpired;
+  }
+
+  protected async fetch<T, S>(
+    path: string,
+    struct: Struct<T, S>,
+    init?: RequestInit & { json?: object },
+  ): Promise<Success<Infer<Struct<T, S>>> | Failure<FailurePayload>> {
+    // If json was provided, we stringify it. Otherwise we use body.
+    const body = init?.json ? JSON.stringify(init.json) : init?.body;
+
+    // If json was provided, we make sure that content type is correctly set.
+    const headers = init?.json
+      ? { ...init?.headers, "Content-Type": "application/json" }
+      : init?.headers;
+
+    try {
+      const res = await fetch(`${this.origin}${path}`, {
+        // Defaults
+        credentials: "include",
+
+        // Overrides
+        ...init,
+        body,
+        headers,
+      });
+
+      if (!res.ok) {
+        console.error(res);
+        return new Failure({ type: "API_ERROR", code: res.status });
+      }
+
+      try {
+        const data = mask(await res.json(), struct);
+        return new Success(data);
+      } catch (error) {
+        console.error(error);
+
+        return new Failure({ type: "VALIDATION_ERROR" });
+      }
+    } catch (error) {
+      console.error(error);
+
+      if (error instanceof Error) {
+        return new Failure({ type: "NETWORK_ERROR" });
+      }
+
+      return new Failure({ type: "UNKNOWN_ERROR" });
+    }
+  }
+
+  /**
+   * Fetches data and retries 401 failures after attempting to refresh tokens.
+   */
+  protected async fetchWithAuth<T, S>(
+    path: string,
+    struct: Struct<T, S>,
+    init?: RequestInit & { json?: object },
+  ): Promise<Success<Infer<Struct<T, S>>> | Failure<FailurePayload>> {
+    const op = await this.fetch(path, struct, init);
+
+    if (op.isSuccess) {
+      return op;
+    }
+
+    if (op.failure.type === "API_ERROR" && op.failure.code === 401) {
+      console.info("API request failed with error 401. Refreshing tokens.");
+
+      const refreshOp = await this.refreshTokens();
+
+      if (refreshOp.isSuccess) {
+        console.info("Tokens refreshed. Retrying request.");
+        return await this.fetch(path, struct, init);
+      } else {
+        console.info("Could not refresh tokens.");
+      }
+    }
+
+    return op;
+  }
+
+  async login(payload: { email: string; password: string }) {
+    const result = await this.fetch(
+      "/v1/sessions",
+      object({
+        currentUser: currentUser(),
+        sessionInfo: sessionInfo(),
+      }),
+      {
+        method: "POST",
+        json: { email: payload.email, plaintextPassword: payload.password },
+      },
+    );
+
+    if (result.isSuccess) {
+      this.onCurrentUser?.(result.value.currentUser);
+      this.onSessionInfo?.(result.value.sessionInfo);
+    }
+
+    return result;
+  }
+
+  async logout() {
+    return await this.fetch("/v1/sessions", object({ message: string() }), {
+      method: "DELETE",
+    });
+  }
+
+  async join(payload: {
+    email: string;
+    password: string;
+    acceptedTos: boolean;
+    subscribedToNewsletter: boolean;
+  }) {
+    const res = await this.fetch(
+      "/v1/users",
+      object({
+        currentUser: currentUser(),
+        sessionInfo: sessionInfo(),
+        tokenId: string(),
+      }),
+      {
+        method: "POST",
+        json: {
+          email: payload.email,
+          plaintextPassword: payload.password,
+          acceptedTos: payload.acceptedTos,
+          subscribedToNewsletter: payload.subscribedToNewsletter,
+        },
+      },
+    );
+
+    if (res.isSuccess) {
+      this.onCurrentUser?.(res.value.currentUser);
+      this.onSessionInfo?.(res.value.sessionInfo);
+    }
+
+    return res;
+  }
+
+  /**
+   * Triggers token refresh process.
+   *
+   * Note that we do not want to perform multiple concurrent token refresh
+   * actions, as that will result in unnecessary 401s. For this reason, a
+   * reference to t
+   */
+  async refreshTokens() {
+    // If there is an ongoing token refresh in progress return that. This should
+    // only deal the response payload, none of the side-effects and cleanup,
+    // which will be handled by the initial invocation.
+    const ongoingRequest = this.refreshTokenPromise;
+
+    if (ongoingRequest) {
+      console.info("Token refresh ongoing. Reusing existing promise.");
+      return await ongoingRequest;
+    }
+
+    // Cache the promise on an instance property to share a reference from
+    // other potential invocations.
+    this.refreshTokenPromise = this.fetch(
+      "/v1/sessions/access-tokens",
+      object({ sessionInfo: sessionInfo() }),
+      { method: "POST" },
+    );
+
+    const result = await this.refreshTokenPromise;
+
+    if (result.isSuccess) {
+      this.onSessionInfo?.(result.value.sessionInfo);
+    }
+
+    if (
+      result.isFailure &&
+      result.failure.type === "API_ERROR" &&
+      result.failure.code === 401
+    ) {
+      this.onSessionExpired?.();
+    }
+
+    // Make sure to reset the shared reference so that subsequent invocations
+    // once again initiate token refresh.
+    delete this.refreshTokenPromise;
+
+    return result;
+  }
+
+  async requestPasswordReset(payload: { email: string }) {
+    return await this.fetch(
+      `/v1/password-reset-tokens`,
+      object({ message: string(), tokenId: string() }),
+      { method: "POST", json: payload },
+    );
+  }
+
+  async checkPasswordResetCode(payload: { tokenId: string; code: string }) {
+    const queryParams = new URLSearchParams({ plaintextCode: payload.code });
+    return await this.fetch(
+      `/v1/password-reset-tokens/${payload.tokenId}?${queryParams}`,
+      object({ message: string() }),
+      { method: "GET" },
+    );
+  }
+
+  async setNewPassword(payload: {
+    tokenId: string;
+    code: string;
+    password: string;
+  }) {
+    const queryParams = new URLSearchParams({ plaintextCode: payload.code });
+    return await this.fetch(
+      `/v1/password-reset-tokens/${payload.tokenId}?${queryParams}`,
+      object({ message: string() }),
+      { method: "PUT", json: { plaintextPassword: payload.password } },
+    );
+  }
+
+  async requestUserVerification() {
+    return await this.fetch(
+      `/v1/user-verification-tokens`,
+      object({ message: string(), tokenId: string() }),
+      { method: "POST" },
+    );
+  }
+
+  async verifyUser(payload: { tokenId: string; code: string }) {
+    const queryParams = new URLSearchParams({ plaintextCode: payload.code });
+    const req = await this.fetch(
+      `/v1/user-verification-tokens/${payload.tokenId}?${queryParams}`,
+      object({ message: string() }),
+      { method: "PUT" },
+    );
+
+    if (req.isSuccess) {
+      await this.refreshTokens();
+      await this.getCurrentUser();
+    }
+
+    return req;
+  }
+
+  async getCurrentUser() {
+    const result = await this.fetchWithAuth(`/v1/users/me`, currentUser());
+
+    if (result.isSuccess) {
+      this.onCurrentUser?.(result.value);
+    }
+
+    return result;
+  }
+}

package/lib/common.css.ts

@@ -0,0 +1,48 @@
+import { style } from "@vanilla-extract/css";
+import { Hover, MinWidth } from "./media.ts";
+
+export const itcSymbol = style({
+  inlineSize: "2.5rem",
+  blockSize: "2.5rem",
+  margin: "0rem auto 0.75rem",
+
+  "@media": {
+    [MinWidth.MEDIUM]: {
+      marginBlock: "-1rem 1.5rem",
+    },
+  },
+});
+
+export const manofa = style({
+  fontFamily: `"manofa", sans-serif`,
+  fontFeatureSettings: `"ss01"`,
+  letterSpacing: "-.01em",
+});
+
+export const minion = style({
+  fontFamily: `"minion-pro", serif`,
+});
+
+export const itcCard = style([
+  minion,
+  {
+    backgroundColor: "white",
+  },
+]);
+
+export const interactiveText = style({
+  display: "inline",
+  textDecoration: "underline",
+  textDecorationColor: "hsl(from currentcolor h s l / 0.3)",
+  textUnderlineOffset: "0.15em",
+
+  "@media": {
+    [Hover.HOVER]: {
+      transition: "text-decoration-color 200ms",
+
+      ":hover": {
+        textDecorationColor: "hsl(from currentcolor h s l / 1)",
+      },
+    },
+  },
+});

package/lib/failureMessages.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "vitest";
+import {
+  getFetchFailureMessages,
+  getSubmitFailureMessage,
+} from "./failureMessages.ts";
+
+describe("getFetchFailureMessages", () => {
+  test("Returns correct message for API_ERROR with code 404", () => {
+    const result = getFetchFailureMessages({ type: "API_ERROR", code: 404 });
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "The link you have followed might be broken.",
+        "title": "Not found",
+      }
+    `);
+  });
+
+  test("Returns correct message for API_ERROR with code 500", () => {
+    const result = getFetchFailureMessages({ type: "API_ERROR", code: 500 });
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "This is probably an issue with our servers. You can try refreshing.",
+        "title": "Ooops, something went wrong",
+      }
+    `);
+  });
+
+  test("Returns correct message for API_ERROR with partial override", () => {
+    const result = getFetchFailureMessages(
+      { type: "API_ERROR", code: 404 },
+      { 404: { title: `Army not found` } },
+    );
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "The link you have followed might be broken.",
+        "title": "Army not found",
+      }
+    `);
+  });
+
+  test("Returns correct message for API_ERROR with override", () => {
+    const result = getFetchFailureMessages(
+      { type: "API_ERROR", code: 404 },
+      {
+        404: {
+          title: `Army not found`,
+          description: `It might have been deleted.`,
+        },
+      },
+    );
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "It might have been deleted.",
+        "title": "Army not found",
+      }
+    `);
+  });
+
+  test("Returns correct message for NETWORK_ERROR", () => {
+    const result = getFetchFailureMessages({ type: "NETWORK_ERROR" });
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "Check your interent connection and try again.",
+        "title": "No connection",
+      }
+    `);
+  });
+
+  test("Returns correct message for UNKNOWN_ERROR", () => {
+    const result = getFetchFailureMessages({ type: "UNKNOWN_ERROR" });
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "This is probably an issue on our side. You can try refreshing.",
+        "title": "Ooops, something went wrong",
+      }
+    `);
+  });
+
+  test("Returns correct message for an unrecognised error type", () => {
+    const result = getFetchFailureMessages({ type: "FOO" as any });
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "description": "This is probably an issue on our side. You can try refreshing.",
+        "title": "Ooops, something went wrong",
+      }
+    `);
+  });
+});
+
+describe("getSubmitFailureMessage", () => {
+  test("Returns correct message for API_ERROR with code 500", () => {
+    const message = getSubmitFailureMessage({ type: "API_ERROR", code: 500 });
+    expect(message).toMatchInlineSnapshot(
+      `"Could not submit form due to an unexpected server error. Please refresh the page and try again."`,
+    );
+  });
+
+  test("Returns correct message for API_ERROR with override", () => {
+    const message = getSubmitFailureMessage(
+      { type: "API_ERROR", code: 401 },
+      { 401: `Username and password do not match. Please try again.` },
+    );
+    expect(message).toMatchInlineSnapshot(
+      `"Username and password do not match. Please try again."`,
+    );
+  });
+
+  test("Returns correct message for NETWORK_ERROR", () => {
+    const result = getSubmitFailureMessage({ type: "NETWORK_ERROR" });
+
+    expect(result).toMatchInlineSnapshot(
+      `"Could not submit form due to network error. Make sure you are connected to the internet and try again."`,
+    );
+  });
+
+  test("Returns correct message for UNKNOWN_ERROR", () => {
+    const result = getSubmitFailureMessage({ type: "UNKNOWN_ERROR" });
+
+    expect(result).toMatchInlineSnapshot(
+      `"Could not submit form due to an unexpected error. Please refresh the page and try again."`,
+    );
+  });
+
+  test("Returns correct message for an unrecognised error type", () => {
+    const result = getSubmitFailureMessage({ type: "FOO" as any });
+
+    expect(result).toMatchInlineSnapshot(
+      `"Could not submit form due to an unexpected error. Please refresh the page and try again."`,
+    );
+  });
+});

package/lib/failureMessages.ts

@@ -0,0 +1,76 @@
+import type { FailurePayload } from "./types.ts";
+
+type OnOverride<T> = (fallback: T, override?: Partial<T>) => T;
+
+function createFailureMessageGetter<T>(
+  defaults: Record<number | "fallback" | "connection", T>,
+  options: { onOverride: OnOverride<T> },
+) {
+  return function getMessage(
+    failure: FailurePayload,
+    overrides: Record<number, Partial<T>> = {},
+  ) {
+    switch (failure.type) {
+      case "API_ERROR": {
+        return options.onOverride(
+          defaults[failure.code] ?? defaults.fallback,
+          overrides[failure.code],
+        );
+      }
+
+      case "NETWORK_ERROR": {
+        return defaults.connection;
+      }
+
+      default: {
+        return defaults.fallback;
+      }
+    }
+  };
+}
+
+export const getFetchFailureMessages = createFailureMessageGetter(
+  {
+    404: {
+      title: `Not found`,
+      description: `The link you have followed might be broken.`,
+    },
+    500: {
+      title: `Ooops, something went wrong`,
+      description: `This is probably an issue with our servers. You can try refreshing.`,
+    },
+    connection: {
+      title: `No connection`,
+      description: `Check your interent connection and try again.`,
+    },
+    fallback: {
+      title: `Ooops, something went wrong`,
+      description: `This is probably an issue on our side. You can try refreshing.`,
+    },
+  },
+  {
+    onOverride(fallback, override) {
+      return { ...fallback, ...override };
+    },
+  },
+);
+
+export const getSubmitFailureMessage = createFailureMessageGetter(
+  {
+    500: `Could not submit form due to an unexpected server error. Please refresh the page and try again.`,
+    connection: `Could not submit form due to network error. Make sure you are connected to the internet and try again.`,
+    fallback: `Could not submit form due to an unexpected error. Please refresh the page and try again.`,
+  },
+  {
+    onOverride(fallback, override) {
+      return override ?? fallback;
+    },
+  },
+);
+
+/**
+ * @deprecated Use {@link getSubmitFailureMessage} instead.
+ */
+export function toKnownFailureMessage(failure: FailurePayload) {
+  return getSubmitFailureMessage(failure);
+}

package/lib/globals.css.ts

@@ -0,0 +1,45 @@
+import { globalStyle } from "@vanilla-extract/css";
+
+// Apply global vars
+import "./vars.css.ts";
+
+globalStyle(":root", {
+  fontSynthesis: "none",
+  textRendering: "optimizeLegibility",
+  WebkitFontSmoothing: "antialiased",
+  MozOsxFontSmoothing: "grayscale",
+});
+
+globalStyle("*", {
+  boxSizing: "border-box",
+});
+
+globalStyle("img, picture, svg", {
+  display: "block",
+});
+
+globalStyle("a", {
+  display: "block",
+  color: "inherit",
+  textDecoration: "none",
+});
+
+globalStyle("input, textarea", {
+  fontFamily: "inherit",
+});
+
+globalStyle("button", {
+  display: "block",
+  fontSize: "inherit",
+  fontFamily: "inherit",
+  backgroundColor: "transparent",
+  border: "none",
+  color: "inherit",
+  cursor: "pointer",
+  padding: 0,
+});
+
+globalStyle("body, h1, h2, h3, h4, h5, h6, p, ul, li, ol", {
+  margin: 0,
+  padding: 0,
+});

package/{dist/index.d.ts → lib/index.ts}

@@ -1,10 +1,14 @@
+// Components
 export * from "./ExternalLink.tsx";
 export * from "./FormSubmitButton.tsx";
 export * from "./FullscreenDismissBlocker.tsx";
 export * from "./IndieTabletopClubSymbol.tsx";
-export * from "./LetterheadFooter.tsx";
+export * from "./Letterhead/index.tsx";
+export * from "./LetterheadForm/index.tsx";
 export * from "./LoadingIndicator.tsx";
 export * from "./ServiceWorkerHandler.tsx";
+
+// Hooks
 export * from "./use-async-op.ts";
 export * from "./use-document-background-color.ts";
 export * from "./use-form.ts";
@@ -12,11 +16,15 @@ export * from "./use-is-installed.ts";
 export * from "./use-media-query.ts";
 export * from "./use-reverting-state.ts";
 export * from "./use-scroll-restoration.ts";
+
+// Utils
 export * from "./append-copy-to-text.ts";
 export * from "./async-op.ts";
 export * from "./caught-value.ts";
 export * from "./class-names.ts";
 export * from "./client.ts";
+export * from "./failureMessages.ts";
 export * from "./media.ts";
 export * from "./structs.ts";
 export * from "./types.ts";
+export * from "./validations.ts";

package/lib/internal.css.ts

@@ -0,0 +1,10 @@
+import { createVar, style } from "@vanilla-extract/css";
+import { bounce } from "./animations.css.ts";
+
+export const animationDelay = createVar();
+
+export const dot = style({
+  fill: "currentcolor",
+  opacity: 0.8,
+  animation: `${bounce} 2s ${animationDelay} infinite`,
+});

package/lib/media.ts

@@ -0,0 +1,50 @@
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
+ */
+
+export enum PrefersColorScheme {
+  LIGHT = "(prefers-color-scheme: light)",
+  DARK = "(prefers-color-scheme: dark)",
+}
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
+ */
+
+export enum PrefersReducedMotion {
+  NO_PREFERENCE = "(prefers-reduced-motion: no-preference)",
+  REDUCE = "(prefers-reduced-motion: reduce)",
+}
+
+export enum Hover {
+  NONE = "(hover: none)",
+
+  // Some Samsung phones incorrectly report that they have "hover" even though they
+  // do not. Adding the pointer query correctly filters these phones out.
+  HOVER = "(hover: hover) and (pointer: fine)",
+}
+
+export enum MediaType {
+  PRINT = "print",
+  SCREEN = "screen",
+}
+
+export enum MinHeight {
+  TALL = "(min-height: 40em)",
+}
+
+export enum MinWidth {
+  SMALL = "(min-width: 28em)",
+  MEDIUM = "(min-width: 50em)",
+  WIDE = "(min-width: 66em)",
+  X_WIDE = "(min-width: 80em)",
+  XX_WIDE = "(min-width: 140em)",
+}
+
+export enum DisplayMode {
+  STANDALONE = "(display-mode: standalone)",
+}
+
+export enum Pointer {
+  COARSE = "(pointer: coarse)",
+  FINE = "(pointer: fine)",
+}

package/lib/storybook/decorators.tsx

@@ -0,0 +1,10 @@
+import { FormProvider, type FormProviderProps } from "@ariakit/react";
+import { type Decorator } from "@storybook/react-vite";
+
+export function form(props?: FormProviderProps): Decorator {
+  return (Story) => (
+    <FormProvider {...props}>
+      <Story />
+    </FormProvider>
+  );
+}