@indietabletop/appkit 3.6.0-2 → 4.0.0-0

package/lib/ShareButton/ShareButton.tsx

@@ -0,0 +1,141 @@
+import { Button, type ButtonProps } from "@ariakit/react";
+import type { ReactNode } from "react";
+import { useRevertingState } from "../use-reverting-state.ts";
+
+type AriakitButtonProps = Omit<
+  ButtonProps,
+  "children" | "onClick" | "disabled" | "value"
+>;
+
+export type CopyToClipboardButtonProps = AriakitButtonProps & {
+  value: string | null;
+  children: ReactNode;
+  revertAfterMs: number;
+};
+
+export function CopyToClipboardButton(props: CopyToClipboardButtonProps) {
+  const { children, value, revertAfterMs, ...buttonProps } = props;
+  const [copiedTimestamp, setCopiedTimestamp] = useRevertingState<
+    number | null
+  >(null, revertAfterMs);
+
+  return (
+    <Button
+      {...buttonProps}
+      disabled={!value}
+      onClick={async () => {
+        if (value) {
+          await navigator.clipboard.writeText(value);
+          setCopiedTimestamp(Date.now());
+        }
+      }}
+    >
+      {copiedTimestamp ? "Copied!" : children}
+    </Button>
+  );
+}
+
+export type WebShareButtonProps = AriakitButtonProps & {
+  children: ReactNode;
+  shareData: ShareData | null;
+  revertAfterMs: number;
+};
+
+export function WebShareButton(props: WebShareButtonProps) {
+  const { shareData, children, revertAfterMs, ...buttonProps } = props;
+
+  const [copiedTimestamp, setCopiedTimestamp] = useRevertingState<
+    number | null
+  >(null, revertAfterMs);
+
+  return (
+    <Button
+      {...buttonProps}
+      disabled={!shareData}
+      onClick={async () => {
+        if (shareData) {
+          try {
+            await navigator.share(shareData);
+            setCopiedTimestamp(Date.now());
+          } catch {
+            console.info("Not shared");
+          }
+        }
+      }}
+    >
+      {copiedTimestamp ? "Shared!" : children}
+    </Button>
+  );
+}
+
+export type ShareButtonProps = AriakitButtonProps & {
+  /**
+   * Button label to use when copy to clipboard is used.
+   */
+  copyLabel: string;
+
+  /**
+   * Button label to use when web share is used.
+   */
+  shareLabel: string;
+
+  /**
+   * Data to be shared by the button.
+   *
+   * If using copy to clipboard, only the URL value will be used.
+   */
+  shareData: ShareData | null;
+
+  /**
+   * How long should the confirmation message be shown within the button?
+   *
+   * @default 1500
+   */
+  revertAfterMs?: number;
+
+  /**
+   * Should web share be used instead of copy to clipboard?
+   *
+   * By default, web share will be used if the browser supports it.
+   *
+   * @default !!navigator.share
+   */
+  webShare?: boolean;
+};
+
+/**
+ * An unstyled button that is pre-configured to either copy provided share data
+ * to clipboard, or to use web share, depending on which feature is detected
+ * in the browser where the button is running.
+ *
+ * Props that are not consumed by the Share Button itself are passed to the
+ * underlying Ariakit Button component.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share
+ */
+export function ShareButton(props: ShareButtonProps) {
+  const {
+    copyLabel,
+    shareLabel,
+    shareData,
+    revertAfterMs = 1500,
+    webShare = !!navigator.share,
+  } = props;
+
+  if (webShare) {
+    return (
+      <WebShareButton shareData={shareData} revertAfterMs={revertAfterMs}>
+        {shareLabel}
+      </WebShareButton>
+    );
+  }
+
+  return (
+    <CopyToClipboardButton
+      revertAfterMs={revertAfterMs}
+      value={shareData?.url ?? null}
+    >
+      {copyLabel}
+    </CopyToClipboardButton>
+  );
+}

package/lib/SubscribeCard/LetterheadInfoCard.tsx

@@ -0,0 +1,23 @@
+import {
+  Letterhead,
+  LetterheadHeading,
+  LetterheadParagraph,
+} from "../Letterhead/index.tsx";
+import * as css from "./style.css.ts";
+import type { ViewContent } from "./SubscribeCard.tsx";
+
+export function LetterheadInfoCard(props: ViewContent) {
+  return (
+    <Letterhead>
+      <LetterheadHeading className={css.card.heading}>
+        {props.title}
+      </LetterheadHeading>
+
+      {typeof props.description === "string" ? (
+        <LetterheadParagraph>{props.description}</LetterheadParagraph>
+      ) : (
+        props.description
+      )}
+    </Letterhead>
+  );
+}

package/lib/SubscribeCard/SubscribeByEmailCard.stories.tsx

@@ -0,0 +1,83 @@
+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 { SubscribeByEmailCard } from "./SubscribeByEmailCard.tsx";
+
+const pledge = {
+  id: "1",
+  email: "test@example.com",
+  contactSubscribed: false,
+};
+
+const handlers = {
+  subscribe() {
+    return http.post(
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
+      async () => {
+        await sleep(2000);
+
+        return HttpResponse.json(
+          { tokenId: "1", message: "Ok" },
+          { status: 201 },
+        );
+      },
+    );
+  },
+  confirm() {
+    return http.put(
+      "http://mock.api/v1/newsletters/changelog/newsletter-signup-tokens/:tokenId",
+      async () => {
+        await sleep(2000);
+
+        return HttpResponse.json({ message: "Ok" }, { status: 201 });
+      },
+    );
+  },
+};
+
+/**
+ * Allows users to subscribe to ITC's newsletter using the email provided
+ * in their pledge.
+ */
+const meta = {
+  title: "Pages/Subscribe By Email Card",
+  component: SubscribeByEmailCard,
+  tags: ["autodocs"],
+  args: {
+    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:
+          "Thank you for being awesome. Once Space Gits is available for " +
+          "early access, you will be among the first to know!",
+      },
+    },
+  },
+  parameters: {
+    msw: {
+      handlers: {
+        subscribe: handlers.subscribe(),
+        confirm: handlers.confirm(),
+      },
+    },
+  },
+} satisfies Meta<typeof SubscribeByEmailCard>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/lib/SubscribeCard/SubscribeByEmailCard.tsx

@@ -0,0 +1,177 @@
+import { Form } from "@ariakit/react";
+import {
+  getSubmitFailureMessage,
+  Letterhead,
+  LetterheadFormActions,
+  LetterheadHeader,
+  LetterheadHeading,
+  LetterheadParagraph,
+  LetterheadSubmitButton,
+  LetterheadSubmitError,
+  LetterheadTextField,
+  useForm,
+  validEmail,
+} from "@indietabletop/appkit";
+import {
+  useState,
+  type Dispatch,
+  type ReactNode,
+  type SetStateAction,
+} from "react";
+import { useAppConfig, useClient } from "../AppConfig/AppConfig.tsx";
+import { LetterheadInfoCard } from "./LetterheadInfoCard.tsx";
+import * as css from "./style.css.ts";
+
+type SetStep = Dispatch<SetStateAction<SubscribeStep>>;
+
+function SubscribeView(
+  props: ViewContent & {
+    setStep: SetStep;
+  },
+) {
+  const { placeholders } = useAppConfig();
+  const { title, description, setStep } = props;
+
+  const client = useClient();
+  const { form, submitName } = useForm({
+    defaultValues: {
+      email: "",
+    },
+    validate: {
+      email: validEmail,
+    },
+    async onSubmit({ values }) {
+      const result = await client.subscribeToNewsletterByEmail(
+        "changelog",
+        values.email,
+      );
+
+      return result.mapFailure(getSubmitFailureMessage);
+    },
+    async onSuccess({ tokenId }, { values }) {
+      setStep({ type: "SUBMIT_CODE", email: values.email, tokenId });
+    },
+  });
+
+  return (
+    <Form store={form} resetOnSubmit={false}>
+      <Letterhead>
+        <LetterheadHeader>
+          <LetterheadHeading className={css.card.heading}>
+            {title}
+          </LetterheadHeading>
+
+          {description}
+        </LetterheadHeader>
+
+        <LetterheadTextField
+          name={form.names.email}
+          label="Your email"
+          placeholder={placeholders.email}
+          autoComplete="email"
+          required
+        />
+
+        <LetterheadFormActions>
+          <LetterheadSubmitError name={submitName} />
+          <LetterheadSubmitButton>Subscribe</LetterheadSubmitButton>
+        </LetterheadFormActions>
+      </Letterhead>
+    </Form>
+  );
+}
+
+function SubmitCodeStep(props: {
+  tokenId: string;
+  setStep: SetStep;
+  email: string;
+}) {
+  const { tokenId, email, setStep } = props;
+  const client = useClient();
+
+  const { form, submitName } = useForm({
+    defaultValues: {
+      code: "",
+    },
+    async onSubmit({ values }) {
+      const op = await client.confirmNewsletterSignup(
+        "changelog",
+        tokenId,
+        values.code,
+      );
+
+      return op.mapFailure((failure) => {
+        return getSubmitFailureMessage(failure, {
+          404: "🚫 This code is incorrect or expired. Please try again.",
+        });
+      });
+    },
+    onSuccess() {
+      setStep({ type: "SUBSCRIBE_SUCCESS" });
+    },
+  });
+
+  return (
+    <Form store={form} resetOnSubmit={false}>
+      <Letterhead>
+        <LetterheadHeader>
+          <LetterheadHeading>Confirm subscription</LetterheadHeading>
+          <LetterheadParagraph>
+            We've sent a one-time code to <em>{email}</em>. Please, enter the
+            code in the field below to confirm your newsletter subscription.
+          </LetterheadParagraph>
+        </LetterheadHeader>
+
+        <LetterheadTextField
+          name={form.names.code}
+          label="Code"
+          placeholder="E.g. 123123"
+          autoComplete="one-time-code"
+          required
+        />
+
+        <LetterheadFormActions>
+          <LetterheadSubmitError name={submitName} />
+          <LetterheadSubmitButton>Confirm</LetterheadSubmitButton>
+        </LetterheadFormActions>
+      </Letterhead>
+    </Form>
+  );
+}
+
+type SubscribeStep =
+  | { type: "SUBSCRIBE" }
+  | { type: "SUBMIT_CODE"; email: string; tokenId: string }
+  | { type: "SUBSCRIBE_SUCCESS" };
+
+type ViewContent = {
+  title: ReactNode;
+  description: ReactNode;
+};
+
+export function SubscribeByEmailCard(props: {
+  content: Record<Exclude<SubscribeStep["type"], "SUBMIT_CODE">, ViewContent>;
+}) {
+  const { content } = props;
+  const [step, setStep] = useState<SubscribeStep>({ type: "SUBSCRIBE" });
+
+  switch (step.type) {
+    case "SUBSCRIBE": {
+      return <SubscribeView {...content[step.type]} setStep={setStep} />;
+    }
+
+    case "SUBMIT_CODE": {
+      return (
+        <SubmitCodeStep
+          email={step.email}
+          tokenId={step.tokenId}
+          setStep={setStep}
+        />
+      );
+    }
+
+    case "SUBSCRIBE_SUCCESS": {
+      return <LetterheadInfoCard {...content[step.type]} />;
+    }
+  }
+}

package/lib/SubscribeCard/SubscribeCard.stories.tsx

@@ -13,7 +13,7 @@ const pledge = {
 const subscribeByPledgeId = {
   success() {
     return http.post(
-      "http://localhost:8000/v1/newsletters/changelog/subscriptions",
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
       async () => {
         await sleep(2000);
 
@@ -26,7 +26,7 @@ const subscribeByPledgeId = {
   },
   noConnection() {
     return http.post(
-      "http://localhost:8000/v1/newsletters/changelog/subscriptions",
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
       async () => {
         return HttpResponse.error();
       },
@@ -34,7 +34,7 @@ const subscribeByPledgeId = {
   },
   error() {
     return http.post(
-      "http://localhost:8000/v1/newsletters/changelog/subscriptions",
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
       async () => {
         await sleep(2000);
 
@@ -44,6 +44,10 @@ const subscribeByPledgeId = {
   },
 };
 
+/**
+ * Allows users to subscribe to ITC's newsletter using the email provided
+ * in their pledge.
+ */
 const meta = {
   title: "Pages/Subscribe Card",
   component: SubscribeCard,
@@ -65,12 +69,9 @@ const meta = {
       },
       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>
-        ),
+        description:
+          "Thank you for being awesome. Once Space Gits is available for " +
+          "early access, you will be among the first to know!",
       },
       PREVIOUSLY_SUBSCRIBED: {
         title: "Space Gits on Indie Tabletop Club",
@@ -106,28 +107,31 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
+/**
+ * The default case, in which the user is not yet subscribed to ITC's newsletter
+ * and the submission is successful.
+ */
 export const Default: Story = {};
 
-export const AlreadySubscribed: Story = {
-  args: { pledge: { ...pledge, contactSubscribed: true } },
-};
-
-export const NoConnection: Story = {
+/**
+ * Same like the default case, but the form submission fails. Errors are
+ * differentiated using the `getSubmitFailureMessage` helper, so all the basics
+ * should be covered, as this page doesn't have special cases.
+ */
+export const FailureOnSubmit: Story = {
   parameters: {
     msw: {
       handlers: {
-        subscribeByPledgeId: subscribeByPledgeId.noConnection(),
+        subscribeByPledgeId: subscribeByPledgeId.error(),
       },
     },
   },
 };
 
-export const FallbackFailure: Story = {
-  parameters: {
-    msw: {
-      handlers: {
-        subscribeByPledgeId: subscribeByPledgeId.error(),
-      },
-    },
-  },
+/**
+ * In this case, the email address associated with this user account is
+ * already subscribed to our newsletter.
+ */
+export const AlreadySubscribed: Story = {
+  args: { pledge: { ...pledge, contactSubscribed: true } },
 };

package/lib/SubscribeCard/SubscribeCard.tsx

@@ -10,7 +10,8 @@ import {
   type RedeemedPledge,
 } from "@indietabletop/appkit";
 import { useState, type ReactNode } from "react";
-import { useClient } from "../ClientContext/ClientContext.tsx";
+import { useClient } from "../AppConfig/AppConfig.tsx";
+import { LetterheadInfoCard } from "./LetterheadInfoCard.tsx";
 import * as css from "./style.css.ts";
 
 type Pledge = Pick<RedeemedPledge, "id" | "email" | "contactSubscribed">;
@@ -38,7 +39,7 @@ function SubscribeView(
   });
 
   return (
-    <Letterhead textAlign="center">
+    <Letterhead>
       <LetterheadHeading className={css.card.heading}>
         {title}
       </LetterheadHeading>
@@ -58,30 +59,30 @@ function SubscribeView(
   );
 }
 
-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 = {
+export type ViewContent = {
   title: ReactNode;
   description: ReactNode;
 };
 
 export function SubscribeCard(props: {
+  /**
+   * The pledge data that will be used to determine whether the user should
+   * be prompted for signup.
+   */
   pledge: Pledge;
+
+  /**
+   * Content for each of the subscribe steps. You probably want to customize it
+   * for each step, so it is left to be defined at point of usage.
+   *
+   * If the `description` is a string, it will be wrapped in
+   * `<LetterheadParagraph>`, otherwise it will be left as is.
+   */
   content: Record<SubscribeStep, ViewContent>;
 }) {
   const { pledge } = props;
@@ -105,7 +106,7 @@ export function SubscribeCard(props: {
 
     case "PREVIOUSLY_SUBSCRIBED":
     case "SUBSCRIBE_SUCCESS": {
-      return <InfoView {...content} />;
+      return <LetterheadInfoCard {...content} />;
     }
   }
 }

package/lib/account/AccountIssueView.tsx

@@ -0,0 +1,40 @@
+import { Button } from "@ariakit/react";
+import { cx } from "../class-names.ts";
+import { interactiveText } from "../common.css.ts";
+import {
+  Letterhead,
+  LetterheadHeading,
+  LetterheadParagraph,
+} from "../Letterhead/index.tsx";
+import type { EventHandlerWithReload } from "./types.ts";
+
+export function AccountIssueView(props: {
+  onLogout: EventHandlerWithReload;
+  reload: () => void;
+}) {
+  const { onLogout, reload } = props;
+
+  return (
+    <Letterhead>
+      <LetterheadHeading>Account issue</LetterheadHeading>
+
+      <LetterheadParagraph>
+        You appear to be logged into an account that no longer exists, or is not
+        working as expected. Sorry about that!
+      </LetterheadParagraph>
+
+      <LetterheadParagraph>
+        {"You can try "}
+        <Button {...cx(interactiveText)} onClick={() => onLogout({ reload })}>
+          logging out
+        </Button>
+        {" and in again. "}
+        {"If the issue persists, please get in touch at "}
+        <a {...cx(interactiveText)} href="mailto:support@indietabletop.club">
+          support@indietabletop.club
+        </a>
+        {"."}
+      </LetterheadParagraph>
+    </Letterhead>
+  );
+}

package/lib/account/AlreadyLoggedInView.tsx

@@ -0,0 +1,44 @@
+import { Button } from "@ariakit/react";
+import { Link } from "wouter";
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
+import { interactiveText } from "../common.css.ts";
+import {
+  Letterhead,
+  LetterheadHeading,
+  LetterheadParagraph,
+} from "../Letterhead/index.tsx";
+import type { CurrentUser } from "../types.ts";
+import type { EventHandlerWithReload } from "./types.ts";
+
+export function AlreadyLoggedInView(props: {
+  currentUser: CurrentUser;
+  onLogout: EventHandlerWithReload;
+  reload: () => void;
+}) {
+  const { hrefs } = useAppConfig();
+  const { currentUser, onLogout, reload } = props;
+
+  return (
+    <Letterhead>
+      <LetterheadHeading>Logged in</LetterheadHeading>
+      <LetterheadParagraph>
+        You are already logged into Indie Tabletop Club as{" "}
+        <em>{currentUser.email}</em>.
+      </LetterheadParagraph>
+
+      <LetterheadParagraph>
+        <Link className={interactiveText} href={hrefs.dashboard()}>
+          Continue
+        </Link>
+        {` as current user, or `}
+        <Button
+          className={interactiveText}
+          onClick={() => onLogout({ reload })}
+        >
+          log out
+        </Button>
+        .
+      </LetterheadParagraph>
+    </Letterhead>
+  );
+}