@indietabletop/appkit 3.6.0-3 → 4.0.0-0

package/lib/AppConfig/AppConfig.tsx

@@ -1,17 +1,11 @@
 import { createContext, type ReactNode, useContext } from "react";
 import type { IndieTabletopClient } from "../client.ts";
+import type { AppHrefs } from "../hrefs.ts";
 
 export type AppConfig = {
   appName: string;
   client: IndieTabletopClient;
-  hrefs: {
-    login: () => string;
-    password: () => string;
-    join: () => string;
-    terms: () => string;
-    verify: () => string;
-    dashboard: () => string;
-  };
+  hrefs: AppHrefs;
   placeholders: {
     email: string;
   };

package/lib/AuthCard/AuthCard.stories.ts

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { fn } from "storybook/test";
+import { AuthCard } from "./AuthCard.tsx";
+
+const meta = {
+  title: "Account/Auth Card",
+  component: AuthCard,
+  tags: ["autodocs"],
+  args: {
+    onLogout: fn(),
+  },
+} satisfies Meta<typeof AuthCard>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The default case where elements are correctly separated with middots.
+ */
+export const Authenticated: Story = {
+  args: {
+    currentUser: {
+      id: "martin",
+      email: "martin@example.com",
+      isVerified: true,
+    },
+  },
+};
+
+/**
+ * The default case in which all steps of the flow succeed.
+ */
+export const Anonymous: Story = {
+  args: {
+    currentUser: null,
+  },
+};

package/lib/AuthCard/AuthCard.tsx

@@ -0,0 +1,64 @@
+import { Button } from "@ariakit/react";
+import { Link } from "wouter";
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
+import { interactiveText } from "../common.css.ts";
+import { IndieTabletopClubLogo } from "../IndieTabletopClubLogo.tsx";
+import { LetterheadParagraph } from "../Letterhead/index.tsx";
+import { button } from "../Letterhead/style.css.ts";
+import { MiddotSeparated } from "../MiddotSeparated/MiddotSeparated.tsx";
+import type { CurrentUser } from "../types.ts";
+import { card } from "./style.css.ts";
+
+/**
+ * Small, ITC-branded card that shows authentication status.
+ *
+ * Primarily intended to be used within the sidenav.
+ */
+export function AuthCard(props: {
+  onLogout: () => void;
+  currentUser: CurrentUser | null;
+}) {
+  const { currentUser, onLogout } = props;
+  const { hrefs } = useAppConfig();
+  const align = !currentUser ? "center" : "start";
+
+  return (
+    <div className={card.container({ align })}>
+      <IndieTabletopClubLogo className={card.logo({ align })} />
+
+      {currentUser ? (
+        <>
+          <LetterheadParagraph>{currentUser.email}</LetterheadParagraph>
+
+          <MiddotSeparated className={card.loggedInAction}>
+            <Link className={interactiveText} href={hrefs.account()}>
+              Account
+            </Link>
+
+            <Button className={interactiveText} onClick={() => onLogout()}>
+              Log out
+            </Button>
+          </MiddotSeparated>
+        </>
+      ) : (
+        <>
+          <LetterheadParagraph size="small">
+            Enable backup & sync, access your pledge data, and more!
+          </LetterheadParagraph>
+
+          <Link href={hrefs.join()} className={button()}>
+            Join
+          </Link>
+
+          <LetterheadParagraph size="small">
+            {"Already have an account? "}
+            <Link href={hrefs.login()} className={interactiveText}>
+              Log in
+            </Link>
+            {"."}
+          </LetterheadParagraph>
+        </>
+      )}
+    </div>
+  );
+}

package/lib/AuthCard/style.css.ts

@@ -0,0 +1,49 @@
+import { style } from "@vanilla-extract/css";
+import { recipe } from "@vanilla-extract/recipes";
+
+export const card = {
+  container: recipe({
+    base: {
+      display: "flex",
+      flexDirection: "column",
+      gap: "0.75rem",
+      backgroundColor: "white",
+      padding: "1.5rem",
+      borderRadius: "0.5rem",
+      color: "black",
+    },
+
+    variants: {
+      align: {
+        center: {
+          textAlign: "center",
+        },
+        start: {
+          textAlign: "start",
+        },
+      },
+    },
+  }),
+
+  logo: recipe({
+    base: {
+      maxInlineSize: "11rem",
+    },
+
+    variants: {
+      align: {
+        center: {
+          marginInline: "auto",
+        },
+        start: {
+          marginInline: "0",
+        },
+      },
+    },
+  }),
+
+  loggedInAction: style({
+    borderBlockStart: "1px solid hsl(0 0% 0% / 0.1)",
+    paddingBlockStart: "0.75rem",
+  }),
+};

package/lib/DialogTrigger/index.tsx

@@ -15,8 +15,8 @@ function DialogGuard(props: { children: ReactNode }) {
 }
 
 /**
- * Wraps AriaKit's DialogProvider, but take a tuple of Dialog a DialogDisclosure
- * elements as children, and makes sense that the Dialog component is not
+ * Wraps AriaKit's DialogProvider, but takes a tuple of Dialog a DialogDisclosure
+ * elements as children, and makes sure that the Dialog component is not
  * rendered when it is hidden.
  *
  * This is important in cases where the dialog contains a form that should only

package/lib/DocumentTitle/DocumentTitle.tsx

@@ -0,0 +1,9 @@
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
+
+export function DocumentTitle(props: { children: string }) {
+  const { children: title } = props;
+  const { appName } = useAppConfig();
+  const itc = `${appName} · Indie Tabletop Club`;
+
+  return <title>{title ? `${title} | ${itc}` : itc}</title>;
+}

package/lib/LoadingIndicator.tsx

@@ -17,6 +17,7 @@ export function LoadingIndicator(props: { className?: string }) {
       width={width}
       height={height}
       className={props.className}
+      preserveAspectRatio="xMidYMid meet"
     >
       <g stroke="none" fill="inherit">
         {Array.from({ length: 3 }, (_, index) => {

package/lib/MiddotSeparated/MiddotSeparated.stories.ts

@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MiddotSeparated } from "./MiddotSeparated.tsx";
+
+type ComponentType = typeof MiddotSeparated;
+
+type Story = StoryObj<typeof meta>;
+
+const meta = {
+  title: "Components/Middot Separated",
+  component: MiddotSeparated,
+  tags: ["autodocs"],
+} satisfies Meta<ComponentType>;
+
+export default meta;
+
+/**
+ * The default case in which all steps of the flow succeed.
+ */
+export const Default: Story = {
+  args: {
+    children: ["Lorem", "Ipsum", " Dolor"],
+  },
+};
+
+/**
+ * Edge case when it comes to handling children in React.
+ */
+export const SingleElement: Story = {
+  args: {
+    children: "Lorem",
+  },
+};

package/lib/MiddotSeparated/MiddotSeparated.tsx

@@ -0,0 +1,24 @@
+import { type HTMLAttributes, Children } from "react";
+import { withMiddlot } from "./style.css.ts";
+
+type MiddotSeparatedProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * A utility component that wraps children into spans and adds middledots
+ * between each item using CSS ::before pseudo elements.
+ */
+export function MiddotSeparated(props: MiddotSeparatedProps) {
+  const { children, ...divProps } = props;
+
+  return (
+    <div {...divProps}>
+      {Children.toArray(children).map((item, index) => {
+        return (
+          <span className={withMiddlot} key={index}>
+            {item}
+          </span>
+        );
+      })}
+    </div>
+  );
+}

package/lib/MiddotSeparated/style.css.ts

@@ -0,0 +1,10 @@
+import { style } from "@vanilla-extract/css";
+
+export const withMiddlot = style({
+  selectors: {
+    "& + &::before": {
+      content: " · ",
+      opacity: 0.6,
+    },
+  },
+});

package/lib/ModernIDB/bindings/factory.tsx

@@ -114,13 +114,18 @@ export function createDatabaseBindings<T extends AnyModernIDB>(db: T) {
     return useContext(DatabaseOpenRequest);
   }
 
-  function DatabaseProvider(props: { children: ReactNode }) {
+  function DatabaseProvider(props: { children: ReactNode; open?: boolean }) {
+    const { children, open = true } = props;
     const { op, setSuccess, setFailure } = useAsyncOp<
       T,
       InaccessibleDatabaseError
     >();
 
     useEffect(() => {
+      if (!open) {
+        return;
+      }
+
       db.open({
         onBlocking() {
           setFailure({ type: "CLOSED_FOR_UPGRADE" });
@@ -142,11 +147,11 @@ export function createDatabaseBindings<T extends AnyModernIDB>(db: T) {
         db.close();
         console.info("Database closed.");
       };
-    }, [setFailure, setSuccess]);
+    }, [setFailure, setSuccess, open]);
 
     return (
       <DatabaseOpenRequest.Provider value={op}>
-        {props.children}
+        {children}
       </DatabaseOpenRequest.Provider>
     );
   }

package/lib/account/CurrentUserFetcher.stories.tsx

@@ -163,20 +163,6 @@ function createMocks(options?: { responseSpeed?: number }) {
 
 const { data, handlers } = createMocks({ responseSpeed: 700 });
 
-/**
- * Fetches fresh current user data if local data is provided.
- *
- * This component uses the Indie Tabletop Client under the hood, so if new
- * data is successfully fetched, the onCurrentUser callback will be invoked,
- * and it is up to the configuration of the client to store the data.
- *
- * Importantly, this component also handles the various user account issues
- * that we could run into: expired session, user mismatch and account deletion.
- *
- * All other errors are ignored. This allows users to use the app in offline
- * more, and doesn't interrupt their session if some unexpected error happens,
- * which they cannot do anything about anyways.
- */
 const meta = {
   title: "Account/Current User Fetcher",
   component: CurrentUserFetcher,

package/lib/account/CurrentUserFetcher.tsx

@@ -8,7 +8,7 @@ import { useCurrentUserResult } from "./useCurrentUserResult.tsx";
 import { UserMismatchView } from "./UserMismatchView.tsx";
 import { VerifyAccountView } from "./VerifyPage.tsx";
 
-export function CurrentUserFetcher(props: {
+type CurrentUserFetcherProps = {
   /**
    * Current user as stored in persistent storage.
    *
@@ -16,14 +16,28 @@ export function CurrentUserFetcher(props: {
    * from the server and store it (via ITC client).
    */
   localUser: CurrentUser | null;
-
   onLogin: EventHandlerWithReload;
   onClearLocalContent: EventHandler;
   onLogout: EventHandlerWithReload;
   onServerLogout: EventHandlerWithReload;
-
   children: ReactNode;
-}) {
+};
+
+/**
+ * Fetches fresh current user data if local data is provided.
+ *
+ * This component uses the Indie Tabletop Client under the hood, so if new
+ * data is successfully fetched, the onCurrentUser callback will be invoked,
+ * and it is up to the configuration of the client to store the data.
+ *
+ * Importantly, this component also handles the various user account issues
+ * that we could run into: expired session, user mismatch and account deletion.
+ *
+ * All other errors are ignored. This allows users to use the app in offline
+ * more, and doesn't interrupt their session if some unexpected error happens,
+ * which they cannot do anything about anyways.
+ */
+export function CurrentUserFetcher(props: CurrentUserFetcherProps) {
   const {
     localUser,
     children,

package/lib/account/{JoinPage.stories.tsx → JoinCard.stories.tsx}

@@ -4,7 +4,7 @@ import { http, HttpResponse } from "msw";
 import { fn } from "storybook/test";
 import { sleep } from "../sleep.ts";
 import type { CurrentUser, SessionInfo } from "../types.ts";
-import { JoinCard } from "./JoinPage.tsx";
+import { JoinCard } from "./JoinCard.tsx";
 
 function createMocks(options?: { responseSpeed?: number }) {
   const simulateNetwork = () => sleep(options?.responseSpeed ?? 2000);
@@ -136,14 +136,12 @@ function createMocks(options?: { responseSpeed?: number }) {
 
 const { data, handlers } = createMocks({ responseSpeed: 700 });
 
-/**
- * Allows the user to reset their password.
- */
 const meta = {
-  title: "Account/Join Page",
+  title: "Account/Join Card",
   component: JoinCard,
   tags: ["autodocs"],
   args: {
+    defaultValues: {},
     onLogout: fn(),
   },
   parameters: {
@@ -165,11 +163,7 @@ type Story = StoryObj<typeof meta>;
 /**
  * The default case in which all steps of the flow succeed.
  */
-export const Success: Story = {
-  play: async ({ canvas, userEvent }) => {
-    userEvent.type(canvas.getByTestId("email-input"), "foo@bar.com");
-  },
-};
+export const Success: Story = {};
 
 /**
  * In this case, the initial step fails because the email address is associated

package/lib/account/{JoinPage.tsx → JoinCard.tsx}

@@ -87,7 +87,6 @@ function InitialStep(props: {
             type="email"
             placeholder={placeholders.email}
             autoComplete="username"
-            data-testid="email-input"
             required
           />
 
@@ -98,7 +97,6 @@ function InitialStep(props: {
             placeholder="Choose a strong password"
             hint="Must be at least 8 characters"
             autoComplete="new-password"
-            data-testid="new-password-input"
             required
           />
 
@@ -122,7 +120,7 @@ function InitialStep(props: {
                 <a
                   target="_blank"
                   rel="noreferrer noopener"
-                  href={hrefs.terms()}
+                  href={hrefs.terms({ content: "join" })}
                   className={interactiveText}
                 >
                   Terms of Service
@@ -249,10 +247,15 @@ function JoinFlow(props: { defaultValues?: DefaultFormValues }) {
   }
 }
 
-export function JoinCard(props: {
+export type JoinCardProps = {
   onLogout: EventHandlerWithReload;
   defaultValues?: DefaultFormValues;
-}) {
+};
+
+/**
+ * Allows the user to join Indie Tabletop Club.
+ */
+export function JoinCard(props: JoinCardProps) {
   const { result, latestAttemptTs, reload } = useCurrentUserResult();
 
   return result.unpack(

package/lib/account/{LoginPage.stories.tsx → LoginCard.stories.tsx}

@@ -4,7 +4,7 @@ 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";
+import { LoginCard } from "./LoginCard.tsx";
 
 function createMocks(options?: { responseSpeed?: number }) {
   const simulateNetwork = () => sleep(options?.responseSpeed ?? 2000);
@@ -123,16 +123,14 @@ function createMocks(options?: { responseSpeed?: number }) {
 
 const { data, handlers } = createMocks({ responseSpeed: 700 });
 
-/**
- * Allows the user to log into Indie Tabletop Club.
- */
 const meta = {
-  title: "Account/Login Page",
+  title: "Account/Login Card",
   component: LoginCard,
   tags: ["autodocs"],
   args: {
     currentUser: null,
     description: "Log in to Indie Tabletop Club to enable backup & sync.",
+    defaultValues: {},
     onLogin: fn(),
     onLogout: fn(),
     onClearLocalContent: fn(),

package/lib/account/{LoginPage.tsx → LoginCard.tsx}

@@ -14,7 +14,7 @@ import type {
 import { useCurrentUserResult } from "./useCurrentUserResult.tsx";
 import { UserMismatchView } from "./UserMismatchView.tsx";
 
-export type LoginPageProps = {
+export type LoginCardProps = {
   /**
    * Any user data that might currently be stored in persistent storage like
    * `localStorage` or IndexedDB.
@@ -82,7 +82,10 @@ export type LoginPageProps = {
   onServerLogout: EventHandlerWithReload;
 };
 
-export function LoginCard(props: LoginPageProps) {
+/**
+ * Allows the user to log into Indie Tabletop Club.
+ */
+export function LoginCard(props: LoginCardProps) {
   const { currentUser } = props;
   const { result, latestAttemptTs, reload } = useCurrentUserResult();
 

package/lib/account/{PasswordResetPage.stories.tsx → PasswordResetCard.stories.tsx}

@@ -3,7 +3,7 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { http, HttpResponse } from "msw";
 import { sleep } from "../sleep.ts";
 import type { CurrentUser, SessionInfo } from "../types.ts";
-import { PasswordResetCard } from "./PasswordResetPage.tsx";
+import { PasswordResetCard } from "./PasswordResetCard.tsx";
 
 function createMocks(options?: { responseSpeed?: number }) {
   const simulateNetwork = () => sleep(options?.responseSpeed ?? 2000);
@@ -132,9 +132,6 @@ function createMocks(options?: { responseSpeed?: number }) {
 
 const { data, handlers } = createMocks({ responseSpeed: 700 });
 
-/**
- * Allows the user to reset their password.
- */
 const meta = {
   title: "Account/Password Reset Page",
   component: PasswordResetCard,

package/lib/account/{PasswordResetPage.tsx → PasswordResetCard.tsx}

@@ -257,7 +257,7 @@ type ResetPasswordStep =
   | { type: "SET_NEW_PASSWORD"; tokenId: string; code: string; email: string }
   | { type: "SUCCESS" };
 
-export function PasswordResetCard(props: {
+export type PasswordResetCardProps = {
   /**
    * Default values for the initial request password reset step.
    *
@@ -266,7 +266,12 @@ export function PasswordResetCard(props: {
    * is maintained between the two locations.
    */
   defaultValues?: DefaultFormValues;
-}) {
+};
+
+/**
+ * Allows the user to reset their password.
+ */
+export function PasswordResetCard(props: PasswordResetCardProps) {
   const [step, setStep] = useState<ResetPasswordStep>({
     type: "REQUEST_PASSWORD_RESET",
   });

package/lib/globals.css.ts

@@ -50,6 +50,10 @@ globalStyle("body, h1, h2, h3, h4, h5, h6, p, ul, li, ol", {
   padding: 0,
 });
 
+globalStyle("ul, ol", {
+  listStyle: "none",
+});
+
 // Fathom SPA support depends on this image being added to the DOM, but they
 // are sloppy about taking out of the document flow, meaning that on pages
 // that are 100vh, there is a scrollbar flicker as the img element is added

package/lib/hrefs.ts

@@ -0,0 +1,48 @@
+import type { LinkUtmParams, createUtm } from "./utm.ts";
+
+type InputAppHrefs = {
+  login: () => string;
+  password: () => string;
+  join: () => string;
+  dashboard: () => string;
+  account: () => string;
+
+  // These are usually external links to the root domain, so we want to be
+  // able to set some tracking params.
+  terms?: (linkUtm?: LinkUtmParams) => string;
+  privacy?: (linkUtm?: LinkUtmParams) => string;
+  cookies?: (linkUtm?: LinkUtmParams) => string;
+};
+
+export type AppHrefs = Required<InputAppHrefs>;
+
+export function createHrefs<T extends InputAppHrefs>(params: {
+  /**
+   * Hrefs to be used for the given app. At minimum, you need to provide
+   * the core hrefs required by Appkit.
+   */
+  hrefs: T;
+
+  /**
+   * The function responsible for generating UTM tags. You should
+   * use the return value of {@link createUtm} unless you are doing something
+   * unusual.
+   */
+  utm: ReturnType<typeof createUtm>;
+}) {
+  const { utm, hrefs } = params;
+
+  return {
+    terms: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club/terms?${utm(linkUtm)}`,
+    privacy: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club/privacy?${utm(linkUtm)}`,
+    cookies: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club/cookies?${utm(linkUtm)}`,
+    itc: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club?${utm(linkUtm)}`,
+    fathom: () => `https://usefathom.com`,
+
+    ...hrefs,
+  };
+}

package/lib/idToDate.ts

@@ -0,0 +1,8 @@
+/**
+ * Given an doc id like `2025-01-01-some-name`, will return a date matching
+ * the starting portion of the id.
+ */
+export function idToDate(id: string, fallback: () => Date) {
+  const dateString = /^(?<date>\d{4}-\d{2}-\d{2})/.exec(id)?.groups?.date;
+  return dateString ? new Date(dateString) : fallback();
+}

package/lib/index.ts

@@ -1,10 +1,12 @@
 // Components
 export * from "./account/CurrentUserFetcher.tsx";
-export * from "./account/JoinPage.tsx";
-export * from "./account/LoginPage.tsx";
-export * from "./account/PasswordResetPage.tsx";
+export * from "./account/JoinCard.tsx";
+export * from "./account/LoginCard.tsx";
+export * from "./account/PasswordResetCard.tsx";
 export * from "./AppConfig/AppConfig.tsx";
+export * from "./AuthCard/AuthCard.tsx";
 export * from "./DialogTrigger/index.tsx";
+export * from "./DocumentTitle/DocumentTitle.tsx";
 export * from "./ExternalLink.tsx";
 export * from "./FormSubmitButton.tsx";
 export * from "./FullscreenDismissBlocker.tsx";
@@ -13,6 +15,7 @@ export * from "./IndieTabletopClubSymbol.tsx";
 export * from "./Letterhead/index.tsx";
 export * from "./LetterheadForm/index.tsx";
 export * from "./LoadingIndicator.tsx";
+export * from "./MiddotSeparated/MiddotSeparated.tsx";
 export * from "./ModalDialog/index.tsx";
 export * from "./QRCode/QRCode.tsx";
 export * from "./ReleaseInfo/index.tsx";
@@ -43,14 +46,19 @@ export * from "./copyrightRange.ts";
 export * from "./failureMessages.ts";
 export * from "./groupBy.ts";
 export * from "./HistoryState.ts";
+export * from "./hrefs.ts";
 export * from "./ids.ts";
+export * from "./idToDate.ts";
+export * from "./mailto.ts";
 export * from "./media.ts";
 export * from "./random.ts";
+export * from "./result/swr.ts";
 export * from "./sleep.ts";
 export * from "./structs.ts";
 export * from "./typeguards.ts";
 export * from "./types.ts";
 export * from "./unique.ts";
+export * from "./utm.ts";
 export * from "./validations.ts";
 
 // Other

package/lib/mailto.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "vitest";
+import { mailto as emailTemplateToMailto } from "./mailto.ts";
+
+describe("emailTempalteToMailto", () => {
+  test("correctly serializes data", () => {
+    expect(
+      emailTemplateToMailto(null, {
+        body: `Hello world!\n\nI am URL escaped.`,
+        subject: `This is a subject?`,
+        cc: null,
+      }),
+    ).toMatchInlineSnapshot(
+      `"mailto:?body=Hello%20world!%0A%0AI%20am%20URL%20escaped.&subject=This%20is%20a%20subject%3F"`,
+    );
+  });
+
+  test("includes recipient when provided", () => {
+    expect(
+      emailTemplateToMailto("hi@example.com", {
+        body: `Hello world!\n\nI am URL escaped.`,
+        subject: `This is a subject?`,
+        cc: null,
+      }),
+    ).toMatchInlineSnapshot(
+      `"mailto:hi@example.com?body=Hello%20world!%0A%0AI%20am%20URL%20escaped.&subject=This%20is%20a%20subject%3F"`,
+    );
+  });
+
+  test("includes cc when provided", () => {
+    expect(
+      emailTemplateToMailto("hi@example.com", {
+        body: `Hello world!\n\nI am URL escaped.`,
+        subject: `This is a subject?`,
+        cc: "cc@example.com",
+      }),
+    ).toMatchInlineSnapshot(
+      `"mailto:hi@example.com?body=Hello%20world!%0A%0AI%20am%20URL%20escaped.&subject=This%20is%20a%20subject%3F&cc=cc%40example.com"`,
+    );
+  });
+
+  test("includes bcc when provided", () => {
+    expect(
+      emailTemplateToMailto("hi@example.com", {
+        body: `Hello world!\n\nI am URL escaped.`,
+        subject: `This is a subject?`,
+        cc: "cc@example.com",
+        bcc: "bcc@example.com",
+      }),
+    ).toMatchInlineSnapshot(
+      `"mailto:hi@example.com?body=Hello%20world!%0A%0AI%20am%20URL%20escaped.&subject=This%20is%20a%20subject%3F&cc=cc%40example.com&bcc=bcc%40example.com"`,
+    );
+  });
+
+  test("cc and bcc allow array values", () => {
+    expect(
+      emailTemplateToMailto("hi@example.com", {
+        body: `Hello world!\n\nI am URL escaped.`,
+        subject: `This is a subject?`,
+        cc: ["cc@example.com", "cc2@example.com"],
+        bcc: ["bcc@example.com", "bcc2@example.com"],
+      }),
+    ).toMatchInlineSnapshot(
+      `"mailto:hi@example.com?body=Hello%20world!%0A%0AI%20am%20URL%20escaped.&subject=This%20is%20a%20subject%3F&cc=cc%40example.com%2Ccc2%40example.com&bcc=bcc%40example.com%2Cbcc2%40example.com"`,
+    );
+  });
+});

package/lib/mailto.ts

@@ -0,0 +1,40 @@
+/**
+ * Encodes values to be used in mailto protocol.
+ *
+ * Note that we cannot simply use URLSeachParams because they, for example, encode a space
+ * as plus (+), which cannot be used in mailto if we want to have consistent behaviour in
+ * all email clients.
+ */
+function encodeValuesForMailto<T extends object>(object: T) {
+  return Object.entries(object)
+    .filter(([_, v]) => !!v)
+    .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+    .join("&");
+}
+
+function serializeArray(value?: string | string[] | null) {
+  return Array.isArray(value) ? value.join(",") : value;
+}
+
+type MailtoPayload = {
+  body?: string | null;
+  subject?: string | null;
+  cc?: string | string[] | null;
+  bcc?: string | string[] | null;
+};
+
+export function mailto(recipient: string | null, payload?: MailtoPayload) {
+  // If the recipient is falsy the user can choose who to send the email to.
+  const to = recipient ?? "";
+
+  const serialized = payload
+    ? `?${encodeValuesForMailto({
+        body: payload.body,
+        subject: payload.subject,
+        cc: serializeArray(payload.cc),
+        bcc: serializeArray(payload.bcc),
+      })}`
+    : "";
+
+  return `mailto:${to}${serialized}`;
+}

package/lib/types.ts

@@ -1,6 +1,23 @@
 import type { Infer } from "superstruct";
 import { currentUser, redeemedPledge, sessionInfo } from "./structs.js";
 
+// Generic type helpers
+
+type Brand<B> = { __brand: B };
+
+export type Branded<T, B> = T & Brand<B>;
+
+/**
+ * A branded string.
+ *
+ * Use this type to make a HTML string as trusted. This can be either HTML
+ * coming from a source that we know is safe (statically generated markdown
+ * that exists in our codebase) or sanitized user-generated content.
+ */
+export type TrustedHtml = Branded<string, "TrustedHtml">;
+
+// Common ITC types
+
 export type CurrentUser = Infer<ReturnType<typeof currentUser>>;
 
 export type SessionInfo = Infer<ReturnType<typeof sessionInfo>>;

package/lib/utm.ts

@@ -0,0 +1,89 @@
+/**
+ * Given an object with keys that might contain undefined values, returns a new
+ * object only with keys that are not undefined.
+ */
+function omitUndefinedKeys<T>(record: Record<string, T | undefined>) {
+  return Object.fromEntries(
+    Object.entries(record).filter(([_, v]) => v !== undefined),
+  ) as Record<string, T>;
+}
+
+/**
+ * Full UTM configuration object.
+ */
+export type UtmParams = {
+  /**
+   * The website/platform the visitor is coming from.
+   */
+  source: string;
+
+  /**
+   * The type of marketing channel (e.g. cpc, email, affiliate, social,
+   * or similar).
+   */
+  medium: string;
+
+  /**
+   * The name of the campaign or product description. In our case, this is
+   * usually the name of the app.
+   */
+  campaign: string;
+
+  /**
+   * Optionally, provide an identifier for the place from which the link was
+   * clicked. E.g. footer, join, etc.
+   */
+  content?: string;
+
+  /**
+   * Optionally, identify paid keywords. We usually do not use this.
+   */
+  term?: string;
+};
+
+/**
+ * UTM Params configuration that is appropriate to set at the link level,
+ * if app-level defaults have been set.
+ */
+export type LinkUtmParams = Pick<UtmParams, "content" | "term">;
+
+/**
+ * Returns URL Search params with provided UTM configuration.
+ *
+ * Most of the time, you probably want to set up some defaults using
+ * {@link createUtm}. This function is intended for special cases.
+ */
+export function utm(params: UtmParams) {
+  return new URLSearchParams(
+    omitUndefinedKeys({
+      utm_source: params.source,
+      utm_medium: params.medium,
+      utm_campaign: params.campaign,
+      utm_content: params.content,
+      utm_term: params.term,
+    }),
+  );
+}
+
+/**
+ * A factory for the {@link utm} function. Use it to set sensible defaults for
+ * further use of the returned function.
+ *
+ * @example
+ * ```ts
+ * const utm = createUtm({
+ *   source: "indietabletopclub",
+ *   medium: "referral",
+ *   campaign: "spacegitsapp",
+ * });
+ *
+ * utm() // => URLSearchParams that inlude the above config
+ *
+ * utm({ campaign: "foo", content: "bar" }) // Sets optional fiels and overrides
+ * ```
+ */
+export function createUtm(defaults: UtmParams) {
+  return function (params?: Partial<UtmParams>) {
+    return utm({ ...defaults, ...params });
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "3.6.0-3",
+  "version": "4.0.0-0",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",

package/lib/Title/index.tsx

@@ -1,9 +0,0 @@
-import { useAppConfig } from "../AppConfig/AppConfig.tsx";
-
-export function Title(props: { children: string }) {
-  const { appName } = useAppConfig();
-
-  return (
-    <title>{`${props.children} | ${appName} · Indie Tabletop Club`}</title>
-  );
-}