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

package/lib/createSafeStorage.ts

@@ -0,0 +1,91 @@
+import { type Struct, validate } from "superstruct";
+import { fromTryCatch } from "./async-op.ts";
+
+type AnyStruct = Struct<any, any>;
+
+type StructsConfig = Record<string, AnyStruct>;
+
+type SafeStorage<T extends Record<string, AnyStruct>> = ReturnType<
+  typeof createSafeStorage<T>
+>;
+
+export type SafeStorageKey<T extends SafeStorage<StructsConfig>> = ReturnType<
+  T["keys"]
+>[number];
+
+type StructValue<T> = T extends Struct<infer V> ? V : never;
+
+/**
+ * Creates an object with an interface similar to localStorage, but that
+ * enforces that values are parsed and validated before being retrieved,
+ * stringified when being set, and that both keys and values typecheck.
+ *
+ * @example
+ * ```ts
+ * const safeStorage = createSafeStorage({
+ *   currentUser: currentUser(),
+ *   sessionInfo: sessionInfo(),
+ *   lastSuccessfulSyncTs: number(),
+ * });
+ *
+ * safeStorage.getItem("currentUser") // Will be valid current user or `null`
+ * safeStorage.setItem("currentUser", { ... }) // Typechecked key and value
+ * safeStorage.removeItem("currentUser") // Typechecked key
+ * safeStorage.clear() // Removes all "owned" keys
+ *
+ * ```
+ */
+export function createSafeStorage<T extends StructsConfig>(structs: T) {
+  return {
+    getItem<K extends keyof T & string>(key: K) {
+      const struct = structs[key];
+      if (!struct) {
+        throw new Error(`No struct found for ${key}`);
+      }
+
+      const storedValue = localStorage.getItem(key);
+
+      if (storedValue === null) {
+        return null;
+      }
+
+      const parsedResult = fromTryCatch<unknown>(() => JSON.parse(storedValue));
+
+      if (parsedResult.isFailure) {
+        console.warn(`Could not parse localStorage value at key '${key}'.`);
+        return null;
+      }
+
+      const [error, value] = validate(parsedResult.value, struct, {
+        coerce: true,
+        mask: true,
+      });
+
+      if (error) {
+        console.warn(
+          `Validation failed for localStorage value at key '${key}'. ${error.message}`,
+        );
+      }
+
+      return value as StructValue<T[K]> | null;
+    },
+
+    setItem<K extends keyof T & string>(key: K, value: StructValue<T[K]>) {
+      localStorage.setItem(key, JSON.stringify(value));
+    },
+
+    removeItem(key: keyof T & string) {
+      localStorage.removeItem(key);
+    },
+
+    clear() {
+      for (const key in structs) {
+        localStorage.removeItem(key);
+      }
+    },
+
+    keys() {
+      return Object.keys(structs) as (keyof T)[];
+    },
+  };
+}

package/lib/createStrictContext.ts

@@ -0,0 +1,15 @@
+import { createContext, use } from "react";
+
+export function createStrictContext<T>() {
+  const Context = createContext<T | null>(null);
+
+  const useStrictContext = () => {
+    const value = use(Context);
+    if (!value) {
+      throw new Error(`Value not found in context.`);
+    }
+    return value;
+  };
+
+  return [Context, useStrictContext] as const;
+}

package/lib/failureMessages.ts

@@ -0,0 +1,108 @@
+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 type FetchFailureAction =
+  | {
+      type: "LINK";
+      href: string;
+      label: string;
+    }
+  | {
+      type: "RELOAD" | "REFETCH";
+      label: string;
+    };
+
+export type FetchFailureMessages = {
+  title: string;
+  description: string;
+  action: FetchFailureAction;
+};
+
+export const getFetchFailureMessages =
+  createFailureMessageGetter<FetchFailureMessages>(
+    {
+      401: {
+        title: "Not logged in",
+        description: "You must be logged in to view this page.",
+        action: { type: "LINK", href: "~/login", label: "Go to login" },
+      },
+      403: {
+        title: "Not authorized",
+        description: "You might be logged into the wrong account.",
+        action: { type: "LINK", href: "~/login", label: "Go to login" },
+      },
+      404: {
+        title: `Not found`,
+        description: `The link you have followed might be broken.`,
+        action: { type: "LINK", href: "~/", label: "Go back" },
+      },
+      500: {
+        title: `Ooops, something went wrong`,
+        description: `This is probably an issue with our servers. You can try refreshing.`,
+        action: { type: "RELOAD", label: "Reload app" },
+      },
+      connection: {
+        title: `No connection`,
+        description: `Check your interent connection and try again.`,
+        action: { type: "REFETCH", label: "Retry request" },
+      },
+      fallback: {
+        title: `Ooops, something went wrong`,
+        description: `This is probably an issue on our side. You can try refreshing.`,
+        action: { type: "RELOAD", label: "Reload app" },
+      },
+    },
+    {
+      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/form/FormSubmitButton.tsx

@@ -0,0 +1,58 @@
+import {
+  type FormSubmitProps,
+  FormSubmit,
+  useFormContext,
+  useStoreState,
+} from "@ariakit/react";
+import type { ReactNode } from "react";
+import { fadeIn } from "../animations.css.ts";
+
+export type FormSubmitButtonProps = FormSubmitProps & {
+  children: ReactNode;
+  loading: ReactNode;
+};
+
+/**
+ * Renders Ariakit FormSubmit component.
+ *
+ * It's main responsibility is to render the loading component (provided via
+ * the `loading` prop) when the form is in the submitting state. This component
+ * will be rendered over the usual content of the button, which will be hidden
+ * as long as the form is submitting.
+ *
+ * @remarks Must be rendered within Ariakit Form Context.
+ */
+export function FormSubmitButton(props: FormSubmitButtonProps) {
+  const { children, className, style, loading, ...submitProps } = props;
+  const form = useFormContext();
+  const isSubmitting = useStoreState(form, (s) => s?.submitting);
+
+  return (
+    <FormSubmit
+      {...submitProps}
+      className={className}
+      style={{ position: "relative", ...style }}
+    >
+      <span
+        style={{ opacity: isSubmitting ? 0 : 1, transition: "200ms opacity" }}
+      >
+        {children}
+      </span>
+
+      {isSubmitting && (
+        <div
+          style={{
+            display: "flex",
+            position: "absolute",
+            inset: "0",
+            alignItems: "center",
+            justifyContent: "center",
+            animation: `${fadeIn} 200ms 200ms both`,
+          }}
+        >
+          {loading}
+        </div>
+      )}
+    </FormSubmit>
+  );
+}

package/lib/form/SubmitErrorAlert.tsx

@@ -0,0 +1,21 @@
+import { useFormContext, useStoreState } from "@ariakit/react";
+import { cx } from "../class-names.ts";
+import { submitErrorAlert } from "./style.css.ts";
+
+export type SubmitErrorMessageProps = {
+  name: string;
+  className?: string;
+};
+
+export function SubmitErrorAlert(props: SubmitErrorMessageProps) {
+  const form = useFormContext();
+  const message = useStoreState(form, (s) => {
+    return s?.errors[props.name] as string | undefined;
+  });
+
+  return (
+    <div role="alert" {...cx(props, submitErrorAlert.container)}>
+      {message}
+    </div>
+  );
+}

package/lib/form/style.css.ts

@@ -0,0 +1,9 @@
+import { style } from "@vanilla-extract/css";
+
+export const submitErrorAlert = {
+  container: style({
+    ":empty": {
+      display: "none",
+    },
+  }),
+};

package/lib/globals.css.ts

@@ -0,0 +1,62 @@
+import { globalStyle } from "@vanilla-extract/css";
+
+// Apply global vars
+import "./vars.css.ts";
+
+globalStyle(":root", {
+  interpolateSize: "allow-keywords",
+  fontSynthesis: "none",
+  textRendering: "optimizeLegibility",
+  WebkitFontSmoothing: "antialiased",
+  MozOsxFontSmoothing: "grayscale",
+  WebkitTapHighlightColor: "transparent",
+});
+
+globalStyle("*", {
+  boxSizing: "border-box",
+});
+
+globalStyle("img, picture, svg", {
+  display: "block",
+});
+
+globalStyle("a", {
+  display: "block",
+  color: "inherit",
+  textDecoration: "none",
+});
+
+globalStyle("input, textarea", {
+  fontFamily: "inherit",
+});
+
+globalStyle("button", {
+  display: "block",
+  fontSize: "inherit",
+  fontFamily: "inherit",
+  backgroundColor: "transparent",
+  border: "none",
+  color: "inherit",
+  cursor: "pointer",
+  padding: 0,
+});
+
+globalStyle("body, h1, h2, h3, h4, h5, h6, p, ul, li, ol", {
+  margin: 0,
+  padding: 0,
+});
+
+globalStyle("ul, ol", {
+  listStyle: "none",
+});
+
+// Fathom SPA support depends on this image being added to the DOM, but they
+// are sloppy about taking out of the document flow, meaning that on pages
+// that are 100vh, there is a scrollbar flicker as the img element is added
+// to the DOM and then removed. This fixes said issue.
+globalStyle(`img[src^="https://cdn.usefathom.com/"]`, {
+  position: "absolute",
+  top: 0,
+  left: 0,
+  opacity: 0.01,
+});

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

@@ -0,0 +1,48 @@
+import type { LinkUtmParams, createUtm } from "./utm.ts";
+
+type InputAppHrefs = {
+  login: () => string;
+  password: () => string;
+  join: () => string;
+  dashboard: () => string;
+  account: () => string;
+
+  // These are usually external links to the root domain, so we want to be
+  // able to set some tracking params.
+  terms?: (linkUtm?: LinkUtmParams) => string;
+  privacy?: (linkUtm?: LinkUtmParams) => string;
+  cookies?: (linkUtm?: LinkUtmParams) => string;
+};
+
+export type AppHrefs = Required<InputAppHrefs>;
+
+export function createHrefs<T extends InputAppHrefs>(params: {
+  /**
+   * Hrefs to be used for the given app. At minimum, you need to provide
+   * the core hrefs required by Appkit.
+   */
+  hrefs: T;
+
+  /**
+   * The function responsible for generating UTM tags. You should
+   * use the return value of {@link createUtm} unless you are doing something
+   * unusual.
+   */
+  utm: ReturnType<typeof createUtm>;
+}) {
+  const { utm, hrefs } = params;
+
+  return {
+    terms: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club/terms?${utm(linkUtm)}`,
+    privacy: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club/privacy?${utm(linkUtm)}`,
+    cookies: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club/cookies?${utm(linkUtm)}`,
+    itc: (linkUtm?: LinkUtmParams) =>
+      `https://indietabletop.club?${utm(linkUtm)}`,
+    fathom: () => `https://usefathom.com`,
+
+    ...hrefs,
+  };
+}

package/lib/idToDate.ts

@@ -0,0 +1,8 @@
+/**
+ * Given an doc id like `2025-01-01-some-name`, will return a date matching
+ * the starting portion of the id.
+ */
+export function idToDate(id: string, fallback: () => Date) {
+  const dateString = /^(?<date>\d{4}-\d{2}-\d{2})/.exec(id)?.groups?.date;
+  return dateString ? new Date(dateString) : fallback();
+}

package/lib/ids.ts

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

package/lib/index.ts

@@ -0,0 +1,75 @@
+// Components
+export * from "./account/AccountIcon.tsx";
+export * from "./account/CurrentUserFetcher.tsx";
+export * from "./account/JoinCard.tsx";
+export * from "./account/LoginCard.tsx";
+export * from "./account/PasswordResetCard.tsx";
+export * from "./AppConfig/AppConfig.tsx";
+export * from "./AuthCard/AuthCard.tsx";
+export * from "./CacheProvider.tsx";
+export * from "./DialogTrigger/index.tsx";
+export * from "./DocumentTitle/DocumentTitle.tsx";
+export * from "./ExternalLink.tsx";
+export * from "./form/FormSubmitButton.tsx";
+export * from "./form/SubmitErrorAlert.tsx";
+export * from "./FullscreenDismissBlocker.tsx";
+export * from "./IndieTabletopClubLogo.tsx";
+export * from "./IndieTabletopClubSymbol.tsx";
+export * from "./Letterhead/index.tsx";
+export * from "./LetterheadForm/index.tsx";
+export * from "./LoadingIndicator.tsx";
+export * from "./MiddotSeparated/MiddotSeparated.tsx";
+export * from "./ModalDialog/index.tsx";
+export * from "./QRCode/QRCode.tsx";
+export * from "./ReleaseInfo/index.tsx";
+export * from "./SafariCheck/SafariCheck.tsx";
+export * from "./ServiceWorkerHandler.tsx";
+export * from "./ShareButton/ShareButton.tsx";
+export * from "./SubscribeCard/SubscribeByEmailCard.tsx";
+export * from "./SubscribeCard/SubscribeByPledgeCard.tsx";
+export * from "./Sync/SyncIcon.tsx";
+export * from "./Sync/SyncLog.tsx";
+
+// Hooks
+export * from "./RulesetResolver.ts";
+export * from "./use-async-op.ts";
+export * from "./use-document-background-color.ts";
+export * from "./use-form.ts";
+export * from "./use-is-installed.ts";
+export * from "./use-media-query.ts";
+export * from "./use-reverting-state.ts";
+export * from "./use-scroll-restoration.ts";
+export * from "./useEnsureValue.ts";
+export * from "./useInvokeClient.ts";
+export * from "./useIsVisible.ts";
+
+// Utils
+export * from "./append-copy-to-text.ts";
+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 "./createSafeStorage.ts";
+export * from "./failureMessages.ts";
+export * from "./groupBy.ts";
+export * from "./HistoryState.ts";
+export * from "./hrefs.ts";
+export * from "./ids.ts";
+export * from "./idToDate.ts";
+export * from "./mailto.ts";
+export * from "./media.ts";
+export * from "./random.ts";
+export * from "./result/swr.ts";
+export * from "./sleep.ts";
+export * from "./structs.ts";
+export * from "./typeguards.ts";
+export * from "./types.ts";
+export * from "./unique.ts";
+export * from "./utm.ts";
+export * from "./validations.ts";
+
+// Other
+export * from "./EnumMapper.ts";
+export * from "./ModernIDB/index.ts";
+export * from "./store/index.tsx";

package/lib/internal.css.ts

@@ -0,0 +1,10 @@
+import { createVar, style } from "@vanilla-extract/css";
+import { bounce } from "./animations.css.ts";
+
+export const animationDelay = createVar();
+
+export const dot = style({
+  fill: "currentcolor",
+  opacity: 0.8,
+  animation: `${bounce} 2s ${animationDelay} infinite`,
+});

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

@@ -0,0 +1,50 @@
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
+ */
+
+export enum PrefersColorScheme {
+  LIGHT = "(prefers-color-scheme: light)",
+  DARK = "(prefers-color-scheme: dark)",
+}
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
+ */
+
+export enum PrefersReducedMotion {
+  NO_PREFERENCE = "(prefers-reduced-motion: no-preference)",
+  REDUCE = "(prefers-reduced-motion: reduce)",
+}
+
+export enum Hover {
+  NONE = "(hover: none)",
+
+  // Some Samsung phones incorrectly report that they have "hover" even though they
+  // do not. Adding the pointer query correctly filters these phones out.
+  HOVER = "(hover: hover) and (pointer: fine)",
+}
+
+export enum MediaType {
+  PRINT = "print",
+  SCREEN = "screen",
+}
+
+export enum MinHeight {
+  TALL = "(min-height: 40em)",
+}
+
+export enum MinWidth {
+  SMALL = "(min-width: 28em)",
+  MEDIUM = "(min-width: 50em)",
+  WIDE = "(min-width: 66em)",
+  X_WIDE = "(min-width: 80em)",
+  XX_WIDE = "(min-width: 140em)",
+}
+
+export enum DisplayMode {
+  STANDALONE = "(display-mode: standalone)",
+}
+
+export enum Pointer {
+  COARSE = "(pointer: coarse)",
+  FINE = "(pointer: fine)",
+}

package/lib/random.ts

@@ -0,0 +1,19 @@
+export function random(max: number) {
+  return Math.floor(Math.random() * max);
+}
+
+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/{dist/sleep.d.ts → lib/sleep.ts}

@@ -9,4 +9,6 @@
  * await sleep(2000) // Waits for 2s
  * ```
  */
-export declare function sleep(ms: number): Promise<unknown>;
+export function sleep(ms: number) {
+  return new Promise((r) => setTimeout(r, ms));
+}