@indietabletop/appkit 6.1.6 → 7.0.0-0

package/{lib/types.ts → dist/types.d.ts}

@@ -1,12 +1,9 @@
-import type { Infer } from "superstruct";
-import { currentUser, redeemedPledge, sessionInfo } from "./structs.js";
-
-// Generic type helpers
-
-type Brand<B> = { __brand: B };
-
+import { Infer } from 'superstruct';
+import { currentUser, redeemedPledge, sessionInfo } from './structs.js';
+type Brand<B> = {
+    __brand: B;
+};
 export type Branded<T, B> = T & Brand<B>;
-
 /**
  * Make properties in union K required in T.
  *
@@ -23,7 +20,6 @@ export type Branded<T, B> = T & Brand<B>;
  * ```
  */
 export type RequiredPick<T, K extends keyof T> = T & Required<Pick<T, K>>;
-
 /**
  * A branded string.
  *
@@ -32,20 +28,13 @@ export type RequiredPick<T, K extends keyof T> = T & Required<Pick<T, K>>;
  * that exists in our codebase) or sanitized user-generated content.
  */
 export type TrustedHtml = Branded<string, "TrustedHtml">;
-
-// Common ITC types
-
 export type CurrentUser = Infer<ReturnType<typeof currentUser>>;
-
 export type SessionInfo = Infer<ReturnType<typeof sessionInfo>>;
-
 export type RedeemedPledge = Infer<ReturnType<typeof redeemedPledge>>;
-
-export type FailurePayload =
-  | {
-      type: "API_ERROR";
-      code: number;
-    }
-  | {
-      type: "NETWORK_ERROR" | "UNKNOWN_ERROR" | "VALIDATION_ERROR";
-    };
+export type FailurePayload = {
+    type: "API_ERROR";
+    code: number;
+} | {
+    type: "NETWORK_ERROR" | "UNKNOWN_ERROR" | "VALIDATION_ERROR";
+};
+export {};

package/dist/unique.d.ts

@@ -0,0 +1,10 @@
+type UniqueKey = string | number;
+/**
+ * Returns an array of unique items, determining uniqueness via the getKey
+ * function.
+ *
+ * Note that the first unique item is returned, all others are omitted
+ * (assuming that they are unique, so it shouldn't matter).
+ */
+export declare function uniqueBy<T>(items: T[], getKey: (item: T) => UniqueKey): T[];
+export {};

package/dist/unique.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/use-async-op.d.ts

@@ -0,0 +1,6 @@
+import { AsyncOp } from './async-op.js';
+export declare function useAsyncOp<T, E>(): {
+    op: AsyncOp<T, E>;
+    setSuccess: (value: T) => void;
+    setFailure: (failure: E) => void;
+};

package/dist/use-document-background-color.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Sets document background color, reverting it to previous color on unmount.
+ */
+export declare function useDocumentBackgroundColor(bodyColor: string): void;

package/dist/use-form.d.ts

@@ -0,0 +1,29 @@
+import { FormStoreState } from '@ariakit/react';
+import { Failure, Success } from './async-op.ts';
+type Validator<T> = (value: T) => string | null;
+type MaybePromise<T> = T | Promise<T>;
+export declare function useForm<T extends object, R>(props: {
+    defaultValues: T;
+    validate?: {
+        [K in keyof T]?: Validator<T[K]>;
+    };
+    /**
+     * Handles form submission login.
+     *
+     * This function should return a Success or Failure. Failures should always contain a string
+     * which will be used as the form error message.
+     */
+    onSubmit: (state: FormStoreState<T>) => MaybePromise<Success<R> | Failure<string>>;
+    /**
+     * If submission was successful (i.e. onSubmit returned a Success), will be run to perform any
+     * side-effect necessary.
+     *
+     * Typically this is used for navigation on mutating some local state.
+     */
+    onSuccess?: (value: R, state: FormStoreState<T>) => MaybePromise<void>;
+}): {
+    form: import('@ariakit/react').FormStore<T>;
+    submitName: string;
+    op: Failure<string> | Success<R> | null;
+};
+export {};

package/dist/use-is-installed.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Checks whether the app is installed.
+ *
+ * Note that this doesn't check whether the app is installed on the device at
+ * all, only whether the currently running process is within an installed window
+ * or running within a browser.
+ */
+export declare function useIsInstalled(): boolean;

package/dist/use-media-query.d.ts

@@ -0,0 +1 @@
+export declare function useMediaQuery(query: string): boolean;

package/dist/use-reverting-state.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sets a state that will automatically revert to null after specified number
+ * of milliseconds.
+ */
+export declare function useRevertingState<T>(initialState: T, revertAfterMs: number): readonly [T | null, import('react').Dispatch<import('react').SetStateAction<T | null>>];

package/dist/use-scroll-restoration.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Handles scroll restoration on window.
+ *
+ * This hook behaves a little differently than the default browser scroll
+ * restoration. This is due to limitations of Wouter (our router of choice)
+ * as well the need to make the app feel more app-like.
+ *
+ * Every scroll position is remembered however the user has got to it (we
+ * don't differentiate between new entries in browser history and back
+ * navigation), but they are only restored if the user last visited the
+ * location less than 60 minutes ago.
+ */
+export declare function useScrollRestoration(
+/**
+ * The current path, provided by your router of choice.
+ */
+pathname: string, options?: {
+    /**
+     * A list of paths where scroll restoration should never be performed.
+     *
+     * This list should have stable identity for optimal performance. Make
+     * sure to use `useMemo` or define the list in module scope.
+     */
+    neverRestore?: string[];
+}): void;

package/dist/useEnsureValue.d.ts

@@ -0,0 +1,6 @@
+import { Failure, Success, AsyncOp } from './async-op.ts';
+/**
+ * Checks if the provided value is non-nullish, otherwise calls provided
+ * getValue function to obtain the value (presumably from some remote location).
+ */
+export declare function useEnsureValue<T>(value: T | null | undefined, getValue: () => Promise<Success<T> | Failure<string>>): AsyncOp<T, string>;

package/dist/useInvokeClient.d.ts

@@ -0,0 +1,25 @@
+import { SWRConfiguration, SWRResponse } from 'swr';
+import { Pending } from './async-op.ts';
+import { IndieTabletopClient } from './client.ts';
+/**
+ * Creates a `useInvokeClient` hook that makes it ergonomic to invoke
+ * client methods.
+ *
+ * Note that only methods starting with `get` are picked up. This hook is
+ * intended for making easy fetches, not for form submissions.
+ */
+export declare function createUseInvokeClient<C extends IndieTabletopClient>(c: C): <K extends keyof C & `get${string}`>(
+/**
+ * ITC Client's method name.
+ */
+method: K, 
+/**
+ * Method's arguments.
+ *
+ * **IMPORTANT**: Must be an array or primitive values as it is directly
+ * used as a `useCallback` dependecy array.
+ */
+args: C[K] extends (...args: any) => any ? Parameters<C[K]> : never, options?: {
+    performFetch?: boolean;
+    swr?: SWRConfiguration;
+}) => C[K] extends (...args: any) => any ? [Awaited<ReturnType<C[K]>> | Pending, SWRResponse<unknown, unknown>] : never;

package/dist/useIsVisible.d.ts

@@ -0,0 +1,4 @@
+export declare function useIsVisible<T extends HTMLElement>(initialState?: boolean, options?: IntersectionObserverInit): {
+    ref: import('react').RefObject<T | null>;
+    isVisible: boolean;
+};

package/dist/utm.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Full UTM configuration object.
+ */
+export type UtmParams = {
+    /**
+     * The website/platform the visitor is coming from.
+     */
+    source: string;
+    /**
+     * The type of marketing channel (e.g. cpc, email, affiliate, social,
+     * or similar).
+     */
+    medium: string;
+    /**
+     * The name of the campaign or product description. In our case, this is
+     * usually the name of the app.
+     */
+    campaign: string;
+    /**
+     * Optionally, provide an identifier for the place from which the link was
+     * clicked. E.g. footer, join, etc.
+     */
+    content?: string;
+    /**
+     * Optionally, identify paid keywords. We usually do not use this.
+     */
+    term?: string;
+};
+/**
+ * UTM Params configuration that is appropriate to set at the link level,
+ * if app-level defaults have been set.
+ */
+export type LinkUtmParams = Pick<UtmParams, "content" | "term">;
+/**
+ * Returns URL Search params with provided UTM configuration.
+ *
+ * Most of the time, you probably want to set up some defaults using
+ * {@link createUtm}. This function is intended for special cases.
+ */
+export declare function utm(params: UtmParams): URLSearchParams;
+/**
+ * A factory for the {@link utm} function. Use it to set sensible defaults for
+ * further use of the returned function.
+ *
+ * @example
+ * ```ts
+ * const utm = createUtm({
+ *   source: "indietabletopclub",
+ *   medium: "referral",
+ *   campaign: "spacegitsapp",
+ * });
+ *
+ * utm() // => URLSearchParams that inlude the above config
+ *
+ * utm({ campaign: "foo", content: "bar" }) // Sets optional fiels and overrides
+ * ```
+ */
+export declare function createUtm(defaults: UtmParams): (params?: Partial<UtmParams>) => URLSearchParams;

package/dist/utm.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/validations.d.ts

@@ -0,0 +1,3 @@
+export declare const EMAIL_REGEX: RegExp;
+export declare const validEmail: (value: string) => "This doesn't look like a valid email." | null;
+export declare const validPassword: (value: string) => "A password has to be at least 8 characters long." | "A password cannot be longer than 256 characters." | null;

package/dist/vars.css.d.ts

@@ -0,0 +1,10 @@
+export declare const Color: {
+    GRAY: `var(--${string})`;
+    MID_GRAY: `var(--${string})`;
+    LIGHT_GRAY: `var(--${string})`;
+    PALE_GRAY: `var(--${string})`;
+    PURPLE: `var(--${string})`;
+};
+export declare const ZIndex: {
+    DIALOG: `var(--${string})`;
+};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "6.1.6",
+  "version": "7.0.0-0",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",
   "scripts": {
     "release": "np",
-    "build": "tsc",
+    "build": "vite build",
+    "prepare": "vite build",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:dev": "vitest watch",
@@ -15,11 +16,14 @@
     "typecheck": "tsc --noEmit"
   },
   "exports": {
-    ".": "./lib/index.ts",
-    "./*.css.ts": "./lib/*.css.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/appkit.js"
+    },
+    "./style.css": "./dist/appkit.css"
   },
   "files": [
-    "/lib"
+    "/dist"
   ],
   "author": "Artur Müller",
   "repository": {
@@ -35,12 +39,15 @@
     "@storybook/addon-links": "^10.1.11",
     "@storybook/react-vite": "^10.1.11",
     "@types/react": "^19.2.8",
+    "@vanilla-extract/vite-plugin": "^5.1.4",
+    "@vitejs/plugin-react": "^5.1.4",
     "msw": "^2.12.7",
     "msw-storybook-addon": "^2.0.6",
     "np": "^10.2.0",
     "storybook": "^10.1.11",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.17"
   },
   "dependencies": {

package/lib/AppConfig/AppConfig.tsx

@@ -1,61 +0,0 @@
-import { createContext, type ReactNode, useContext } from "react";
-import type { IndieTabletopClient } from "../client.ts";
-import type { AppHrefs } from "../hrefs.ts";
-
-export type AppConfig = {
-  app: {
-    /**
-     * The app's name, e.g. Space Gits. Do not include the word App in this
-     * title -- it will be added automatically in places where it's needed.
-     */
-    name: string;
-
-    /**
-     * The URL to the app's icon. This should be a maskable-style icon. In
-     * other words, it should not include its own transparency.
-     */
-    icon: string;
-  };
-  isDev: boolean;
-  client: IndieTabletopClient;
-  hrefs: AppHrefs;
-  placeholders: {
-    email: string;
-  };
-};
-
-const AppConfigContext = createContext<AppConfig | null>(null);
-
-export function AppConfigProvider(props: {
-  config: AppConfig;
-  children: ReactNode;
-}) {
-  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/AuthCard/AuthCard.stories.ts

@@ -1,34 +0,0 @@
-import { fn } from "storybook/test";
-import preview from "../../.storybook/preview.tsx";
-import { AuthCard } from "./AuthCard.tsx";
-
-const meta = preview.meta({
-  title: "Account/Auth Card",
-  component: AuthCard,
-  tags: ["autodocs"],
-  args: {
-    onLogout: fn(),
-  },
-});
-
-/**
- * The default case where elements are correctly separated with middots.
- */
-export const Authenticated = meta.story({
-  args: {
-    currentUser: {
-      id: "martin",
-      email: "martin@example.com",
-      isVerified: true,
-    },
-  },
-});
-
-/**
- * The default case in which all steps of the flow succeed.
- */
-export const Anonymous = meta.story({
-  args: {
-    currentUser: null,
-  },
-});

package/lib/AuthCard/AuthCard.tsx

@@ -1,64 +0,0 @@
-import { Button } from "@ariakit/react";
-import { Link } from "wouter";
-import { useAppConfig } from "../AppConfig/AppConfig.tsx";
-import { interactiveText } from "../common.css.ts";
-import { IndieTabletopClubLogo } from "../IndieTabletopClubLogo.tsx";
-import { LetterheadParagraph } from "../Letterhead/index.tsx";
-import { button } from "../Letterhead/style.css.ts";
-import { MiddotSeparated } from "../MiddotSeparated/MiddotSeparated.tsx";
-import type { CurrentUser } from "../types.ts";
-import { card } from "./style.css.ts";
-
-/**
- * Small, ITC-branded card that shows authentication status.
- *
- * Primarily intended to be used within the sidenav.
- */
-export function AuthCard(props: {
-  onLogout: () => void;
-  currentUser: CurrentUser | null;
-}) {
-  const { currentUser, onLogout } = props;
-  const { hrefs } = useAppConfig();
-  const align = !currentUser ? "center" : "start";
-
-  return (
-    <div className={card.container({ align })}>
-      <IndieTabletopClubLogo className={card.logo({ align })} />
-
-      {currentUser ? (
-        <>
-          <LetterheadParagraph>{currentUser.email}</LetterheadParagraph>
-
-          <MiddotSeparated className={card.loggedInAction}>
-            <Link className={interactiveText} href={hrefs.account()}>
-              Account
-            </Link>
-
-            <Button className={interactiveText} onClick={() => onLogout()}>
-              Log out
-            </Button>
-          </MiddotSeparated>
-        </>
-      ) : (
-        <>
-          <LetterheadParagraph size="small">
-            Enable backup & sync, access your pledge data, and more!
-          </LetterheadParagraph>
-
-          <Link href={hrefs.join()} className={button()}>
-            Join
-          </Link>
-
-          <LetterheadParagraph size="small">
-            {"Already have an account? "}
-            <Link href={hrefs.login()} className={interactiveText}>
-              Log in
-            </Link>
-            {"."}
-          </LetterheadParagraph>
-        </>
-      )}
-    </div>
-  );
-}

package/lib/AuthCard/style.css.ts

@@ -1,49 +0,0 @@
-import { style } from "@vanilla-extract/css";
-import { recipe } from "@vanilla-extract/recipes";
-
-export const card = {
-  container: recipe({
-    base: {
-      display: "flex",
-      flexDirection: "column",
-      gap: "0.75rem",
-      backgroundColor: "white",
-      padding: "1.5rem",
-      borderRadius: "0.5rem",
-      color: "black",
-    },
-
-    variants: {
-      align: {
-        center: {
-          textAlign: "center",
-        },
-        start: {
-          textAlign: "start",
-        },
-      },
-    },
-  }),
-
-  logo: recipe({
-    base: {
-      maxInlineSize: "11rem",
-    },
-
-    variants: {
-      align: {
-        center: {
-          marginInline: "auto",
-        },
-        start: {
-          marginInline: "0",
-        },
-      },
-    },
-  }),
-
-  loggedInAction: style({
-    borderBlockStart: "1px solid hsl(0 0% 0% / 0.1)",
-    paddingBlockStart: "0.75rem",
-  }),
-};

package/lib/DialogTrigger/index.tsx

@@ -1,36 +0,0 @@
-import {
-  DialogProvider,
-  useDialogContext,
-  useStoreState,
-} from "@ariakit/react";
-import type { ReactElement, ReactNode } from "react";
-
-function DialogGuard(props: { children: ReactNode }) {
-  const dialog = useDialogContext();
-  const isMounted = useStoreState(dialog, (store) => store?.mounted);
-  if (!isMounted) {
-    return null;
-  }
-  return props.children;
-}
-
-/**
- * Wraps AriaKit's DialogProvider, but takes a tuple of Dialog a DialogDisclosure
- * elements as children, and makes sure that the Dialog component is not
- * rendered when it is hidden.
- *
- * This is important in cases where the dialog contains a form that should only
- * be initialized and re-initialized when the dialog opens, not when it is first
- * rendered.
- */
-export function DialogTrigger(props: {
-  children: [ReactElement, ReactElement];
-}) {
-  const [dialog, button] = props.children;
-  return (
-    <DialogProvider>
-      <DialogGuard>{dialog}</DialogGuard>
-      {button}
-    </DialogProvider>
-  );
-}

package/lib/DocumentTitle/DocumentTitle.tsx

@@ -1,10 +0,0 @@
-import { useAppConfig } from "../AppConfig/AppConfig.tsx";
-
-export function DocumentTitle(props: { children: string }) {
-  const { children: children } = props;
-  const { app, isDev } = useAppConfig();
-  const itc = `${app.name} · Indie Tabletop Club`;
-  const title = children ? `${children} | ${itc}` : itc;
-
-  return <title>{isDev ? `[DEV] ${title}` : title}</title>;
-}

package/lib/EnumMapper.ts

@@ -1,50 +0,0 @@
-type InputValues<K extends string | number, V> = Record<K, V> | Array<[K, V]>;
-
-/**
- * Handles mapping enums to arbitrary values.
- */
-export class EnumMapper<K extends string | number, V> {
-  private map: Map<K, V>;
-  private fallback: V;
-
-  constructor(values: InputValues<K, V>, fallback: V) {
-    const entries = Array.isArray(values)
-      ? values
-      : (Object.entries(values) as Array<[K, V]>);
-    this.map = new Map(entries);
-    this.fallback = fallback;
-  }
-
-  /**
-   * Returns a value corresponding to the provided key.
-   *
-   * If no match is found, returns the fallback value provided in the constructor.
-   *
-   * Note that TypeScript will make sure that we only ever use the right types
-   * as the enum param, but it can still happen at runtime that different
-   * values are provided.
-   */
-  get(key: K | undefined): V {
-    if (key === undefined) {
-      return this.fallback;
-    }
-
-    const value = this.map.get(key);
-    if (value === undefined) {
-      return this.fallback;
-    }
-
-    return value;
-  }
-
-  /**
-   * All enums known by this mapper.
-   */
-  get enums() {
-    return Array.from(this.map.keys());
-  }
-
-  static from<K extends string>(values: InputValues<K, string>) {
-    return new EnumMapper(values, "Unknown");
-  }
-}

package/lib/ExternalLink.tsx

@@ -1,10 +0,0 @@
-import type { AnchorHTMLAttributes } from "react";
-
-export type ExternalLinkProps = Omit<
-  AnchorHTMLAttributes<HTMLAnchorElement>,
-  "rel" | "target"
->;
-
-export function ExternalLink(props: ExternalLinkProps) {
-  return <a {...props} target="_blank" rel="noreferrer noopener" />;
-}

package/lib/FullscreenDismissBlocker.tsx

@@ -1,23 +0,0 @@
-import { useEffect } from "react";
-
-function preventDefaultEscHandling(event: KeyboardEvent) {
-  if (event.key === "Escape") {
-    event.preventDefault();
-  }
-}
-
-/**
- * This component prevents the default MacOS behaviour where a fullscreen window
- * gets minimized by pressing Escape.
- */
-export function FullscreenDismissBlocker() {
-  useEffect(() => {
-    window.addEventListener("keydown", preventDefaultEscHandling);
-
-    return () => {
-      window.removeEventListener("keydown", preventDefaultEscHandling);
-    };
-  }, []);
-
-  return null;
-}