@indietabletop/appkit 3.6.0-2 → 4.0.0-0

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/useEnsureValue.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+import { Failure, Pending, Success, type AsyncOp } from "./async-op.ts";
+import { caughtValueToString } from "./caught-value.ts";
+
+/**
+ * Checks if the provided value is non-nullish, otherwise calls provided
+ * getValue function to obtain the value (presumably from some remote location).
+ */
+export function useEnsureValue<T>(
+  value: T | null | undefined,
+  getValue: () => Promise<Success<T> | Failure<string>>,
+) {
+  const [result, setShareLink] = useState<AsyncOp<T, string>>(
+    value != null ? new Success(value) : new Pending(),
+  );
+
+  useEffect(() => {
+    if (value == null) {
+      getValue().then(
+        (success) => {
+          setShareLink(success);
+        },
+        (error: unknown) => {
+          setShareLink(new Failure(caughtValueToString(error)));
+        },
+      );
+    }
+  }, [value, getValue]);
+
+  return result;
+}

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-2",
+  "version": "4.0.0-0",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",
@@ -9,7 +9,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest",
-    "storybook": "storybook dev -p 6000"
+    "storybook": "storybook dev"
   },
   "exports": {
     ".": "./lib/index.ts",
@@ -26,6 +26,7 @@
   },
   "devDependencies": {
     "@storybook/addon-docs": "^9.1.6",
+    "@storybook/addon-links": "^9.1.7",
     "@storybook/react-vite": "^9.1.6",
     "@types/react": "^19.1.8",
     "msw": "^2.11.2",

package/lib/ClientContext/ClientContext.tsx

@@ -1,25 +0,0 @@
-import { createContext, type ReactNode, useContext } from "react";
-import type { IndieTabletopClient } from "../client.ts";
-
-const ClientContext = createContext<IndieTabletopClient | null>(null);
-
-export function ClientProvider(props: {
-  client: IndieTabletopClient;
-  children: ReactNode;
-}) {
-  const { client, children } = props;
-  return <ClientContext value={client}>{children}</ClientContext>;
-}
-
-export function useClient() {
-  const client = useContext(ClientContext);
-
-  if (!client) {
-    throw new Error(
-      `Attempting to retrieve ITC client, but none was found within context. ` +
-        `Make sure that ClientProvider is used in the component hierarchy.`,
-    );
-  }
-
-  return client;
-}

package/lib/LoginPage/LoginPage.stories.tsx

@@ -1,107 +0,0 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { http, HttpResponse } from "msw";
-import { fn } from "storybook/test";
-import { IndieTabletopClient } from "../client.ts";
-import { sleep } from "../sleep.ts";
-import { LoginPage } from "./LoginPage.tsx";
-
-const userA = {
-  id: "a",
-  email: "a@example.com",
-  isVerified: true,
-};
-
-const userB = {
-  id: "b",
-  email: "b@example.com",
-  isVerified: true,
-};
-
-const meta = {
-  title: "Pages/Login Page",
-  component: LoginPage,
-  tags: ["autodocs"],
-  args: {
-    client: new IndieTabletopClient({ apiOrigin: "" }),
-    onSuccess: fn(),
-    onLogout: fn(),
-    localUser: null,
-  },
-  parameters: {
-    msw: {
-      handlers: {
-        getCurrentUser: http.get("/v1/users/me", async () => {
-          await sleep(2000);
-
-          return HttpResponse.json(userA);
-        }),
-
-        createNewSession: http.post("/v1/sessions", async () => {
-          await sleep(2000);
-
-          return HttpResponse.json({
-            currentUser: userA,
-            sessionInfo: {
-              createdTs: 123,
-              expiresTs: 123,
-            },
-          });
-        }),
-      },
-    },
-  },
-} satisfies Meta<typeof LoginPage>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-// There is no local user and server response reports user not authenticated.
-// This is the majority case.
-export const Default: Story = {
-  parameters: {
-    msw: {
-      handlers: {
-        getCurrentUser: http.get("/v1/users/me", async () => {
-          await sleep(2000);
-
-          return HttpResponse.text("Not authenticated", { status: 401 });
-        }),
-      },
-    },
-  },
-};
-
-// User is logged in via a server cookie. They can proceed to app.
-export const AlreadyLoggedIn: Story = {
-  args: {
-    localUser: userA,
-  },
-};
-
-// App has local data that doesn't match server-data. User has to choose
-// how to proceed.
-
-// TODO Style UserMismatch and add handler.
-export const UserMismatch: Story = {
-  args: {
-    localUser: userB,
-  },
-};
-
-// TODO: Implement Not Found story (user was probably deleted)
-export const UserNotFound: Story = {
-  args: {
-    localUser: null,
-  },
-};
-
-// TODO: Implement no connection story
-export const NoConnection: Story = {};
-
-// TODO: Implement fallback failure (all other cases)
-export const FallbackFailure: Story = {
-  args: {
-    localUser: userB,
-  },
-};

package/lib/LoginPage/LoginPage.tsx

@@ -1,204 +0,0 @@
-import { Form } from "@ariakit/react";
-import { Button } from "@ariakit/react/button";
-
-import { useCallback, useEffect, useState } from "react";
-import { Link, useLocation } from "wouter";
-import { Pending, type Failure, type Success } from "../async-op.js";
-import { IndieTabletopClient } from "../client.ts";
-import { interactiveText } from "../common.css.ts";
-import { getSubmitFailureMessage } from "../failureMessages.ts";
-import { LoadingPage } from "../InfoPage/index.tsx";
-import {
-  Letterhead,
-  LetterheadHeading,
-  LetterheadParagraph,
-  LetterheadSubmitButton,
-} from "../Letterhead/index.tsx";
-import {
-  LetterheadSubmitError,
-  LetterheadTextField,
-} from "../LetterheadForm/index.tsx";
-import { Title } from "../Title/index.tsx";
-import type { CurrentUser, FailurePayload } from "../types.ts";
-import { useForm } from "../use-form.ts";
-import { validEmail } from "../validations.ts";
-import * as css from "./style.css.ts";
-
-type EventHandler = () => Promise<void> | void;
-
-function LoginForm(props: {
-  client: IndieTabletopClient;
-  onSuccess: EventHandler;
-}) {
-  const { client, onSuccess } = props;
-
-  const [_, navigate] = useLocation();
-  const { form, submitName } = useForm({
-    defaultValues: { email: "", 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. Please try again.",
-          404: "Could not find a user with this email.",
-        });
-      });
-    },
-
-    async onSuccess() {
-      await onSuccess();
-      navigate("~/");
-    },
-  });
-
-  return (
-    <Form store={form} resetOnSubmit={false}>
-      <div
-        style={{
-          display: "flex",
-          flexDirection: "column",
-          gap: "1.125rem",
-        }}
-      >
-        <LetterheadTextField
-          name={form.names.email}
-          placeholder="james.workshop@example.com"
-          label="Email"
-          type="email"
-          required
-        />
-        <LetterheadTextField
-          name={form.names.password}
-          label="Password"
-          placeholder="Your password"
-          type="password"
-          required
-        />
-      </div>
-      <div
-        style={{
-          marginBlockStart: "2rem",
-          display: "flex",
-          flexDirection: "column",
-          gap: "1.125rem",
-        }}
-      >
-        <LetterheadSubmitError name={submitName} />
-        <LetterheadSubmitButton>Log in</LetterheadSubmitButton>
-      </div>
-    </Form>
-  );
-}
-
-function useCurrentUserResult(client: IndieTabletopClient) {
-  const getCurrentUser = useCallback(() => client.getCurrentUser(), [client]);
-  const [result, setResult] = useState<
-    Success<CurrentUser> | Failure<FailurePayload> | Pending
-  >(new Pending());
-
-  useEffect(() => {
-    getCurrentUser().then((result) => setResult(result));
-  }, [getCurrentUser]);
-
-  return result;
-}
-
-export function LoginPage(props: {
-  client: IndieTabletopClient;
-  localUser: CurrentUser | null;
-  onSuccess: EventHandler;
-  onLogout: EventHandler;
-}) {
-  const { client, localUser, onLogout } = props;
-  const currentUserResult = useCurrentUserResult(client);
-
-  return (
-    <div className={css.page}>
-      <Title>Login</Title>
-
-      {currentUserResult.unpack(
-        (serverUser) => {
-          if (localUser && localUser.id !== serverUser.id) {
-            return (
-              <Letterhead>
-                <header className={css.header}>
-                  <LetterheadHeading>User mismatch</LetterheadHeading>
-
-                  <LetterheadParagraph>
-                    You are logged into Indie Tabletop Club as{" "}
-                    {serverUser.email}, but the account currently logged in on
-                    this device is {localUser.email}.
-                  </LetterheadParagraph>
-
-                  <LetterheadParagraph>
-                    Please pick which user account to continue with to prevent
-                    syncing issues.
-                  </LetterheadParagraph>
-
-                  <div>
-                    <Button type="button">
-                      <div>Continue as {serverUser.email}</div>
-                      <div>Local data will be deleted.</div>
-                    </Button>
-
-                    <Button type="button">
-                      <div>Continue as {localUser.email}</div>
-                      <div>You will be asked for your credentials again.</div>
-                    </Button>
-                  </div>
-                </header>
-              </Letterhead>
-            );
-          }
-
-          return (
-            <Letterhead>
-              <header className={css.header}>
-                <LetterheadHeading>Logged in</LetterheadHeading>
-                <LetterheadParagraph>
-                  You are already logged into Indie Tabletop Club as{" "}
-                  {serverUser.email}.
-                </LetterheadParagraph>
-
-                <LetterheadParagraph>
-                  <Link className={interactiveText} href="~/">
-                    Continue
-                  </Link>
-                  {` as current user, or `}
-                  <Button className={interactiveText} onClick={onLogout}>
-                    log out
-                  </Button>
-                  .
-                </LetterheadParagraph>
-              </header>
-            </Letterhead>
-          );
-        },
-        (failure) => {
-          if (failure.type === "API_ERROR" && failure.code === 401) {
-            return (
-              <Letterhead>
-                <header className={css.header}>
-                  <LetterheadHeading>Log in</LetterheadHeading>
-                  <LetterheadParagraph>
-                    Log into your Indie Tabletop Club account to access creator
-                    features.
-                  </LetterheadParagraph>
-                </header>
-
-                <LoginForm {...props} />
-              </Letterhead>
-            );
-          }
-
-          return null;
-        },
-        () => (
-          <LoadingPage />
-        ),
-      )}
-    </div>
-  );
-}

package/lib/LoginPage/style.css.ts

@@ -1,17 +0,0 @@
-import { MinWidth } from "@indietabletop/appkit";
-import { style } from "@vanilla-extract/css";
-
-export const page = style({
-  backgroundColor: "white",
-
-  "@media": {
-    [MinWidth.SMALL]: {
-      backgroundColor: "transparent",
-      padding: "clamp(1rem, 5vw, 5rem)",
-    },
-  },
-});
-
-export const header = style({
-  marginBlockEnd: "3rem",
-});

package/lib/Title/index.tsx

@@ -1,4 +0,0 @@
-export function Title(props: { children: string }) {
-  // TODO: Pick out an app name from context
-  return <title>{`${props.children} | Indie Tabletop Club`}</title>;
-}