@indietabletop/appkit 3.2.0-7 → 3.2.0-9

package/lib/LetterheadForm/LetterheadReadonlyTextField.stories.tsx

@@ -0,0 +1,21 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { LetterheadReadonlyTextField } from "./index.tsx";
+
+const meta = {
+  title: "ReadonlyTextField",
+  component: LetterheadReadonlyTextField,
+  tags: ["autodocs"],
+  args: {},
+} satisfies Meta<typeof LetterheadReadonlyTextField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: "Email",
+    value: "john@example.com",
+    placeholder: "john@example.com",
+  },
+};

package/lib/LetterheadForm/LetterheadSubmitError.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { form } from "../storybook/decorators.tsx";
+import { LetterheadSubmitError } from "./index.tsx";
+
+const meta = {
+  title: "LetterheadSubmitError",
+  component: LetterheadSubmitError,
+  tags: ["autodocs"],
+  args: {},
+  decorators: [
+    form({ defaultErrors: { submit: "This is an error message." } }),
+  ],
+} satisfies Meta<typeof LetterheadSubmitError>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    name: "submit",
+  },
+};

package/lib/LetterheadForm/LetterheadTextField.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { form } from "../storybook/decorators.tsx";
+import { LetterheadTextField } from "./index.tsx";
+
+const meta = {
+  title: "FormTextField",
+  component: LetterheadTextField,
+  tags: ["autodocs"],
+  args: {},
+  decorators: [form()],
+} satisfies Meta<typeof LetterheadTextField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: "Email",
+    placeholder: "john@example.com",
+    name: "foo",
+  },
+};

package/lib/LetterheadForm/index.tsx

@@ -0,0 +1,94 @@
+import {
+  FormError,
+  FormInput,
+  type FormInputProps,
+  FormLabel,
+  useFormContext,
+  useStoreState,
+} from "@ariakit/react";
+import { type ReactNode } from "react";
+import * as css from "./style.css.ts";
+
+type LetterheadTextFieldProps = FormInputProps & {
+  label: string;
+  hint?: ReactNode;
+};
+
+export function LetterheadTextField(props: LetterheadTextFieldProps) {
+  const { name, label, hint, ...inputProps } = props;
+
+  return (
+    <div>
+      <div className={css.field}>
+        <FormLabel name={name} className={css.fieldLabel}>
+          {label}
+        </FormLabel>
+
+        <FormInput {...inputProps} name={name} className={css.fieldInput} />
+      </div>
+
+      <FormError name={name} className={css.fieldIssue} />
+
+      {hint && <div className={css.fieldHint}>{hint}</div>}
+    </div>
+  );
+}
+
+type LetterheadReadonlyTextFieldProps = {
+  label: string;
+  value: string;
+  placeholder?: string;
+  hint?: ReactNode;
+  type?: "text" | "email" | "password";
+};
+
+/**
+ * Renders a read-only text field.
+ *
+ * For an editable text field, use {@link LetterheadTextField} along with
+ * Ariakit form store.
+ */
+export function LetterheadReadonlyTextField(
+  props: LetterheadReadonlyTextFieldProps,
+) {
+  return (
+    <div>
+      <label className={css.field}>
+        <span className={css.fieldLabel}>{props.label}</span>
+
+        <input
+          className={css.fieldInput}
+          type={props.type ?? "text"}
+          value={props.value}
+          placeholder={props.placeholder}
+          readOnly
+        />
+      </label>
+
+      {props.hint && <div className={css.fieldHint}>{props.hint}</div>}
+    </div>
+  );
+}
+
+type LetterheadSubmitErrorProps = {
+  name: string;
+};
+
+/**
+ * Renders an error message from form context.
+ *
+ * If there is no error message, will be completely omitted from DOM, so there
+ * is no need to guard it with an if statement.
+ */
+export function LetterheadSubmitError(props: LetterheadSubmitErrorProps) {
+  const form = useFormContext();
+  const message = useStoreState(form, (s) => {
+    return s?.errors[props.name] as string | undefined;
+  });
+
+  return (
+    <div role="alert" className={css.submitError}>
+      {message}
+    </div>
+  );
+}

package/lib/LetterheadForm/style.css.ts

@@ -0,0 +1,80 @@
+import { style } from "@vanilla-extract/css";
+import { manofa, minion } from "../common.css.ts";
+import { Color } from "../vars.css.ts";
+
+const border = style({
+  borderRadius: "0.5rem",
+  border: `1px solid ${Color.GRAY}`,
+});
+
+export const field = style({
+  display: "block",
+});
+
+export const fieldLabel = style([
+  manofa,
+  {
+    display: "block",
+    textTransform: "uppercase",
+    fontSize: "0.75rem",
+    fontWeight: 600,
+    marginBottom: "0.5rem",
+  },
+]);
+
+export const fieldInput = style([
+  border,
+  minion,
+  {
+    display: "block",
+    width: "100%",
+    fontSize: "1rem",
+    lineHeight: "1.25rem",
+    padding: "1rem 0 1rem 1rem",
+
+    ":read-only": {
+      backgroundColor: "hsl(0 0% 0% / 0.05)",
+    },
+
+    // Hide MS Edge widgets -- we handle them manually
+    "::-ms-clear": {
+      display: "none",
+    },
+    "::-ms-reveal": {
+      display: "none",
+    },
+  },
+]);
+
+export const fieldIssue = style({
+  color: Color.PURPLE,
+  fontSize: "0.875rem",
+  marginTop: "0.5rem",
+
+  ":empty": {
+    display: "none",
+  },
+});
+
+export const fieldHint = style({
+  color: Color.MID_GRAY,
+  fontSize: "0.875rem",
+  marginTop: "0.5rem",
+
+  selectors: {
+    [`${fieldIssue}:not(:empty) + &`]: {
+      display: "none",
+    },
+  },
+});
+
+export const submitError = style({
+  padding: "1rem",
+  color: Color.PURPLE,
+  backgroundColor: Color.PALE_GRAY,
+  borderRadius: "0.75rem",
+
+  ":empty": {
+    display: "none",
+  },
+});

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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,138 @@
+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(`
+      {
+        "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(`
+      {
+        "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(`
+      {
+        "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(`
+      {
+        "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(`
+      {
+        "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(`
+      {
+        "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(`
+      {
+        "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/failureMessages.ts

@@ -0,0 +1,76 @@
+import type { FailurePayload } from "./types.ts";
+
+type OnOverride<T> = (fallback: T, override?: Partial<T>) => T;
+
+function createFailureMessageGetter<T>(
+  defaults: Record<number | "fallback" | "connection", T>,
+  options: { onOverride: OnOverride<T> },
+) {
+  return function getMessage(
+    failure: FailurePayload,
+    overrides: Record<number, Partial<T>> = {},
+  ) {
+    switch (failure.type) {
+      case "API_ERROR": {
+        return options.onOverride(
+          defaults[failure.code] ?? defaults.fallback,
+          overrides[failure.code],
+        );
+      }
+
+      case "NETWORK_ERROR": {
+        return defaults.connection;
+      }
+
+      default: {
+        return defaults.fallback;
+      }
+    }
+  };
+}
+
+export const getFetchFailureMessages = createFailureMessageGetter(
+  {
+    404: {
+      title: `Not found`,
+      description: `The link you have followed might be broken.`,
+    },
+    500: {
+      title: `Ooops, something went wrong`,
+      description: `This is probably an issue with our servers. You can try refreshing.`,
+    },
+    connection: {
+      title: `No connection`,
+      description: `Check your interent connection and try again.`,
+    },
+    fallback: {
+      title: `Ooops, something went wrong`,
+      description: `This is probably an issue on our side. You can try refreshing.`,
+    },
+  },
+  {
+    onOverride(fallback, override) {
+      return { ...fallback, ...override };
+    },
+  },
+);
+
+export const getSubmitFailureMessage = createFailureMessageGetter(
+  {
+    500: `Could not submit form due to an unexpected server error. Please refresh the page and try again.`,
+    connection: `Could not submit form due to network error. Make sure you are connected to the internet and try again.`,
+    fallback: `Could not submit form due to an unexpected error. Please refresh the page and try again.`,
+  },
+  {
+    onOverride(fallback, override) {
+      return override ?? fallback;
+    },
+  },
+);
+
+/**
+ * @deprecated Use {@link getSubmitFailureMessage} instead.
+ */
+export function toKnownFailureMessage(failure: FailurePayload) {
+  return getSubmitFailureMessage(failure);
+}

package/lib/globals.css.ts

@@ -1,5 +1,8 @@
 import { globalStyle } from "@vanilla-extract/css";
 
+// Apply global vars
+import "./vars.css.ts";
+
 globalStyle(":root", {
   fontSynthesis: "none",
   textRendering: "optimizeLegibility",

package/lib/index.ts

@@ -4,6 +4,7 @@ export * from "./FormSubmitButton.tsx";
 export * from "./FullscreenDismissBlocker.tsx";
 export * from "./IndieTabletopClubSymbol.tsx";
 export * from "./Letterhead/index.tsx";
+export * from "./LetterheadForm/index.tsx";
 export * from "./LoadingIndicator.tsx";
 export * from "./ServiceWorkerHandler.tsx";
 
@@ -22,7 +23,7 @@ export * from "./async-op.ts";
 export * from "./caught-value.ts";
 export * from "./class-names.ts";
 export * from "./client.ts";
-export * from "./knownFailure.ts";
+export * from "./failureMessages.ts";
 export * from "./media.ts";
 export * from "./structs.ts";
 export * from "./types.ts";

package/lib/storybook/decorators.tsx

@@ -0,0 +1,10 @@
+import { FormProvider, type FormProviderProps } from "@ariakit/react";
+import { type Decorator } from "@storybook/react-vite";
+
+export function form(props?: FormProviderProps): Decorator {
+  return (Story) => (
+    <FormProvider {...props}>
+      <Story />
+    </FormProvider>
+  );
+}

package/lib/vars.css.ts

@@ -0,0 +1,9 @@
+import { createGlobalTheme } from "@vanilla-extract/css";
+
+export const Color = createGlobalTheme(":root", {
+  GRAY: "#ececec",
+  MID_GRAY: "hsl(0 0% 50%)",
+  LIGHT_GRAY: "#e7e8e8",
+  PALE_GRAY: "#f6f7f7",
+  PURPLE: "#d6446e",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "3.2.0-7",
+  "version": "3.2.0-9",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",

package/lib/knownFailure.ts

@@ -1,9 +0,0 @@
-import type { FailurePayload } from "./types.ts";
-
-export function toKnownFailureMessage(failure: FailurePayload) {
-  if (failure.type === "NETWORK_ERROR") {
-    return "Could not submit form due to network error. Make sure you are connected to the internet and try again.";
-  }
-
-  return "Could not submit form due to an unexpected error. Please refresh the page and try again.";
-}