@indietabletop/appkit 3.5.0 → 3.6.0-0

package/lib/SubscribeCard/SubscribeCard.stories.tsx

@@ -0,0 +1,133 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { http, HttpResponse } from "msw";
+import { LetterheadParagraph } from "../Letterhead/index.tsx";
+import { sleep } from "../sleep.ts";
+import { SubscribeCard } from "./SubscribeCard.tsx";
+
+const pledge = {
+  id: "1",
+  email: "test@example.com",
+  contactSubscribed: false,
+};
+
+const subscribeByPledgeId = {
+  success() {
+    return http.post(
+      "http://localhost:8000/v1/newsletters/changelog/subscriptions",
+      async () => {
+        await sleep(2000);
+
+        return HttpResponse.json(
+          { message: "Added to newsletter" },
+          { status: 201 },
+        );
+      },
+    );
+  },
+  noConnection() {
+    return http.post(
+      "http://localhost:8000/v1/newsletters/changelog/subscriptions",
+      async () => {
+        return HttpResponse.error();
+      },
+    );
+  },
+  error() {
+    return http.post(
+      "http://localhost:8000/v1/newsletters/changelog/subscriptions",
+      async () => {
+        await sleep(2000);
+
+        return HttpResponse.text("Application error", { status: 500 });
+      },
+    );
+  },
+};
+
+const meta = {
+  title: "Pages/Subscribe Card",
+  component: SubscribeCard,
+  tags: ["autodocs"],
+  args: {
+    pledge,
+    content: {
+      SUBSCRIBE: {
+        title: "Space Gits on Indie Tabletop Club",
+        description: (
+          <LetterheadParagraph>
+            Space Gits is getting a fancy <strong>gang builder</strong> and{" "}
+            <strong>smart rules</strong> in late 2025 in collaboration with
+            Indie Tabletop Club. Subscribe to ITC&apos;s{" "}
+            <em>at‑most‑one‑a‑month</em> newsletter and be among the first to
+            gain early access. It&apos;s gonna be rad.
+          </LetterheadParagraph>
+        ),
+      },
+      SUBSCRIBE_SUCCESS: {
+        title: "Subscribed!",
+        description: (
+          <LetterheadParagraph>
+            Thank you for being awesome. Once Space Gits is available for early
+            access, you will be among the first to know!
+          </LetterheadParagraph>
+        ),
+      },
+      PREVIOUSLY_SUBSCRIBED: {
+        title: "Space Gits on Indie Tabletop Club",
+        description: (
+          <>
+            <LetterheadParagraph>
+              Space Gits is getting a fancy <strong>gang builder</strong> and{" "}
+              <strong>smart rules</strong> in late 2025 in collaboration with
+              Indie Tabletop Club.
+            </LetterheadParagraph>
+
+            <LetterheadParagraph>
+              Early access will be announced via ITC&apos;s newsletter, which
+              &mdash; according to our records &mdash; you are are already
+              subscribed to! Nothing left to do but await the good news in your
+              inbox!
+            </LetterheadParagraph>
+          </>
+        ),
+      },
+    },
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        subscribeByPledgeId: subscribeByPledgeId.success(),
+      },
+    },
+  },
+} satisfies Meta<typeof SubscribeCard>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const AlreadySubscribed: Story = {
+  args: { pledge: { ...pledge, contactSubscribed: true } },
+};
+
+export const NoConnection: Story = {
+  parameters: {
+    msw: {
+      handlers: {
+        subscribeByPledgeId: subscribeByPledgeId.noConnection(),
+      },
+    },
+  },
+};
+
+export const FallbackFailure: Story = {
+  parameters: {
+    msw: {
+      handlers: {
+        subscribeByPledgeId: subscribeByPledgeId.error(),
+      },
+    },
+  },
+};

package/lib/SubscribeCard/SubscribeCard.tsx

@@ -0,0 +1,107 @@
+import { Form } from "@ariakit/react";
+import {
+  getSubmitFailureMessage,
+  Letterhead,
+  LetterheadHeading,
+  LetterheadParagraph,
+  LetterheadSubmitButton,
+  LetterheadSubmitError,
+  useForm,
+  type RedeemedPledge,
+} from "@indietabletop/appkit";
+import { useState, type ReactNode } from "react";
+import { useClient } from "../ClientContext/ClientContext.tsx";
+import * as css from "./style.css.ts";
+
+type Pledge = Pick<RedeemedPledge, "id" | "email" | "contactSubscribed">;
+
+function SubscribeView(
+  props: ViewContent & {
+    onSuccess: () => void;
+    pledge: Pledge;
+  },
+) {
+  const { pledge, title, description, onSuccess } = props;
+
+  const client = useClient();
+  const { form, submitName } = useForm({
+    defaultValues: {},
+    onSuccess,
+    async onSubmit() {
+      const result = await client.subscribeToNewsletterByPledgeId(pledge.id);
+      return result.mapFailure(getSubmitFailureMessage);
+    },
+  });
+
+  return (
+    <Letterhead textAlign="center">
+      <LetterheadHeading className={css.card.heading}>
+        {title}
+      </LetterheadHeading>
+
+      {description}
+
+      <Form store={form} className={css.card.form}>
+        <LetterheadSubmitError name={submitName} />
+
+        <LetterheadSubmitButton>Subscribe</LetterheadSubmitButton>
+
+        <LetterheadParagraph size="small">
+          Using {pledge.email} from your pledge.
+        </LetterheadParagraph>
+      </Form>
+    </Letterhead>
+  );
+}
+
+function InfoView(props: ViewContent) {
+  return (
+    <Letterhead textAlign="center">
+      <LetterheadHeading className={css.card.heading}>
+        {props.title}
+      </LetterheadHeading>
+
+      {props.description}
+    </Letterhead>
+  );
+}
+
+type SubscribeStep =
+  | "PREVIOUSLY_SUBSCRIBED"
+  | "SUBSCRIBE"
+  | "SUBSCRIBE_SUCCESS";
+
+type ViewContent = {
+  title: ReactNode;
+  description: ReactNode;
+};
+
+export function SubscribeCard(props: {
+  pledge: Pledge;
+  content: Record<SubscribeStep, ViewContent>;
+}) {
+  const { pledge } = props;
+
+  const [step, setStep] = useState<SubscribeStep>(
+    pledge.contactSubscribed ? "PREVIOUSLY_SUBSCRIBED" : "SUBSCRIBE",
+  );
+
+  const content = props.content[step];
+
+  switch (step) {
+    case "SUBSCRIBE": {
+      return (
+        <SubscribeView
+          {...props}
+          {...content}
+          onSuccess={() => void setStep("SUBSCRIBE_SUCCESS")}
+        />
+      );
+    }
+
+    case "PREVIOUSLY_SUBSCRIBED":
+    case "SUBSCRIBE_SUCCESS": {
+      return <InfoView {...content} />;
+    }
+  }
+}

package/lib/SubscribeCard/style.css.ts

@@ -0,0 +1,14 @@
+import { style } from "@vanilla-extract/css";
+
+export const card = {
+  heading: style({
+    maxInlineSize: "20rem",
+    marginInline: "auto",
+  }),
+  form: style({
+    marginBlockStart: "2.5rem",
+    display: "flex",
+    flexDirection: "column",
+    gap: "1rem",
+  }),
+};

package/lib/Title/index.tsx

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

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

@@ -18,7 +18,7 @@ export function appendCopyToText(input: string): string {
   // with the copy suffix, but it doesn't contain count.
   const nextCount = !count ? 2 : parseInt(count, 10) + 1;
 
-  return `${value.trim()} (Copy ${nextCount})`;
+  return `${value?.trim()} (Copy ${nextCount})`;
 }
 
 /**

package/lib/async-op.ts

@@ -240,6 +240,14 @@ export function fold<Ops extends readonly AsyncOp<unknown, unknown>[] | []>(
   return new Pending() as never;
 }
 
+export function isAsyncOp(value: unknown): value is AsyncOp<unknown, unknown> {
+  return (
+    value instanceof Pending ||
+    value instanceof Success ||
+    value instanceof Failure
+  );
+}
+
 export type AsyncOp<SuccessValue, FailureValue> =
   | Pending
   | Success<SuccessValue>

package/lib/client.ts

@@ -1,6 +1,6 @@
-import { type Infer, mask, object, string, Struct } from "superstruct";
+import { type Infer, mask, object, string, Struct, unknown } from "superstruct";
 import { Failure, Success } from "./async-op.js";
-import { currentUser, sessionInfo } from "./structs.js";
+import { currentUser, redeemedPledge, sessionInfo } from "./structs.js";
 import type { CurrentUser, FailurePayload, SessionInfo } from "./types.js";
 
 export class IndieTabletopClient {
@@ -276,6 +276,22 @@ export class IndieTabletopClient {
     return req;
   }
 
+  async getSnapshot<T, S>(
+    gameCode: string,
+    snapshotId: string,
+    struct: Struct<T, S>,
+  ) {
+    return await this.fetch(`/v1/snapshots/${gameCode}/${snapshotId}`, struct);
+  }
+
+  async createSnapshot(gameCode: string, payload: object) {
+    return await this.fetch(
+      `/v1/snapshots/${gameCode}`,
+      object({ snapshotId: string() }),
+      { method: "POST", json: payload },
+    );
+  }
+
   async getCurrentUser() {
     const result = await this.fetchWithAuth(`/v1/users/me`, currentUser());
 
@@ -286,6 +302,10 @@ export class IndieTabletopClient {
     return result;
   }
 
+  getRuleset(game: string, version: string) {
+    return this.fetch(`/v1/rulesets/${game}/${version}`, unknown());
+  }
+
   /**
    * Uploads a file given S3 presigned config.
    */
@@ -316,4 +336,19 @@ export class IndieTabletopClient {
       return new Failure({ type: "NETWORK_ERROR" });
     }
   }
+
+  async redeemPledge(id: string) {
+    return await this.fetch(
+      `/v1/redemptions/spacegits/pledges/${id}`,
+      redeemedPledge(),
+    );
+  }
+
+  async subscribeToNewsletterByPledgeId(pledgeId: string) {
+    return await this.fetch(
+      `/v1/newsletters/changelog/subscriptions`,
+      object({ message: string() }),
+      { method: "POST", json: { pledgeId, type: "PLEDGE" } },
+    );
+  }
 }

package/lib/copyrightRange.ts

@@ -0,0 +1,6 @@
+export function copyrightRange(yearSince: number) {
+  const currentYear = new Date().getFullYear();
+  return currentYear === yearSince
+    ? `© ${yearSince}`
+    : `© ${yearSince}–${currentYear}`;
+}

package/lib/groupBy.ts

@@ -0,0 +1,25 @@
+export function groupBy<T, K extends string>(
+  items: T[],
+  getKey: (item: T) => K,
+) {
+  const groups: Partial<Record<K, T[]>> = {};
+
+  for (const item of items) {
+    const key = getKey(item);
+    const group = groups[key];
+    if (group) {
+      group.push(item);
+    } else {
+      groups[key] = [item];
+    }
+  }
+
+  // Using a Proxy to make sure that even if one of the possible group keys
+  // was not included in the provided list, that group will still return
+  // an empty list rather than `undefined`.
+  return new Proxy(groups, {
+    get(target, prop, receiver) {
+      return Reflect.get(target, prop, receiver) ?? [];
+    },
+  }) as Record<K, T[]>;
+}

package/lib/ids.ts

@@ -0,0 +1,6 @@
+import { customAlphabet } from "nanoid";
+
+export const getId = customAlphabet(
+  "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  12,
+);

package/lib/index.ts

@@ -1,4 +1,5 @@
 // Components
+export * from "./ClientContext/ClientContext.tsx";
 export * from "./DialogTrigger/index.tsx";
 export * from "./ExternalLink.tsx";
 export * from "./FormSubmitButton.tsx";
@@ -8,9 +9,12 @@ export * from "./Letterhead/index.tsx";
 export * from "./LetterheadForm/index.tsx";
 export * from "./LoadingIndicator.tsx";
 export * from "./ModalDialog/index.tsx";
+export * from "./ReleaseInfo/index.tsx";
 export * from "./ServiceWorkerHandler.tsx";
+export * from "./SubscribeCard/SubscribeCard.tsx";
 
 // Hooks
+export * from "./RulesetResolver.ts";
 export * from "./use-async-op.ts";
 export * from "./use-document-background-color.ts";
 export * from "./use-form.ts";
@@ -26,10 +30,18 @@ export * from "./async-op.ts";
 export * from "./caught-value.ts";
 export * from "./class-names.ts";
 export * from "./client.ts";
+export * from "./copyrightRange.ts";
 export * from "./failureMessages.ts";
+export * from "./groupBy.ts";
+export * from "./ids.ts";
 export * from "./media.ts";
 export * from "./random.ts";
 export * from "./sleep.ts";
 export * from "./structs.ts";
+export * from "./typeguards.ts";
 export * from "./types.ts";
+export * from "./unique.ts";
 export * from "./validations.ts";
+
+// Other
+export * from "./ModernIDB/index.ts";

package/lib/random.ts

@@ -5,3 +5,15 @@ export function random(max: number) {
 export function randomItem<T>(array: T[]) {
   return array[random(array.length)];
 }
+
+export function randomItemOrThrow<T>(array: T[]) {
+  const item = array[random(array.length)];
+
+  if (!item) {
+    throw new Error(
+      "Could not select a random item from list. Perhaps the list is empty?",
+    );
+  }
+
+  return item;
+}

package/lib/result/swr.ts

@@ -0,0 +1,18 @@
+import type { SWRResponse } from "swr";
+import { Failure, Pending } from "../async-op.ts";
+import type { FailurePayload } from "../types.ts";
+
+export function swrResponseToResult<T>(response: SWRResponse<T, unknown>) {
+  const { data, error } = response;
+
+  if (data !== undefined) {
+    return data;
+  }
+
+  if (error !== undefined) {
+    console.error(error);
+    return new Failure<FailurePayload>({ type: "UNKNOWN_ERROR" });
+  }
+
+  return new Pending();
+}

package/lib/structs.ts

@@ -15,3 +15,13 @@ export function sessionInfo() {
     createdTs: number(),
   });
 }
+
+export function redeemedPledge() {
+  return object({
+    id: string(),
+    downloadUrl: string(),
+    downloadUrlExpiresTs: number(),
+    contactSubscribed: boolean(),
+    email: string(),
+  });
+}

package/lib/typeguards.ts

@@ -0,0 +1,12 @@
+/**
+ * Checkes whether value is `null` or `undefined`.
+ *
+ * In some cases, this is preferrable to using `if (!value)`, as that will
+ * include `""`, `0`, and `false`, which is not always desirable.
+ *
+ * This function uses the same semantics like the nullish coalescing operators
+ * like `??` and `??=`.
+ */
+export function isNullish(value: unknown): value is null | undefined {
+  return value === null || value === undefined;
+}

package/lib/types.ts

@@ -1,10 +1,12 @@
 import type { Infer } from "superstruct";
-import { currentUser, sessionInfo } from "./structs.js";
+import { currentUser, redeemedPledge, sessionInfo } from "./structs.js";
 
 export type CurrentUser = Infer<ReturnType<typeof currentUser>>;
 
 export type SessionInfo = Infer<ReturnType<typeof sessionInfo>>;
 
+export type RedeemedPledge = Infer<ReturnType<typeof redeemedPledge>>;
+
 export type FailurePayload =
   | {
       type: "API_ERROR";

package/lib/unique.test.ts

@@ -0,0 +1,22 @@
+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",
+        },
+      ]
+    `);
+  });
+});

package/lib/unique.ts

@@ -0,0 +1,24 @@
+type UniqueKey = string | number;
+
+/**
+ * Returns an array of unique items, determining uniqueness via the getKey
+ * function.
+ *
+ * Note that the first unique item is returned, all others are omitted
+ * (assuming that they are unique, so it shouldn't matter).
+ */
+export function uniqueBy<T>(items: T[], getKey: (item: T) => UniqueKey): T[] {
+  const seen = new Set<UniqueKey>();
+  const returnItems: T[] = [];
+
+  for (const item of items) {
+    const uniqueKey = getKey(item);
+
+    if (!seen.has(uniqueKey)) {
+      returnItems.push(item);
+      seen.add(uniqueKey);
+    }
+  }
+
+  return returnItems;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "3.5.0",
+  "version": "3.6.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 6006"
+    "storybook": "storybook dev -p 6000"
   },
   "exports": {
     ".": "./lib/index.ts",
@@ -25,11 +25,13 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^9.0.4",
-    "@storybook/react-vite": "^9.0.4",
+    "@storybook/addon-docs": "^9.1.6",
+    "@storybook/react-vite": "^9.1.6",
     "@types/react": "^19.1.8",
+    "msw": "^2.11.2",
+    "msw-storybook-addon": "^2.0.5",
     "np": "^10.1.0",
-    "storybook": "^9.0.4",
+    "storybook": "^9.1.6",
     "typescript": "^5.8.2",
     "vite": "^6.3.5",
     "vitest": "^3.0.5"
@@ -41,6 +43,14 @@
     "@vanilla-extract/dynamic": "^2.1.3",
     "@vanilla-extract/recipes": "^0.5.7",
     "@vanilla-extract/sprinkles": "^1.6.3",
-    "superstruct": "^2.0.2"
+    "nanoid": "^5.1.5",
+    "superstruct": "^2.0.2",
+    "swr": "^2.3.6",
+    "wouter": "^3.7.1"
+  },
+  "msw": {
+    "workerDirectory": [
+      "public"
+    ]
   }
 }