@indietabletop/appkit 6.1.6 → 7.0.0-rc.0

package/lib/AppConfig/AppConfig.tsx

@@ -1,6 +1,10 @@
-import { createContext, type ReactNode, useContext } from "react";
+import { type ReactNode } from "react";
 import type { IndieTabletopClient } from "../client.ts";
+import { createStrictContext } from "../createStrictContext.ts";
 import type { AppHrefs } from "../hrefs.ts";
+import type { ModernIDB } from "../ModernIDB/index.ts";
+import type { DatabaseAppMachineMethods } from "../store/index.tsx";
+import type { AppkitFormatters } from "./formatters.tsx";
 
 export type AppConfig = {
   app: {
@@ -16,15 +20,56 @@ export type AppConfig = {
      */
     icon: string;
   };
+
+  /**
+   * Usually the value of `import.meta.env.DEV` when using Vite.
+   *
+   * This is used primarily by the DocumentTitle component, to make it clear
+   * which browser tab is in DEV mode.
+   */
   isDev: boolean;
+
+  /**
+   * A reference to the ITC client.
+   *
+   * This is necessary in order for prefab components to make thier own calls.
+   */
   client: IndieTabletopClient;
+
+  /**
+   * A hrefs configuration.
+   *
+   * This is necessary so that prefab components can navigate around the app
+   * without hard-coded values.
+   */
   hrefs: AppHrefs;
+
+  /**
+   * Customize input placeholders so that they fit their given app thematically.
+   */
   placeholders: {
     email: string;
   };
+
+  /**
+   * Formatters accessible to prefab components.
+   *
+   * You might want to create different formatters based on the app's locale.
+   */
+  fmt: AppkitFormatters;
+
+  database: ModernIDB<any, any> & DatabaseAppMachineMethods;
 };
 
-const AppConfigContext = createContext<AppConfig | null>(null);
+const [AppConfigContext, useAppConfig] = createStrictContext<AppConfig>();
+
+export { createFormatters } from "./formatters.tsx";
+
+export { useAppConfig };
+
+export function useClient() {
+  return useAppConfig().client;
+}
 
 export function AppConfigProvider(props: {
   config: AppConfig;
@@ -33,29 +78,3 @@ export function AppConfigProvider(props: {
   const { config, children } = props;
   return <AppConfigContext value={config}>{children}</AppConfigContext>;
 }
-
-export function useAppConfig() {
-  const config = useContext(AppConfigContext);
-
-  if (!config) {
-    throw new Error(
-      `Attempting to retrieve app config, but none was found within context. ` +
-        `Make sure that AppConfigProvider is used in the component hierarchy.`,
-    );
-  }
-
-  return config;
-}
-
-export function useClient() {
-  const config = useContext(AppConfigContext);
-
-  if (!config?.client) {
-    throw new Error(
-      `Attempting to retrieve ITC client, but none was found within context. ` +
-        `Make sure that AppConfigProvider is used in the component hierarchy.`,
-    );
-  }
-
-  return config.client;
-}

package/lib/AppConfig/formatters.tsx

@@ -0,0 +1,43 @@
+// English only uses "one" and "other"
+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.
+type EnglishLocale = "en" | `en-${string}`;
+
+/**
+ * Creates formatters that can be used across the app.
+ */
+export function createFormatters(locale: EnglishLocale) {
+  const cardinalRules = new Intl.PluralRules(locale);
+
+  const dateTimeFmt = new Intl.DateTimeFormat(locale);
+
+  const conjunctionFmt = new Intl.ListFormat(locale, {
+    style: "long",
+    type: "conjunction",
+  });
+
+  const disjunctionFmt = new Intl.ListFormat(locale, {
+    style: "long",
+    type: "disjunction",
+  });
+
+  return {
+    plural(count: number, rules: Record<EnglishCardinalRule, string>) {
+      const tag = cardinalRules.select(count) as EnglishCardinalRule;
+      return rules[tag].replace("#", count.toString());
+    },
+    dateTime(date: Date | string | number) {
+      return dateTimeFmt.format(new Date(date));
+    },
+    conjunction(items: string[]) {
+      return conjunctionFmt.format(items);
+    },
+    disjunction(items: string[]) {
+      return disjunctionFmt.format(items);
+    },
+  };
+}

package/lib/CacheProvider.tsx

@@ -0,0 +1,20 @@
+import { useCurrentUser } from "@indietabletop/appkit";
+import { useMemo, type ReactNode } from "react";
+import { SWRConfig } from "swr";
+
+/**
+ * Links SWR cache to the current user. This makes sure that if a user logs
+ * out and continues using the app in an anonymous state, they will not be
+ * shown stale data.
+ */
+export function CacheProvider(props: { children: ReactNode }) {
+  const currentUser = useCurrentUser();
+  const cacheKey = currentUser ? currentUser.id : "anonymous";
+
+  const provider = useMemo(() => {
+    console.info(`Using SWR cache for "${cacheKey}"`);
+    return () => new Map();
+  }, [cacheKey]);
+
+  return <SWRConfig value={{ provider }}>{props.children}</SWRConfig>;
+}

package/lib/Sync/SyncIcon.stories.tsx

@@ -0,0 +1,67 @@
+import { assignInlineVars } from "@vanilla-extract/dynamic";
+import preview from "../../.storybook/preview.tsx";
+import { SyncIcon } from "./SyncIcon.tsx";
+import { syncTheme } from "./style.css.ts";
+
+const meta = preview.meta({
+  title: "Components/SyncIcon",
+  component: SyncIcon,
+});
+
+export const Inactive = meta.story({
+  args: {
+    status: "INACTIVE",
+  },
+});
+
+export const Authenticating = meta.story({
+  args: {
+    status: "AUTHENTICATING",
+  },
+});
+
+export const Idle = meta.story({
+  args: {
+    status: "IDLE",
+  },
+});
+
+export const Error = meta.story({
+  args: {
+    status: "ERROR",
+  },
+});
+
+export const Syncing = meta.story({
+  args: {
+    status: "SYNCING",
+  },
+});
+
+export const Waiting = meta.story({
+  args: {
+    status: "WAITING",
+  },
+});
+
+export const Overrides = meta.story({
+  args: {
+    status: "AUTHENTICATING",
+  },
+  decorators: [
+    (Story) => {
+      return (
+        <div
+          style={assignInlineVars(syncTheme, {
+            idle: "black",
+            inactive: "black",
+            syncing: "black",
+            error: "black",
+          })}
+        >
+          <Story />
+        </div>
+      );
+    },
+  ],
+});

package/lib/Sync/SyncIcon.tsx

@@ -0,0 +1,102 @@
+import { cx } from "../class-names.ts";
+import type { SyncState } from "../store/index.tsx";
+import { icon, syncTheme } from "./style.css.ts";
+
+export { syncTheme };
+
+function Icon(props: { variant: SyncState }) {
+  switch (props.variant) {
+    case "IDLE": {
+      return (
+        <g className={icon.group}>
+          <circle className={icon.idle} />
+
+          <path
+            d="M9.0026 14L16.0737 6.92893L14.6595 5.51472L9.0026 11.1716L6.17421 8.3431L4.75999 9.7574L9.0026 14Z"
+            className={icon.shape}
+          />
+        </g>
+      );
+    }
+
+    case "AUTHENTICATING":
+    case "WAITING": {
+      return (
+        <g className={icon.group}>
+          <circle className={icon.syncing} />
+
+          <g>
+            <circle cx="14" cy="10" className={icon.bounce} />
+            <circle cx="10" cy="10" className={icon.bounce} />
+            <circle cx="6" cy="10" className={icon.bounce} />
+          </g>
+        </g>
+      );
+    }
+
+    case "SYNCING": {
+      return (
+        <g className={icon.group}>
+          <circle className={icon.idle} />
+
+          <path
+            d="M14.8201 15.0761C16.1628 13.8007 17 11.9981 17 10C17 6.13401 13.866 3 10 3C8.9391 3 7.9334 3.23599 7.03241 3.65834L8.0072 5.41292C8.6177 5.14729 9.2917 5 10 5C12.7614 5 15 7.23858 15 10H12L14.8201 15.0761ZM12.9676 16.3417L11.9928 14.5871C11.3823 14.8527 10.7083 15 10 15C7.23858 15 5 12.7614 5 10H8L5.17993 4.92387C3.83719 6.19929 3 8.0019 3 10C3 13.866 6.13401 17 10 17C11.0609 17 12.0666 16.764 12.9676 16.3417Z"
+            className={icon.shape}
+          />
+        </g>
+      );
+    }
+
+    case "ERROR": {
+      return (
+        <g className={icon.group}>
+          <circle className={icon.error} />
+
+          <path
+            d="M10 8.58579L7.17157 5.75735L5.75736 7.17156L8.5858 9.99999L5.75736 12.8284L7.17157 14.2426L10 11.4142L12.8284 14.2426L14.2426 12.8284L11.4142 9.99999L14.2426 7.17156L12.8284 5.75735L10 8.58579Z"
+            className={icon.shape}
+          />
+        </g>
+      );
+    }
+
+    case "INACTIVE": {
+      return (
+        <g className={icon.group}>
+          <circle className={icon.inactive} />
+
+          <path
+            d="M9 13V15H11V13H9ZM11 11.3551C12.4457 10.9248 13.5 9.5855 13.5 8C13.5 6.067 11.933 4.5 10 4.5C8.302 4.5 6.88637 5.70919 6.56731 7.31346L8.5288 7.70577C8.6656 7.01823 9.2723 6.5 10 6.5C10.8284 6.5 11.5 7.17157 11.5 8C11.5 8.8284 10.8284 9.5 10 9.5C9.4477 9.5 9 9.9477 9 10.5V12H11V11.3551Z"
+            className={icon.shape}
+          />
+        </g>
+      );
+    }
+
+    default: {
+      return null;
+    }
+  }
+}
+
+export function SyncIcon(props: {
+  status: SyncState;
+  title?: string;
+  className?: string;
+}) {
+  const { status, title } = props;
+
+  return (
+    <svg
+      {...cx(props, icon.container({ rotate: status === "SYNCING" }))}
+      width="20px"
+      height="20px"
+      viewBox="0 0 20 20"
+      version="1.1"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <title>{title}</title>
+      <Icon variant={status} />
+    </svg>
+  );
+}

package/lib/Sync/SyncLog.tsx

@@ -0,0 +1,222 @@
+import {
+  Disclosure,
+  DisclosureContent,
+  DisclosureProvider,
+} from "@ariakit/react";
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
+import {
+  useLastSuccessfulSyncTs,
+  useSyncLog,
+  useSyncState,
+  type SyncState,
+} from "../store/index.tsx";
+import type { SyncAttempt } from "../store/types.ts";
+import type { FailurePayload } from "../types.ts";
+import { log } from "./style.css.ts";
+import { SyncIcon } from "./SyncIcon.tsx";
+
+function SyncActionSuccess(props: {
+  heading: string;
+  items: { id: string; name: string; deleted: boolean }[];
+}) {
+  const { heading, items } = props;
+
+  return (
+    <div>
+      <div>
+        <strong>{heading}</strong>
+      </div>
+
+      <div style={{ marginBlockStart: "0.25rem" }}>
+        {items.length > 0 ?
+          <ul
+            style={{
+              listStyle: "initial",
+              paddingInlineStart: "1.5rem",
+            }}
+          >
+            {items.map((item) => {
+              const name = item.name || "Unnamed item";
+
+              if (item.deleted) {
+                return (
+                  <li key={item.id}>
+                    Synced deletion of {name} (<code>{item.id}</code>)
+                  </li>
+                );
+              }
+
+              return (
+                <li key={item.id}>
+                  Synced {name} (<code>{item.id}</code>)
+                </li>
+              );
+            })}
+          </ul>
+        : <div style={{ opacity: 0.5 }}>
+            <em>Everything up to date.</em>
+          </div>
+        }
+      </div>
+    </div>
+  );
+}
+
+const failureToLabel: Record<FailurePayload["type"], string> = {
+  NETWORK_ERROR: "A network error occurred.",
+  API_ERROR: "Server responded with error ",
+  UNKNOWN_ERROR: "An unexpected error ocurred. Try restarting the app.",
+  VALIDATION_ERROR: "Data validation error occurred. Try restarting the app.",
+};
+
+function SyncActionFailure(props: {
+  heading: string;
+  failure: FailurePayload;
+}) {
+  const { heading, failure } = props;
+  const label = failureToLabel[failure.type];
+  return (
+    <div>
+      {heading}
+      {": "}
+      {failure.type === "API_ERROR" ?
+        ` ${label} ${failure.code}.`
+      : ` ${label}`}
+    </div>
+  );
+}
+
+const syncStateToLabel: Record<SyncState, string> = {
+  WAITING: "Waiting for additional changes...",
+  IDLE: "Sync enabled. Waiting for changes.",
+  AUTHENTICATING: "Verifying identity...",
+  ERROR: "Last sync unsuccessful. Waiting for changes.",
+  INACTIVE: "Sync not enabled. Log in or join to enable.",
+  SYNCING: "Syncing...",
+};
+
+export function SyncLogList(props: {
+  syncState: SyncState;
+  syncLog: SyncAttempt[];
+  lastSuccessfulSyncTs: number | null;
+}) {
+  const { syncLog, syncState, lastSuccessfulSyncTs } = props;
+  const { fmt } = useAppConfig();
+
+  return (
+    <div>
+      <div className={log.item}>
+        <SyncIcon status={syncState} />
+
+        <div>
+          <div>{syncStateToLabel[syncState]}</div>
+
+          <div className={log.itemTimestamp}>
+            {lastSuccessfulSyncTs ?
+              `Last successful sync at: ${fmt.dateTime(lastSuccessfulSyncTs)}`
+            : "Not synced yet."}
+          </div>
+        </div>
+      </div>
+
+      {syncLog.map((logItem) => {
+        const isFailure =
+          logItem.pull?.type === "FAILURE" || logItem.push?.type == "FAILURE";
+
+        const itemsSynced =
+          (logItem.pull?.type === "SUCCESS" ?
+            logItem.pull.value.pulled.length
+          : 0) +
+          (logItem.push?.type === "SUCCESS" ?
+            logItem.push.value.pushed.length + logItem.push.value.pulled.length
+          : 0);
+
+        return (
+          <DisclosureProvider key={logItem.startedTs}>
+            <Disclosure className={log.item}>
+              {isFailure ?
+                <>
+                  <SyncIcon status="ERROR" />
+                  <div>
+                    Sync attempt failed
+                    <div className={log.itemTimestamp}>
+                      {fmt.dateTime(logItem.startedTs)}
+                    </div>
+                  </div>
+                </>
+              : <>
+                  <SyncIcon status="IDLE" />
+                  <div>
+                    {"Sync successful. "}
+                    {itemsSynced === 0 ?
+                      "Everything up to date."
+                    : fmt.plural(itemsSynced, {
+                        one: "1 item synced.",
+                        other: "# items synced.",
+                      })
+                    }
+                    <div className={log.itemTimestamp}>
+                      {fmt.dateTime(logItem.startedTs)}
+                    </div>
+                  </div>
+                </>
+              }
+            </Disclosure>
+
+            <DisclosureContent className={log.disclosureContent}>
+              {logItem.pull && (
+                <>
+                  {logItem.pull.type === "SUCCESS" ?
+                    <SyncActionSuccess
+                      heading="Pull successful"
+                      items={logItem.pull.value.pulled}
+                    />
+                  : <SyncActionFailure
+                      heading="Pull failed"
+                      failure={logItem.pull.failure}
+                    />
+                  }
+                </>
+              )}
+
+              {logItem.push && (
+                <>
+                  {logItem.push.type === "SUCCESS" ?
+                    <>
+                      <SyncActionSuccess
+                        heading="Push successful"
+                        items={logItem.push.value.pushed}
+                      />
+                      <SyncActionSuccess
+                        heading="Patch successful"
+                        items={logItem.push.value.pulled}
+                      />
+                    </>
+                  : <SyncActionFailure
+                      heading="Push failed"
+                      failure={logItem.push.failure}
+                    />
+                  }
+                </>
+              )}
+            </DisclosureContent>
+          </DisclosureProvider>
+        );
+      })}
+    </div>
+  );
+}
+
+export function SyncLog() {
+  const syncState = useSyncState();
+  const syncLog = useSyncLog();
+  const lastSuccessfulSyncTs = useLastSuccessfulSyncTs();
+
+  return (
+    <SyncLogList
+      syncState={syncState}
+      syncLog={syncLog}
+      lastSuccessfulSyncTs={lastSuccessfulSyncTs}
+    />
+  );
+}

package/lib/Sync/SyncLogList.stories.tsx

@@ -0,0 +1,219 @@
+import preview from "../../.storybook/preview.tsx";
+import { Failure, Success } from "../async-op.ts";
+import { SyncLogList } from "./SyncLog.tsx";
+
+const meta = preview.meta({
+  title: "Components/SyncLogList",
+  component: SyncLogList,
+});
+
+export const Inactive = meta.story({
+  args: {
+    syncState: "INACTIVE",
+    lastSuccessfulSyncTs: null,
+    syncLog: [],
+  },
+});
+
+export const Syncing = meta.story({
+  args: {
+    syncState: "SYNCING",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: null,
+        push: new Success({
+          pushed: [
+            {
+              id: "123",
+              name: "Test Item",
+              updatedTs: 1773753718052,
+              deleted: false,
+            },
+          ],
+          pulled: [],
+        }),
+      },
+    ],
+  },
+});
+
+export const Idle = meta.story({
+  args: {
+    syncState: "IDLE",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [],
+  },
+});
+
+export const Waiting = meta.story({
+  args: {
+    syncState: "WAITING",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [],
+  },
+});
+
+export const Authenticating = meta.story({
+  args: {
+    syncState: "AUTHENTICATING",
+    lastSuccessfulSyncTs: null,
+    syncLog: [],
+  },
+});
+
+export const Error = meta.story({
+  args: {
+    syncState: "ERROR",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: null,
+        push: new Failure({ type: "API_ERROR" as const, code: 500 }),
+      },
+    ],
+  },
+});
+
+export const SuccessfulPullAndPush = meta.story({
+  args: {
+    syncState: "IDLE",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: new Success({
+          pulled: [
+            {
+              id: "p1",
+              name: "Pulled Item",
+              updatedTs: 1773753718052,
+              deleted: false,
+            },
+          ],
+        }),
+        push: new Success({
+          pushed: [
+            {
+              id: "s1",
+              name: "Pushed Item",
+              updatedTs: 1773753718052,
+              deleted: false,
+            },
+          ],
+          pulled: [
+            {
+              id: "s2",
+              name: "Patch Item",
+              updatedTs: 1773753718052,
+              deleted: false,
+            },
+          ],
+        }),
+      },
+    ],
+  },
+});
+
+export const AllUpToDate = meta.story({
+  args: {
+    syncState: "IDLE",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: new Success({ pulled: [] }),
+        push: new Success({ pushed: [], pulled: [] }),
+      },
+    ],
+  },
+});
+
+export const PullFailure = meta.story({
+  args: {
+    syncState: "ERROR",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: new Failure({ type: "NETWORK_ERROR" as const }),
+        push: null,
+      },
+    ],
+  },
+});
+
+export const DeletedAndUnnamedItems = meta.story({
+  args: {
+    syncState: "IDLE",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: null,
+        push: new Success({
+          pushed: [
+            {
+              id: "d1",
+              name: "Removed Campaign",
+              updatedTs: 1773753718052,
+              deleted: true,
+            },
+            {
+              id: "d2",
+              name: "",
+              updatedTs: 1773753718052,
+              deleted: false,
+            },
+          ],
+          pulled: [],
+        }),
+      },
+    ],
+  },
+});
+
+export const MultipleSyncEntries = meta.story({
+  args: {
+    syncState: "IDLE",
+    lastSuccessfulSyncTs: 1773753718052,
+    syncLog: [
+      {
+        startedTs: 1773753718052,
+        pull: new Success({ pulled: [] }),
+        push: new Success({ pushed: [], pulled: [] }),
+      },
+      {
+        startedTs: 1773753608052,
+        pull: new Success({
+          pulled: [
+            {
+              id: "m1",
+              name: "Synced Item",
+              updatedTs: 1773753608052,
+              deleted: false,
+            },
+          ],
+        }),
+        push: new Success({
+          pushed: [
+            {
+              id: "m2",
+              name: "Pushed Item",
+              updatedTs: 1773753608052,
+              deleted: false,
+            },
+          ],
+          pulled: [],
+        }),
+      },
+      {
+        startedTs: 1773753508052,
+        pull: new Failure({ type: "NETWORK_ERROR" as const }),
+        push: null,
+      },
+    ],
+  },
+});

package/lib/Sync/style.css.ts

@@ -0,0 +1,126 @@
+import {
+  createThemeContract,
+  fallbackVar,
+  keyframes,
+  style,
+} from "@vanilla-extract/css";
+import { recipe } from "@vanilla-extract/recipes";
+
+const bounce = keyframes({
+  "0%": { translate: "0 0" },
+  "25%": { translate: "0 -10%" },
+  "50%": { translate: "0 0" },
+  "100%": { translate: "0 0" },
+});
+
+const rotation = keyframes({
+  from: { transform: `rotate(0deg)` },
+  to: { transform: `rotate(360deg)` },
+});
+
+export const syncTheme = createThemeContract({
+  idle: null,
+  inactive: null,
+  syncing: null,
+  error: null,
+});
+
+const backplate = style({
+  cx: 10,
+  cy: 10,
+  r: 10,
+});
+
+export const icon = {
+  container: recipe({
+    base: {},
+
+    variants: {
+      rotate: {
+        true: {
+          animation: `${rotation} linear 2s both infinite`,
+        },
+      },
+    },
+  }),
+
+  group: style({
+    stroke: "none",
+    fill: "none",
+    fillRule: "evenodd",
+  }),
+
+  shape: style({
+    fill: "white",
+  }),
+
+  idle: style([
+    backplate,
+    {
+      fill: fallbackVar(syncTheme.idle, "green"),
+    },
+  ]),
+
+  inactive: style([
+    backplate,
+    {
+      fill: fallbackVar(syncTheme.inactive, "blue"),
+    },
+  ]),
+
+  error: style([
+    backplate,
+    {
+      fill: fallbackVar(syncTheme.error, "red"),
+    },
+  ]),
+
+  syncing: style([
+    backplate,
+    {
+      fill: fallbackVar(syncTheme.syncing, "purple"),
+    },
+  ]),
+
+  bounce: style({
+    vars: {
+      "--duration": "1.5s",
+    },
+
+    animation: `${bounce} var(--duration) both infinite`,
+    r: 1,
+    fill: "white",
+
+    selectors: {
+      "&:nth-child(2)": {
+        animationDelay: "calc(var(--duration) * -0.1)",
+      },
+      "&:nth-child(3)": {
+        animationDelay: "calc(var(--duration) * -0.2)",
+      },
+    },
+  }),
+};
+
+export const log = {
+  item: style({
+    display: "grid",
+    gridTemplateColumns: "auto minmax(0, 1fr)",
+    alignItems: "center",
+    gap: "1rem",
+    padding: "1rem 0",
+    textAlign: "start",
+    borderBlockStart: "1px solid hsl(0 0% 90%)",
+    inlineSize: "100%",
+  }),
+
+  disclosureContent: style({
+    display: "grid",
+    gap: "1rem",
+    borderInlineStart: "1px solid hsl(0 0% 90%)",
+    paddingInlineStart: "1rem",
+    marginBlockEnd: "1.5rem",
+  }),
+
+  itemTimestamp: style({ opacity: 0.5 }),
+};

package/lib/account/AccountIcon.tsx

@@ -0,0 +1,15 @@
+import { useSyncState } from "../store/index.tsx";
+import { SyncIcon } from "../Sync/SyncIcon.tsx";
+import { accountIcon } from "./style.css.ts";
+
+export function AccountIcon(props: { imgSrc: string }) {
+  const { imgSrc } = props;
+  const syncState = useSyncState();
+
+  return (
+    <div className={accountIcon.container}>
+      <SyncIcon status={syncState} className={accountIcon.syncIcon} />
+      <img src={imgSrc} alt="" className={accountIcon.image} />
+    </div>
+  );
+}

package/lib/account/iconMask.svg

@@ -0,0 +1,3 @@
+<svg width="56" height="56" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M28 0C43.464 0 56 12.536 56 28C56 31.3019 55.4265 34.4697 54.377 37.4111C52.2143 35.3015 49.2598 34 46 34C39.3726 34 34 39.3726 34 46C34 49.2598 35.3015 52.2143 37.4111 54.377C34.4697 55.4265 31.3019 56 28 56C12.536 56 0 43.464 0 28C0 12.536 12.536 0 28 0Z" fill="white"/>
+</svg>

package/lib/account/style.css.ts

@@ -1,5 +1,29 @@
 import { style } from "@vanilla-extract/css";
 import { Hover, MinWidth } from "../media.ts";
+import iconMask from "./iconMask.svg";
+
+export const accountIcon = {
+  container: style({
+    position: "relative",
+    marginInline: "auto",
+
+    inlineSize: "56px",
+    blockSize: "56px",
+  }),
+
+  syncIcon: style({
+    position: "absolute",
+    right: "0",
+    bottom: "0",
+  }),
+
+  image: style({
+    mask: `url("${iconMask}") no-repeat`,
+    inlineSize: "100%",
+    blockSize: "100%",
+    borderRadius: "50%",
+  }),
+};
 
 export const page = style({
   backgroundColor: "white",

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

@@ -1,10 +1,12 @@
 // 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";
@@ -25,6 +27,8 @@ 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";

package/lib/store/index.tsx

@@ -1,54 +1,109 @@
 import type { UserGameData } from "@indietabletop/types";
-import { createActorContext } from "@xstate/react";
-import { createContext, useContext, useMemo, type ReactNode } from "react";
-import { fromCallback, fromPromise } from "xstate";
+import { useActorRef, useSelector } from "@xstate/react";
+import { createContext, useMemo, type ReactNode } from "react";
+import { Actor, fromCallback, fromPromise } from "xstate";
+import { useAppConfig } from "../AppConfig/AppConfig.tsx";
 import { Failure, Success } from "../async-op.ts";
 import type { GameCode, IndieTabletopClient } from "../client.ts";
+import { createStrictContext } from "../createStrictContext.ts";
 import type { ModernIDB } from "../ModernIDB/ModernIDB.ts";
 import type { ModernIDBIndexes, ModernIDBSchema } from "../ModernIDB/types.ts";
 import type { CurrentUser } from "../types.ts";
 import {
   machine,
+  type AppMachine,
   type PullChangesInput,
   type PushChangesInput,
 } from "./store.ts";
 import type { MachineEvent, PullResult, PushResult } from "./types.ts";
 import { toSyncedItems } from "./utils.ts";
 
-export type AppActions = {
-  clientLogout: (params: { serverUser: CurrentUser }) => Promise<void>;
-  serverLogout: () => Promise<void>;
-  logout: () => Promise<void>;
-  push: () => void;
-  pull: () => void;
-};
+export type AppActions = ReturnType<typeof useCreateActions>;
 
-export const AppActionsContext = createContext<null | AppActions>(null);
+type AppActor = Actor<AppMachine>;
 
-const {
-  Provider: InternalMachineProvider,
-  useSelector,
-  useActorRef,
-} = createActorContext(machine);
+export const [AppMachineContext, useAppMachineContext] = createStrictContext<{
+  actorRef: AppActor;
+  actions: AppActions;
+}>();
 
-export { useActorRef, useSelector };
+export const AppActionsContext = createContext<null | AppActions>(null);
 
 export function useCurrentUser() {
-  return useSelector((s) => s.context.currentUser);
+  const { actorRef } = useAppMachineContext();
+  return useSelector(actorRef, (s) => s.context.currentUser);
 }
 
 export function useSessionInfo() {
-  return useSelector((s) => s.context.sessionInfo);
+  const { actorRef } = useAppMachineContext();
+  return useSelector(actorRef, (s) => s.context.sessionInfo);
 }
 
-export function useAppActions() {
-  const actions = useContext(AppActionsContext);
+/**
+ * Checks if the app is in an authenticated state.
+ *
+ * This means that the user that might have been provided in local storage
+ * has been checked with the server and they a) have a valid session and
+ * b) are matching the current user.
+ */
+export function useIsAuthenticated() {
+  const { actorRef } = useAppMachineContext();
+  return useSelector(actorRef, (s) => s.matches("authenticated"));
+}
+
+export function useSyncLog() {
+  const { actorRef } = useAppMachineContext();
+  return useSelector(actorRef, (s) => s.context.syncLog);
+}
+
+export function useLastSuccessfulSyncTs() {
+  const { actorRef } = useAppMachineContext();
+  return useSelector(actorRef, (s) => s.context.lastSuccessfulSyncTs);
+}
+
+export type SyncState = ReturnType<typeof useSyncState>;
+
+/**
+ * Returns the app's current sync state.
+ */
+export function useSyncState() {
+  const { actorRef } = useAppMachineContext();
+  return useSelector(actorRef, (s) => {
+    switch (true) {
+      case s.matches({ authenticated: { sync: "syncing" } }): {
+        return "SYNCING";
+      }
+
+      case s.matches({ authenticated: { sync: "waiting" } }): {
+        return "WAITING";
+      }
+
+      case s.matches({ authenticated: { sync: "idle" } }): {
+        const lastSync = s.context.syncLog[0];
+
+        if (
+          lastSync?.pull?.type === "FAILURE" ||
+          lastSync?.push?.type === "FAILURE"
+        ) {
+          return "ERROR";
+        }
 
-  if (!actions) {
-    throw new Error(`Missing context value for app actions.`);
-  }
+        return "IDLE";
+      }
+
+      case s.matches("unauthenticated") && !!s.context.currentUser: {
+        return "AUTHENTICATING";
+      }
+
+      default: {
+        return "INACTIVE";
+      }
+    }
+  });
+}
 
-  return actions;
+export function useAppActions() {
+  return useAppMachineContext().actions;
 }
 
 export type DatabaseAppMachineMethods = {
@@ -62,7 +117,7 @@ export type DatabaseAppMachineMethods = {
   clearAll(): Promise<Success<string> | Failure<string>>;
 };
 
-export function createAppMachineProvider<
+export function createMachine<
   Schema extends ModernIDBSchema,
   Indexes extends ModernIDBIndexes<Schema>,
 >(options: {
@@ -180,62 +235,60 @@ export function createAppMachineProvider<
     },
   );
 
-  // Bound provider components
-
-  function AppActionsProvider(props: { children: ReactNode }) {
-    const { children } = props;
-    const app = useActorRef();
-
-    const actions: AppActions = useMemo(() => {
-      async function clientLogout(params: { serverUser: CurrentUser }) {
-        await database.clearAll();
-        app.send({ type: "serverUser", ...params });
-
-        // Get new session info
-        await client.refreshTokens();
-      }
-
-      async function serverLogout() {
-        await client.logout();
-      }
-
-      async function logout() {
-        await client.logout();
-        await database.clearAll();
-        app.send({ type: "reset" });
-      }
+  return machine.provide({
+    actors: { auth, sync, pullChanges, pushChanges },
+  });
+}
 
-      function push() {
-        app.send({ type: "push" });
-      }
+function useCreateActions(app: AppActor) {
+  const { database, client } = useAppConfig();
+
+  return useMemo(() => {
+    async function clientLogout(params: { serverUser: CurrentUser }) {
+      await database.clearAll();
+      app.send({ type: "serverUser", ...params });
+
+      // Get new session info
+      await client.refreshTokens();
+    }
+
+    async function serverLogout() {
+      await client.logout();
+    }
+
+    async function logout() {
+      await client.logout();
+      await database.clearAll();
+      app.send({ type: "reset" });
+    }
+
+    function push() {
+      app.send({ type: "push" });
+    }
+
+    function pull() {
+      app.send({ type: "pull" });
+    }
+
+    return {
+      pull,
+      push,
+      logout,
+      serverLogout,
+      clientLogout,
+    };
+  }, [app]);
+}
 
-      function pull() {
-        app.send({ type: "pull" });
-      }
+export function AppMachineProvider(props: {
+  value: typeof machine;
+  children: ReactNode;
+}) {
+  const actorRef = useActorRef(props.value);
+  const actions = useCreateActions(actorRef);
+  const context = useMemo(() => ({ actorRef, actions }), [actorRef, actions]);
 
-      return {
-        pull,
-        push,
-        logout,
-        serverLogout,
-        clientLogout,
-      };
-    }, [app]);
-
-    return <AppActionsContext value={actions}>{children}</AppActionsContext>;
-  }
-
-  return function AppMachineProvider(props: { children: ReactNode }) {
-    const { children } = props;
-
-    return (
-      <InternalMachineProvider
-        logic={machine.provide({
-          actors: { auth, sync, pullChanges, pushChanges },
-        })}
-      >
-        <AppActionsProvider>{children}</AppActionsProvider>
-      </InternalMachineProvider>
-    );
-  };
+  return (
+    <AppMachineContext value={context}>{props.children}</AppMachineContext>
+  );
 }

package/lib/store/store.ts

@@ -150,8 +150,9 @@ const config = setup({
     }),
 
     patchSessionInfo: assign(({ context }, newSessionInfo: SessionInfo) => {
-      const sessionInfo = context.sessionInfo
-        ? { ...context.sessionInfo, expiresTs: newSessionInfo.expiresTs }
+      const sessionInfo =
+        context.sessionInfo ?
+          { ...context.sessionInfo, expiresTs: newSessionInfo.expiresTs }
         : newSessionInfo;
 
       safeStorage.setItem("sessionInfo", sessionInfo);
@@ -225,6 +226,8 @@ const config = setup({
   },
 });
 
+export type AppMachine = typeof machine;
+
 export const machine = config.createMachine({
   /** @xstate-layout N4IgpgJg5mDOIC5QEMAOqDEAnOYAuA2gAwC6ioqA9rAJZ42UB25IAHogLQBMRAbAHQBOQbwCMggOy8ALES7DRAGhABPTvIn8AzAA5B0rdN4BWCRKKDRvAL7XlaVPwCujZE7wALMI3oBjZHiQGL5OWDg+AKqwYFjEZEggVLT0TCzsCEZc-FyiXHqiOtJcvLwSymoI3Fqi-LkiIjkSIrIStvbozq7uXj40-oEQwaHheFExBKLxFNR0DMwJ6dJL-GJ1gkTSwubS5Yj6mjrG602F0ietdiAOnW6e3n4BQSFh92OxXFOJMynzoIs6uwQljaVw6LluPQeAww0SwADcYm84iwkrNUgtEHkiICOKI8SDrhD7n1HoNniMkaQUd85mlELkctktLxDkQdDoJFYuGVVPTREZaoZjMKdNzRFILu1HETev0nsNXrCJp9UT86QhRVkiHVjDIiHwSlxAXiBaJDEVqkRzNVpASOjKofKXpElR9qclaRiENjed67dLusS5YNorBaEwAJKMABmlGRCVVnr+9JKAkE3LyPF4zN0Sl9JoEZukwuMos5Ev9-AdJOhofDjAAoqxUDQcBB49MPejkwhDDUtERqjwDBIuMYszitOnsmaOdJcqW5zZLoTA7LSfxYCpGL5N9vfDRGFAMBAmGBN3hHlX7WvHRA9zuHwejx2vl3fmxMcVpPxjOLNgOeISAYgLcsY-DmJIxjVJYg6iBslbVsGT5Poex6oE4sAeK+ibdp+CDwdqQjSHogimPopiGICxaaAU6bchseS6IIiG3jWkAoVuO5ofwGEADZ8WhJ5nvwh5wpQADW56rnc64DJx+48fxglHggYmUP0cxxDhNJ4ekuQbPwhz6AYA6FCUWjGgIHLCLopj8tqJmsbJd4KdxR68U4AlCTEWCUFgvF8QEsZYAAtteAYuex95cbusVKV5KlQGpjDiZpTDaVSCa6R++n8j+YjmKYo7ATovDGgY2SbCY2YkUczmQtFbnPlAnlYUJp6MOe6lSRFVZschsWoR5GHtap6npYwmUqjl6pWBIOhGdq1r6pyYqAgOtR8MY2q6HkYiag1QYbkN8UjZhHg+WE-mBcF-nhTJjWDfuw2taNl3jalGkBFppA6e+c26tZpksiRFjzgCvpcFwP7QUU46CDoQH8sYR1yRxQ00BAfFgBg73-WiuX0usAh-sBghaOYZWFICUg-nR0HajDejAWjrmY9juPKQTapejkxRLbk7KDoawqAtmgi-tDxhLNBZljmzTUczjGA80m+EFGI2haDrZhyKKxZGr6SNaNrOvjkU2aiqIivPY+ADuyCzEeeMXWren0lIWRkwBFhIzyFQslkdE8DLXBTtmkqgpFT0nS9jvO8erCwJegRVtGgRYAAFKIO1EAAlBgj3HfJQ0J-QL5ZZ2hNzUUWTcrwMMSNBZEmYCpaaI3lN8PqPDAbaIKMJQEBwCwDjujXXrcDLQgiOIdNyAoOKrLUBjjloPDHFOlbggNpIT7zPa4sBEH6gObImBy+qQxUHBGDUueitmMhmufqMrjeUXBgf6vpAbTI6CIKYAC9RLK+jvlIFYa9zakUcu-KU-Uv4bkPGAQSUAaAACMcY-w9kCQy4ckZ4gUGRcQgIKbgRRpsM0RYmhR2LujGK+4cFEw1KOABQDyYRwppOZYMgtC6m1DIUUSNlwIKQnHR8Z0oDMPVOmIg7DgEU1ATicUi0+FwxkLBeCdDP6x1Li9KRnlvJHhkV6EQi0CEcJAbwbh+YCrbW1MtWQiMWIfxjiXDGBjFLnTGtI7KAMvT8jyPwIw1ReBskKFYaCFUjI6z4Pwng1DCq2wkXFbxrVYqQFMT2cQeJT4imECRIoAd6Sm34SYfUiMzDh3HDoFJ+jJHpP4NGJ2OMIDZPwokzQ9l5xHHgrnBaoEpy1DMCRGGMMRBmFEdHRBejPGPixtg-xk8ew5AKNoJmHIdDdw5LTRu2hdTimbsAsU9T5m7nLmhDp+kIbaE5Drfko4ii5D2VkcpRzhTAW5FoWwtggA */
   id: "app",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "6.1.6",
+  "version": "7.0.0-rc.0",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",
@@ -11,7 +11,7 @@
     "test": "vitest run",
     "test:dev": "vitest watch",
     "test:release": "npm run test && npm run typecheck",
-    "storybook": "storybook dev",
+    "storybook": "storybook dev --port 11111",
     "typecheck": "tsc --noEmit"
   },
   "exports": {
@@ -31,32 +31,33 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^10.1.11",
-    "@storybook/addon-links": "^10.1.11",
-    "@storybook/react-vite": "^10.1.11",
-    "@types/react": "^19.2.8",
-    "msw": "^2.12.7",
+    "@storybook/addon-docs": "^10.2.19",
+    "@storybook/addon-links": "^10.2.19",
+    "@storybook/react-vite": "^10.2.19",
+    "@types/react": "^19.2.14",
+    "fake-indexeddb": "^6.2.5",
+    "msw": "^2.12.12",
     "msw-storybook-addon": "^2.0.6",
-    "np": "^10.2.0",
-    "storybook": "^10.1.11",
+    "np": "^11.0.2",
+    "storybook": "^10.2.19",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
-    "vitest": "^4.0.17"
+    "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@ariakit/react": "^0.4.21",
-    "@indietabletop/tooling": "^5.2.0",
-    "@indietabletop/types": "^1.3.1",
-    "@vanilla-extract/css": "^1.18.0",
+    "@ariakit/react": "^0.4.23",
+    "@indietabletop/tooling": "^6.0.0",
+    "@indietabletop/types": "^1.5.0",
+    "@vanilla-extract/css": "^1.19.0",
     "@vanilla-extract/dynamic": "^2.1.5",
     "@vanilla-extract/recipes": "^0.5.7",
     "@vanilla-extract/sprinkles": "^1.6.5",
-    "@xstate/react": "^6.0.0",
-    "nanoid": "^5.1.6",
+    "@xstate/react": "^6.1.0",
+    "nanoid": "^5.1.7",
     "superstruct": "^2.0.2",
-    "swr": "^2.3.8",
+    "swr": "^2.4.1",
     "wouter": "^3.9.0",
-    "xstate": "^5.25.0"
+    "xstate": "^5.28.0"
   },
   "msw": {
     "workerDirectory": [