@indietabletop/appkit 3.6.0-3 → 4.0.0-1

package/lib/AppConfig/AppConfig.tsx

@@ -1,17 +1,12 @@
 import { createContext, type ReactNode, useContext } from "react";
 import type { IndieTabletopClient } from "../client.ts";
+import type { AppHrefs } from "../hrefs.ts";
 
 export type AppConfig = {
   appName: string;
+  isDev: boolean;
   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,10 @@
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
+
+export function DocumentTitle(props: { children: string }) {
+  const { children: children } = props;
+  const { appName, isDev } = useAppConfig();
+  const itc = `${appName} · Indie Tabletop Club`;
+  const title = children ? `${children} | ${itc}` : itc;
+
+  return <title>{isDev ? `[DEV] ${title}` : title}</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,
@@ -105,6 +119,8 @@ export function CurrentUserFetcher(props: {
             <VerifyAccountView
               currentUser={serverUser}
               onClose={() => setOpen(false)}
+              onLogout={onLogout}
+              reload={reload}
             />
           </ModalDialog>
 

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/account/VerifyPage.tsx

@@ -2,6 +2,7 @@ import { Button, Form } from "@ariakit/react";
 import { useState, type Dispatch, type SetStateAction } from "react";
 import { Link } from "wouter";
 import { useAppConfig, useClient } from "../AppConfig/AppConfig.tsx";
+import { interactiveText } from "../common.css.ts";
 import { getSubmitFailureMessage } from "../failureMessages.ts";
 import {
   Letterhead,
@@ -18,13 +19,20 @@ import {
 } from "../LetterheadForm/index.tsx";
 import type { CurrentUser } from "../types.ts";
 import { useForm } from "../use-form.ts";
-import type { EventHandler } from "./types.ts";
+import type { EventHandler, EventHandlerWithReload } from "./types.ts";
 
-type SetStep = Dispatch<SetStateAction<Steps>>;
+type SetStep = Dispatch<SetStateAction<VerifyStep>>;
+
+function InitialStep(props: {
+  setStep: SetStep;
+  currentUser: CurrentUser;
+  onLogout: EventHandlerWithReload;
+  reload: () => void;
+}) {
+  const { setStep, onLogout, currentUser, reload } = props;
+  const { email } = currentUser;
 
-function InitialStep(props: { setStep: SetStep; currentUser: CurrentUser }) {
   const client = useClient();
-  const { email } = props.currentUser;
   const { form, submitName } = useForm({
     defaultValues: {},
     async onSubmit() {
@@ -32,7 +40,7 @@ function InitialStep(props: { setStep: SetStep; currentUser: CurrentUser }) {
       return op.mapFailure(getSubmitFailureMessage);
     },
     onSuccess(value) {
-      props.setStep({ type: "SUBMIT_CODE", tokenId: value.tokenId });
+      setStep({ type: "SUBMIT_CODE", tokenId: value.tokenId });
     },
   });
 
@@ -50,6 +58,16 @@ function InitialStep(props: { setStep: SetStep; currentUser: CurrentUser }) {
         <LetterheadFormActions>
           <LetterheadSubmitError name={submitName} />
           <LetterheadSubmitButton>Send code</LetterheadSubmitButton>
+          <LetterheadParagraph>
+            Cannot complete verification?{" "}
+            <Button
+              className={interactiveText}
+              onClick={() => void onLogout({ reload })}
+            >
+              Log out
+            </Button>
+            .
+          </LetterheadParagraph>
         </LetterheadFormActions>
       </Letterhead>
     </Form>
@@ -138,13 +156,15 @@ function SuccessStep(props: { onClose?: EventHandler }) {
   );
 }
 
-type Steps =
+type VerifyStep =
   | { type: "INITIAL" }
   | { type: "SUBMIT_CODE"; tokenId: string }
   | { type: "SUCCESS" };
 
 export function VerifyAccountView(props: {
   currentUser: CurrentUser;
+  onLogout: EventHandlerWithReload;
+  reload: () => void;
 
   /**
    * If provided, will cause the success step to render a close dialog button
@@ -154,18 +174,15 @@ export function VerifyAccountView(props: {
    */
   onClose?: EventHandler;
 }) {
-  const { currentUser } = props;
-  const [step, setStep] = useState<Steps>({ type: "INITIAL" });
+  const [step, setStep] = useState<VerifyStep>({ type: "INITIAL" });
 
   switch (step.type) {
     case "INITIAL": {
-      return <InitialStep setStep={setStep} currentUser={currentUser} />;
+      return <InitialStep {...props} setStep={setStep} />;
     }
 
     case "SUBMIT_CODE": {
-      return (
-        <SubmitCodeStep {...step} setStep={setStep} currentUser={currentUser} />
-      );
+      return <SubmitCodeStep {...props} {...step} setStep={setStep} />;
     }
 
     case "SUCCESS": {
@@ -173,45 +190,3 @@ export function VerifyAccountView(props: {
     }
   }
 }
-
-// TODO: Decide if to remove this?
-function AlreadyVerifiedView() {
-  const { hrefs } = useAppConfig();
-
-  return (
-    <Letterhead>
-      <LetterheadHeader>
-        <LetterheadHeading>Already Verified</LetterheadHeading>
-        <LetterheadParagraph>
-          Your user account has already been verified. You're all good!
-        </LetterheadParagraph>
-      </LetterheadHeader>
-
-      <Link href={hrefs.dashboard()} className={button()}>
-        Back to dashboard
-      </Link>
-    </Letterhead>
-  );
-}
-
-// TODO: Decide if to remove this?
-export function VerifyCard(props: { currentUser: CurrentUser | null }) {
-  const { currentUser } = props;
-
-  if (!currentUser) {
-    return (
-      <Letterhead>
-        <LetterheadHeading>Cannot verify</LetterheadHeading>
-        <LetterheadParagraph>
-          You must be logged in to verify your account.
-        </LetterheadParagraph>
-      </Letterhead>
-    );
-  }
-
-  if (currentUser.isVerified) {
-    return <AlreadyVerifiedView />;
-  }
-
-  return <VerifyAccountView currentUser={currentUser} />;
-}

package/lib/account/useCurrentUserResult.tsx

@@ -23,7 +23,22 @@ export function useCurrentUserResult(options?: {
   // with caching or any of that business.
   useEffect(() => {
     if (performFetch) {
-      client.getCurrentUser().then((result) => setResult(result));
+      const fetchUserAndStoreResult = async () => {
+        setResult(new Pending());
+
+        const result = await client.getCurrentUser();
+        setResult(result);
+      };
+
+      // Invoke the fetch action
+      fetchUserAndStoreResult();
+
+      // Set up listeners for data revalidation
+      window.addEventListener("focus", fetchUserAndStoreResult);
+
+      return () => {
+        window.removeEventListener("focus", fetchUserAndStoreResult);
+      };
     }
   }, [client, latestAttemptTs, performFetch]);
 

package/lib/copyrightRange.ts

@@ -1,6 +1,10 @@
 export function copyrightRange(yearSince: number) {
   const currentYear = new Date().getFullYear();
-  return currentYear === yearSince
-    ? `© ${yearSince}`
-    : `© ${yearSince}–${currentYear}`;
+
+  // Handle edge-case in which yearSince is greater than currentYear.
+  const clampedYearSince = Math.min(yearSince, currentYear);
+
+  return currentYear === clampedYearSince
+    ? `© ${clampedYearSince}`
+    : `© ${clampedYearSince}–${currentYear}`;
 }

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.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,40 @@
 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>;
+
+/**
+ * Make properties in union K required in T.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   id: string;
+ *   name?: string;
+ *   email?: string;
+ * }
+ *
+ * type UserWithRequiredName = RequiredPick<User, 'name'>;
+ * // Result: { id: string; name: string; email?: string; }
+ * ```
+ */
+export type RequiredPick<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
+/**
+ * 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,92 @@
+/**
+ * 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 && omitUndefinedKeys(params)),
+    });
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "3.6.0-3",
+  "version": "4.0.0-1",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",
@@ -25,17 +25,17 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^9.1.6",
-    "@storybook/addon-links": "^9.1.7",
-    "@storybook/react-vite": "^9.1.6",
+    "@storybook/addon-docs": "^9.1.10",
+    "@storybook/addon-links": "^9.1.10",
+    "@storybook/react-vite": "^9.1.10",
     "@types/react": "^19.1.8",
     "msw": "^2.11.2",
     "msw-storybook-addon": "^2.0.5",
     "np": "^10.1.0",
-    "storybook": "^9.1.6",
+    "storybook": "^9.1.10",
     "typescript": "^5.8.2",
     "vite": "^6.3.5",
-    "vitest": "^3.0.5"
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "@ariakit/react": "^0.4.17",

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>
-  );
-}

package/lib/append-copy-to-text.test.ts

@@ -1,29 +0,0 @@
-import { describe, expect, test } from "vitest";
-import {
-  appendCopyToText,
-  maybeAppendCopyToText,
-} from "./append-copy-to-text.ts";
-
-describe("appendCopyToText", () => {
-  test("Appends ' (Copy)' to provided string", () => {
-    const returnValue = appendCopyToText("Zangrad Raiders");
-    expect(returnValue).toBe("Zangrad Raiders (Copy)");
-  });
-
-  test("Adds a copy count number if string already ends in ' (Copy)'", () => {
-    const returnValue = appendCopyToText("Zangrad Raiders (Copy)");
-    expect(returnValue).toBe("Zangrad Raiders (Copy 2)");
-  });
-
-  test("Increments a copy count number if one already exists", () => {
-    const returnValue = appendCopyToText("Zangrad Raiders (Copy 2)");
-    expect(returnValue).toBe("Zangrad Raiders (Copy 3)");
-  });
-});
-
-describe("maybeAppendCopyToText", () => {
-  test("Ignores empty strings", () => {
-    const returnValue = maybeAppendCopyToText("");
-    expect(returnValue).toBe("");
-  });
-});

package/lib/failureMessages.test.ts

@@ -1,169 +0,0 @@
-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(`
-      {
-        "action": {
-          "href": "~/",
-          "label": "Go back",
-          "type": "LINK",
-        },
-        "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(`
-      {
-        "action": {
-          "label": "Reload app",
-          "type": "RELOAD",
-        },
-        "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(`
-      {
-        "action": {
-          "href": "~/",
-          "label": "Go back",
-          "type": "LINK",
-        },
-        "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(`
-      {
-        "action": {
-          "href": "~/",
-          "label": "Go back",
-          "type": "LINK",
-        },
-        "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(`
-      {
-        "action": {
-          "label": "Retry request",
-          "type": "REFETCH",
-        },
-        "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(`
-      {
-        "action": {
-          "label": "Reload app",
-          "type": "RELOAD",
-        },
-        "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(`
-      {
-        "action": {
-          "label": "Reload app",
-          "type": "RELOAD",
-        },
-        "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/unique.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { uniqueBy } from "./unique.ts";
-
-describe("unique", () => {
-  test("Returns unique items based on getKey", () => {
-    const result = uniqueBy(
-      [{ id: "zxcvbn" }, { id: "qwerty" }, { id: "zxcvbn" }],
-      (item) => item.id,
-    );
-
-    expect(result).toMatchInlineSnapshot(`
-      [
-        {
-          "id": "zxcvbn",
-        },
-        {
-          "id": "qwerty",
-        },
-      ]
-    `);
-  });
-});