@indietabletop/appkit 7.0.0-0 → 7.0.0-rc.1

package/lib/ShareButton/ShareButton.tsx

@@ -0,0 +1,153 @@
+import { Button, type ButtonProps } from "@ariakit/react";
+import { useState, type ReactNode } from "react";
+import { useRevertingState } from "../use-reverting-state.ts";
+
+type AriakitButtonProps = Omit<ButtonProps, "children" | "onClick" | "value">;
+
+export type CopyToClipboardButtonProps = AriakitButtonProps & {
+  value: string | null;
+  children: ReactNode;
+  revertAfterMs: number;
+};
+
+export function CopyToClipboardButton(props: CopyToClipboardButtonProps) {
+  const { children, value, revertAfterMs, disabled, ...buttonProps } = props;
+  const [copiedTimestamp, setCopiedTimestamp] = useRevertingState<
+    number | null
+  >(null, revertAfterMs);
+
+  return (
+    <Button
+      {...buttonProps}
+      disabled={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, disabled, ...buttonProps } =
+    props;
+
+  // Tracking sharing state to prevent duplicate invocations of
+  // the share dialog.
+  const [sharing, setSharing] = useState(false);
+
+  const [copiedTimestamp, setCopiedTimestamp] = useRevertingState<
+    number | null
+  >(null, revertAfterMs);
+
+  return (
+    <Button
+      {...buttonProps}
+      disabled={disabled || !shareData || sharing}
+      onClick={async () => {
+        if (shareData) {
+          try {
+            setSharing(true);
+
+            await navigator.share(shareData);
+            setCopiedTimestamp(Date.now());
+          } catch {
+            console.info("Not shared");
+          } finally {
+            setSharing(false);
+          }
+        }
+      }}
+    >
+      {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,
+    ...buttonProps
+  } = props;
+
+  if (webShare) {
+    return (
+      <WebShareButton
+        {...buttonProps}
+        shareData={shareData}
+        revertAfterMs={revertAfterMs}
+      >
+        {shareLabel}
+      </WebShareButton>
+    );
+  }
+
+  return (
+    <CopyToClipboardButton
+      {...buttonProps}
+      revertAfterMs={revertAfterMs}
+      value={shareData?.url ?? null}
+    >
+      {copyLabel}
+    </CopyToClipboardButton>
+  );
+}

package/lib/ShareButton/test.css.ts

@@ -0,0 +1,3 @@
+import { style } from "@vanilla-extract/css";
+
+export const test = style({ backgroundColor: "rebeccapurple", color: "wheat" });

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 "./SubscribeByPledgeCard.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,69 @@
+import { http, HttpResponse } from "msw";
+import preview from "../../.storybook/preview.tsx";
+import { LetterheadParagraph } from "../Letterhead/index.tsx";
+import { sleep } from "../sleep.ts";
+import { SubscribeByEmailCard } from "./SubscribeByEmailCard.tsx";
+
+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 });
+      },
+    );
+  },
+};
+
+const meta = preview.meta({
+  title: "Newsletter/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(),
+      },
+    },
+  },
+});
+
+export const Default = meta.story({});

package/lib/SubscribeCard/SubscribeByEmailCard.tsx

@@ -0,0 +1,183 @@
+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;
+};
+
+/**
+ * Allows users to sign up to the newsletter using an arbitrary email.
+ *
+ * Signups are verified using an one-time code, which is sent to the supplied
+ * email address.
+ */
+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/SubscribeByPledgeCard.stories.tsx

@@ -0,0 +1,133 @@
+import { http, HttpResponse } from "msw";
+import preview from "../../.storybook/preview.tsx";
+import { LetterheadParagraph } from "../Letterhead/index.tsx";
+import { sleep } from "../sleep.ts";
+import { SubscribeByPledgeCard } from "./SubscribeByPledgeCard.tsx";
+
+const pledge = {
+  id: "1",
+  email: "test@example.com",
+  contactSubscribed: false,
+};
+
+const subscribeByPledgeId = {
+  success() {
+    return http.post(
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
+      async () => {
+        await sleep(2000);
+
+        return HttpResponse.json(
+          { message: "Added to newsletter" },
+          { status: 201 },
+        );
+      },
+    );
+  },
+  noConnection() {
+    return http.post(
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
+      async () => {
+        return HttpResponse.error();
+      },
+    );
+  },
+  error() {
+    return http.post(
+      "http://mock.api/v1/newsletters/changelog/subscriptions",
+      async () => {
+        await sleep(2000);
+
+        return HttpResponse.text("Application error", { status: 500 });
+      },
+    );
+  },
+};
+
+/**
+ * Allows users to subscribe to ITC's newsletter using the email provided
+ * in their pledge.
+ */
+const meta = preview.meta({
+  title: "Newsletter/Subscribe By Pledge Card",
+  component: SubscribeByPledgeCard,
+  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:
+          "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",
+        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(),
+      },
+    },
+  },
+});
+
+/**
+ * The default case, in which the user is not yet subscribed to ITC's newsletter
+ * and the submission is successful.
+ */
+export const Default = meta.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 = meta.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 = meta.story({
+  args: { pledge: { ...pledge, contactSubscribed: true } },
+});

package/lib/SubscribeCard/SubscribeByPledgeCard.tsx

@@ -0,0 +1,127 @@
+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 "../AppConfig/AppConfig.tsx";
+import { LetterheadInfoCard } from "./LetterheadInfoCard.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(
+        "changelog",
+        pledge.id,
+      );
+
+      return result.mapFailure(getSubmitFailureMessage);
+    },
+  });
+
+  return (
+    <Letterhead>
+      <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>
+  );
+}
+
+type SubscribeStep =
+  | "PREVIOUSLY_SUBSCRIBED"
+  | "SUBSCRIBE"
+  | "SUBSCRIBE_SUCCESS";
+
+export type ViewContent = {
+  title: ReactNode;
+  description: ReactNode;
+};
+
+/**
+ * Allows users to sign up to the newsletter using the email associated with
+ * their pledge ID.
+ *
+ * Emails are not verified using a one-time code, as the user has just
+ * implicitly verified their address by navigating to the page with the unique
+ * pledge ID.
+ */
+export function SubscribeByPledgeCard(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;
+
+  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 <LetterheadInfoCard {...content} />;
+    }
+  }
+}
+
+export {
+  /**
+   * @deprecated Use {@link SubscribeByPledgeCard}
+   */
+  SubscribeByPledgeCard as SubscribeCard,
+};

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",
+  }),
+};