@indietabletop/appkit 7.0.0-rc.5 → 7.0.0

package/lib/AppConfig/formatters.tsx

@@ -3,12 +3,14 @@ type EnglishCardinalRule = Extract<Intl.LDMLPluralRule, "one" | "other">;
 
 export type AppkitFormatters = ReturnType<typeof createFormatters>;
 
-// Currently, we only support localizing English variants. Not translating the
-// app into other locales.
+// Currently, we only support localizing English variants.
 type EnglishLocale = "en" | `en-${string}`;
 
 /**
  * Creates formatters that can be used across the app.
+ *
+ * These can be either used directly when imported, or via the `useAppConfig`
+ * hook when using inside of reusable components like e.g. the `SyncLog`.
  */
 export function createFormatters(locale: EnglishLocale) {
   const cardinalRules = new Intl.PluralRules(locale);

package/lib/RichText/style.css.ts

@@ -21,7 +21,6 @@ globalStyle(`${content} > :first-child`, {
 
 globalStyle(`${content} em`, {
   fontFamily: richTextTheme.emphasisFont,
-  textTransform: "lowercase",
 });
 
 globalStyle(`${content} :is(h1, h2, h3, h4, h5, h6)`, {

package/lib/Sync/SyncIcon.tsx

@@ -79,6 +79,28 @@ function Icon(props: { variant: SyncState }) {
   }
 }
 
+/**
+ * Given {@link SyncState}, will render the appropriate matching icon.
+ *
+ * You can use {@link syncTheme} to configure its colors. Generally, you would
+ * do that at the top level in a Vanilla Extract (.css.ts) file
+ * using `assignVars`.
+ *
+ * @example
+ * ```ts
+ * globalStyle(":root", {
+ *   vars: assignVars(syncTheme, {
+ *     idle: vars.color.blue,
+ *     inactive: vars.color.gray,
+ *     syncing: vars.color.blue,
+ *     error: vars.color.red,
+ *   }),
+ * )];
+ * ```
+ *
+ * It is also possible to use inline styles to set the vars if it's necessary.
+ */
+
 export function SyncIcon(props: {
   status: SyncState;
   title?: string;

package/lib/account/AccountIcon.tsx

@@ -2,6 +2,11 @@ import { useSyncState } from "../store/index.tsx";
 import { SyncIcon } from "../Sync/SyncIcon.tsx";
 import { accountIcon } from "./style.css.ts";
 
+/**
+ * Displays the user's icon, along with the sync status of the app.
+ *
+ * See {@link SyncIcon} to learn how to configure that component.
+ */
 export function AccountIcon(props: { imgSrc: string }) {
   const { imgSrc } = props;
   const syncState = useSyncState();

package/lib/async-op.ts

@@ -287,6 +287,11 @@ export function fromTryCatch<T>(callback: () => T) {
   }
 }
 
+/**
+ * Creates a Result from a promise-returning callback function.
+ *
+ * This is a great way to avoid try/catch statements inside of async functions.
+ */
 export async function fromPromise<T>(
   callback: () => Promise<T>,
 ): Promise<Success<T> | Failure<unknown>> {

package/lib/createStrictContext.ts

@@ -1,5 +1,17 @@
 import { createContext, use } from "react";
 
+/**
+ * Creates context values along with a pre-bound use(Context) hook that throws
+ * if context value is falsy.
+ *
+ * @param [debugName="Value"] Optionally, provide a debug name for this context
+ * value to be used within error messages if context value is nullish.
+ *
+ * @example
+ * ```ts
+ * export const [KnightContext, useKnight] = createStrictContext<Knight>("KnightContext");
+ * ```
+ */
 export function createStrictContext<T>(debugName: string = "Value") {
   const Context = createContext<T | null>(null);
 

package/lib/fathom.ts

@@ -4,12 +4,16 @@ declare global {
   }
 }
 
+/**
+ * Sends an arbitrary event to Fathom Analytics. Will log a warning if Fathom
+ * is not installed.
+ */
 export function trackEvent(event: string) {
   if (window.fathom) {
     window.fathom.trackEvent(event);
   } else {
     console.warn(
-      `Attempting to track event ${event}, but Fathom not installed.`,
+      `Attempting to track event ${event}, but Fathom is not installed.`,
     );
   }
 }

package/lib/store/index.tsx

@@ -61,7 +61,11 @@ export function useLastSuccessfulSyncTs() {
 export type SyncState = ReturnType<typeof useSyncState>;
 
 /**
- * Returns the app's current sync state.
+ * Returns the app's current {@link SyncState}.
+ *
+ * Note that this is not a property within the app's machine context, it is a
+ * derived value based on several factors.
+ *
  */
 export function useSyncState() {
   const { actorRef } = useAppMachineContext();

package/lib/useFetchJson.tsx

@@ -37,6 +37,10 @@ export async function fetchJson<T>(url: string): Promise<FetchJsonResult<T>> {
   return parsed;
 }
 
+/**
+ * Fetches a JSON document at provided URL. Note that the return type can be
+ * explicitly provided, but it is not validated at runtime — beware!
+ */
 export function useFetchJson<T = unknown>(
   url: string,
   config?: SWRConfiguration,
@@ -44,6 +48,11 @@ export function useFetchJson<T = unknown>(
   return useSWR<FetchJsonResult<T>>(url, fetchJson, config);
 }
 
+/**
+ * Fetches a JSON document at provided URL. Response will be wrapped in a
+ * Result. Note that the return type can be explicitly provided, but it is
+ * not validated at runtime — beware!
+ */
 export function useFetchJsonResult<T = unknown>(
   url: string,
   config?: SWRConfiguration,

package/lib/useGetProductStatus.ts

@@ -4,6 +4,7 @@ import { useClient } from "./AppConfig/AppConfig.tsx";
 import { Failure, Success } from "./async-op.ts";
 import { swrResponseToResult } from "./result/swr.ts";
 import { useCurrentUser } from "./store/index.tsx";
+import type { FailurePayload } from "./types.ts";
 
 function useGetOwnedProduct(productCode: string) {
   const client = useClient();
@@ -18,6 +19,28 @@ function useGetOwnedProduct(productCode: string) {
   return swrResponseToResult(swr);
 }
 
+export type ProductStatusSuccessPayload =
+  /**
+   * The user should authenticate before proceeding to checkout.
+   */
+  | { type: "AUTHENTICATE" }
+
+  /**
+   * The user can proceed to checkout.
+   */
+  | { type: "PURCHASE" }
+
+  /**
+   * The user already owns this product. The `downloadUrl` property should be
+   * used to let the user download their files.
+   */
+  | { type: "DOWNLOAD"; downloadUrl: string };
+
+/**
+ * Wraps ITC client's getOwnedProduct call and maps it's responses into
+ * {@link ProductStatusSuccessPayload} which is more appropriate for product
+ * purchase pages.
+ */
 export function useGetProductStatus(productCode: string) {
   const result = useGetOwnedProduct(productCode);
   const currentUser = useCurrentUser();
@@ -33,11 +56,15 @@ export function useGetProductStatus(productCode: string) {
       // The no currentUser case is possible in case the user is logged into ITC
       // via a domain-wide cookie, but they have not yet logged in this app.
       if (failure.code === 401 || !currentUser) {
-        return new Success({ type: "AUTHENTICATE" as const });
+        return new Success<ProductStatusSuccessPayload>({
+          type: "AUTHENTICATE",
+        });
       }
 
       if (failure.code === 403) {
-        return new Success({ type: "PURCHASE" as const });
+        return new Success<ProductStatusSuccessPayload>({
+          type: "PURCHASE",
+        });
       }
     }
 
@@ -49,8 +76,13 @@ export function useGetProductStatus(productCode: string) {
   // if a product link fails to generate.
   const { downloadUrl } = result.value;
   if (!downloadUrl) {
-    return new Failure({ type: "UNKNOWN_ERROR" as const });
+    return new Failure<FailurePayload>({
+      type: "UNKNOWN_ERROR",
+    });
   }
 
-  return new Success({ type: "DOWNLOAD" as const, downloadUrl });
+  return new Success<ProductStatusSuccessPayload>({
+    type: "DOWNLOAD",
+    downloadUrl,
+  });
 }

package/package.json

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