@quilted/quilt 0.9.0 → 0.9.2

package/build/typescript/context/QuiltFrameworkContext.d.ts

@@ -0,0 +1,66 @@
+import type { ComponentChildren } from 'preact';
+import type { Navigation, RouteNavigationEntry } from '@quilted/preact-router';
+import type { Localization } from '@quilted/preact-localize';
+import type { BrowserDetails } from '@quilted/preact-browser';
+import type { BrowserAssets } from '@quilted/assets';
+import type { Performance } from '@quilted/preact-performance';
+import type { AsyncActionCache } from '@quilted/async';
+import type { AsyncComponentProps } from '@quilted/preact-async';
+import type { GraphQLClient } from '@quilted/graphql';
+/**
+ * The allowlisted set of `QuiltContext` fields that can be passed as props
+ * to the `<QuiltFrameworkContext>` component.
+ */
+export interface QuiltFrameworkContextProps {
+    /** The navigation instance. */
+    navigation?: Navigation;
+    /** The current route navigation entry (set automatically by `useRoutes()`). */
+    navigationEntry?: RouteNavigationEntry<any, any>;
+    /** The localization instance. */
+    localization?: Localization;
+    /** Browser environment details. */
+    browser?: BrowserDetails;
+    /** The application's asset manifest. */
+    assets?: BrowserAssets;
+    /** Performance monitoring context. */
+    performance?: Performance;
+    /**
+     * Async context for this application. Enables async action caching,
+     * default async component render options, and hydration tracking.
+     */
+    async?: {
+        /** Shared cache for async actions. Required for SSR. */
+        cache?: AsyncActionCache;
+        /** Default render options for async components. */
+        components?: Pick<AsyncComponentProps<any>, 'render'>;
+        /**
+         * Whether to serialize the cache for client-side hydration.
+         * Defaults to `true` when a cache is provided.
+         */
+        serialize?: boolean;
+    };
+    /**
+     * The GraphQL client for this application, or a plain object with
+     * `fetch` (and optional `cache`) properties.
+     */
+    graphql?: Pick<GraphQLClient, 'fetch' | 'cache'>;
+    children?: ComponentChildren;
+}
+/**
+ * Provides a `QuiltContext` value to the component tree. Accepts any declared
+ * `QuiltContext` fields as props and memoizes the context object so that
+ * consumers only re-render when a field they use actually changes.
+ *
+ * Also manages async hydration tracking and optional async action cache
+ * serialization — no separate `<AsyncContext>` needed.
+ *
+ * Use this component at the root of your application to provide navigation,
+ * localization, browser details, and other app-wide context.
+ *
+ * @example
+ * <QuiltFrameworkContext navigation={context.navigation} localization={context.localization}>
+ *   <App />
+ * </QuiltFrameworkContext>
+ */
+export declare function QuiltFrameworkContext({ navigation, navigationEntry, localization, browser, assets, performance, async: asyncProp, graphql, children, }: QuiltFrameworkContextProps): import("preact").JSX.Element;
+//# sourceMappingURL=QuiltFrameworkContext.d.ts.map

package/build/typescript/context/QuiltFrameworkContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuiltFrameworkContext.d.ts","sourceRoot":"","sources":["../../../source/context/QuiltFrameworkContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,QAAQ,CAAC;AAS9C,OAAO,KAAK,EAAC,UAAU,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAC,mBAAmB,EAAe,MAAM,uBAAuB,CAAC;AAE7E,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,kBAAkB,CAAC;AAEpD;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,+BAA+B;IAC/B,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,oBAAoB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACjD,iCAAiC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,mCAAmC;IACnC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,wCAAwC;IACxC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,sCAAsC;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE;QACN,wDAAwD;QACxD,KAAK,CAAC,EAAE,gBAAgB,CAAC;QACzB,mDAAmD;QACnD,UAAU,CAAC,EAAE,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;QACtD;;;WAGG;QACH,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;IACF;;;OAGG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC;IACjD,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,EACV,eAAe,EACf,YAAY,EACZ,OAAO,EACP,MAAM,EACN,WAAW,EACX,KAAK,EAAE,SAAS,EAChB,OAAO,EACP,QAAQ,GACT,EAAE,0BAA0B,gCAqD5B"}

package/build/typescript/context/testing.d.ts

@@ -0,0 +1,41 @@
+import type { ComponentChildren } from 'preact';
+import { TestNavigation } from '@quilted/preact-router/testing';
+import { TestBrowser } from '@quilted/preact-browser/testing';
+import { Localization } from '@quilted/preact-localize';
+export interface QuiltFrameworkTestContextProps {
+    /**
+     * A custom navigation instance for the test. Defaults to a new `TestNavigation`
+     * pointed at `https://example.com/`.
+     *
+     * @see TestNavigation
+     */
+    navigation?: TestNavigation;
+    /**
+     * The localization instance for the test. Defaults to `new Localization('en')`.
+     *
+     * @see Localization
+     */
+    localization?: Localization;
+    /**
+     * A custom browser mock for the test. Defaults to a new `TestBrowser`.
+     *
+     * @see TestBrowser
+     */
+    browser?: TestBrowser;
+    children?: ComponentChildren;
+}
+/**
+ * Provides a `QuiltContext` configured with test-friendly instances of
+ * navigation, localization, and browser details. Use this in unit tests
+ * to wrap components that need Quilt context.
+ *
+ * @example
+ * const navigation = new TestNavigation('/my-page');
+ * render(
+ *   <QuiltFrameworkTestContext navigation={navigation} localization={new Localization('fr')}>
+ *     <MyComponent />
+ *   </QuiltFrameworkTestContext>
+ * );
+ */
+export declare function QuiltFrameworkTestContext({ navigation, localization, browser, children, }: QuiltFrameworkTestContextProps): import("preact").JSX.Element;
+//# sourceMappingURL=testing.d.ts.map

package/build/typescript/context/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../source/context/testing.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAAC,cAAc,EAAC,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAC,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAC,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAEtD,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAE5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,UAAU,EACV,YAAqC,EACrC,OAAO,EACP,QAAQ,GACT,EAAE,8BAA8B,gCAwBhC"}

package/build/typescript/context.d.ts

@@ -1,2 +1,3 @@
-export * from '@quilted/preact-context';
+export { QuiltFrameworkContextPreact, useQuiltContext, createOptionalContext, type QuiltContext, type OptionalContext, type OptionalContextOptions, type UseQuiltContextHookType, } from '@quilted/preact-context';
+export { QuiltFrameworkContext, type QuiltFrameworkContextProps, } from './context/QuiltFrameworkContext.tsx';
 //# sourceMappingURL=context.d.ts.map

package/build/typescript/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../source/context.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../source/context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,qCAAqC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quilted/quilt",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/lemonmade/quilt.git",
@@ -49,6 +49,12 @@
       "quilt:esnext": "./build/esnext/context.esnext",
       "import": "./build/esm/context.mjs"
     },
+    "./context/testing": {
+      "types": "./build/typescript/context/testing.d.ts",
+      "quilt:source": "./source/context/testing.tsx",
+      "quilt:esnext": "./build/esnext/context/testing.esnext",
+      "import": "./build/esm/context/testing.mjs"
+    },
     "./events": {
       "types": "./build/typescript/events.d.ts",
       "quilt:source": "./source/events.ts",
@@ -170,6 +176,9 @@
       "context": [
         "./build/typescript/context.d.ts"
       ],
+      "context/testing": [
+        "./build/typescript/context/testing.d.ts"
+      ],
       "env": [
         "./build/typescript/env.d.ts"
       ],
@@ -229,31 +238,31 @@
     "./build/esm/signals.mjs"
   ],
   "dependencies": {
-    "@quilted/assets": "^0.1.9",
+    "@quilted/assets": "^0.1.11",
     "@quilted/async": "^0.4.23",
-    "@quilted/events": "^2.1.3",
-    "@quilted/graphql": "^3.3.9",
+    "@quilted/events": "^2.1.4",
+    "@quilted/graphql": "^3.4.0",
     "@quilted/hono": "^0.2.0",
-    "@quilted/preact-async": "^0.1.21",
-    "@quilted/preact-browser": "^0.2.0",
-    "@quilted/preact-context": "^0.1.3",
-    "@quilted/preact-graphql": "^0.1.8",
-    "@quilted/preact-localize": "^0.4.0",
-    "@quilted/preact-performance": "^0.1.1",
-    "@quilted/preact-router": "^0.2.13",
-    "@quilted/preact-signals": "^0.1.2",
-    "@quilted/preact-testing": "^0.1.8",
-    "@quilted/preact-workers": "^0.2.1",
+    "@quilted/preact-async": "^0.1.23",
+    "@quilted/preact-browser": "^0.2.7",
+    "@quilted/preact-context": "^0.1.5",
+    "@quilted/preact-graphql": "^0.1.10",
+    "@quilted/preact-localize": "^0.4.2",
+    "@quilted/preact-performance": "^0.1.3",
+    "@quilted/preact-router": "^0.2.16",
+    "@quilted/preact-signals": "^0.1.3",
+    "@quilted/preact-testing": "^0.1.9",
+    "@quilted/preact-workers": "^0.2.2",
     "@quilted/react": "^19.0.0",
-    "@quilted/react-dom": "^19.0.1",
-    "@quilted/signals": "^0.2.3",
-    "@quilted/threads": "^4.0.0",
+    "@quilted/react-dom": "^19.0.2",
+    "@quilted/signals": "^0.2.4",
+    "@quilted/threads": "^4.0.2",
     "jest-matcher-utils": "^29.0.0",
-    "preact-render-to-string": "^6.5.13"
+    "preact-render-to-string": "^6.6.6"
   },
   "peerDependencies": {
     "graphql": "^16.8.0",
-    "preact": "^10.26.0",
+    "preact": "^10.29.0",
     "prettier": "^2.0.0 || ^3.0.0",
     "vitest": "^2.0.0 || ^3.0.0"
   },
@@ -273,7 +282,7 @@
   },
   "devDependencies": {
     "expect": "^29.0.0",
-    "preact": "^10.26.0",
+    "preact": "^10.29.0",
     "prettier": "^3.5.1",
     "vitest": "^3.0.0"
   },

package/source/context/QuiltFrameworkContext.tsx

@@ -0,0 +1,176 @@
+import {useLayoutEffect, useMemo, useContext} from 'preact/hooks';
+import type {ComponentChildren} from 'preact';
+
+import {
+  QuiltFrameworkContextPreact,
+  type QuiltContext,
+} from '@quilted/preact-context';
+import {HTMLAttributes} from '@quilted/preact-browser';
+import {signal} from '@quilted/preact-signals';
+
+import type {Navigation, RouteNavigationEntry} from '@quilted/preact-router';
+import type {Localization} from '@quilted/preact-localize';
+import type {BrowserDetails} from '@quilted/preact-browser';
+import type {BrowserAssets} from '@quilted/assets';
+import type {Performance} from '@quilted/preact-performance';
+import type {AsyncActionCache} from '@quilted/async';
+import type {AsyncComponentProps, AsyncContext} from '@quilted/preact-async';
+import {useAsyncActionCacheSerialization} from '@quilted/preact-async';
+import type {GraphQLClient} from '@quilted/graphql';
+
+/**
+ * The allowlisted set of `QuiltContext` fields that can be passed as props
+ * to the `<QuiltFrameworkContext>` component.
+ */
+export interface QuiltFrameworkContextProps {
+  /** The navigation instance. */
+  navigation?: Navigation;
+  /** The current route navigation entry (set automatically by `useRoutes()`). */
+  navigationEntry?: RouteNavigationEntry<any, any>;
+  /** The localization instance. */
+  localization?: Localization;
+  /** Browser environment details. */
+  browser?: BrowserDetails;
+  /** The application's asset manifest. */
+  assets?: BrowserAssets;
+  /** Performance monitoring context. */
+  performance?: Performance;
+  /**
+   * Async context for this application. Enables async action caching,
+   * default async component render options, and hydration tracking.
+   */
+  async?: {
+    /** Shared cache for async actions. Required for SSR. */
+    cache?: AsyncActionCache;
+    /** Default render options for async components. */
+    components?: Pick<AsyncComponentProps<any>, 'render'>;
+    /**
+     * Whether to serialize the cache for client-side hydration.
+     * Defaults to `true` when a cache is provided.
+     */
+    serialize?: boolean;
+  };
+  /**
+   * The GraphQL client for this application, or a plain object with
+   * `fetch` (and optional `cache`) properties.
+   */
+  graphql?: Pick<GraphQLClient, 'fetch' | 'cache'>;
+  children?: ComponentChildren;
+}
+
+/**
+ * Provides a `QuiltContext` value to the component tree. Accepts any declared
+ * `QuiltContext` fields as props and memoizes the context object so that
+ * consumers only re-render when a field they use actually changes.
+ *
+ * Also manages async hydration tracking and optional async action cache
+ * serialization — no separate `<AsyncContext>` needed.
+ *
+ * Use this component at the root of your application to provide navigation,
+ * localization, browser details, and other app-wide context.
+ *
+ * @example
+ * <QuiltFrameworkContext navigation={context.navigation} localization={context.localization}>
+ *   <App />
+ * </QuiltFrameworkContext>
+ */
+export function QuiltFrameworkContext({
+  navigation,
+  navigationEntry,
+  localization,
+  browser,
+  assets,
+  performance,
+  async: asyncProp,
+  graphql,
+  children,
+}: QuiltFrameworkContextProps) {
+  const parentContext = useContext(QuiltFrameworkContextPreact);
+
+  const asyncValue = useAsyncContext(asyncProp);
+
+  const memoizedValue = useMemo(
+    () =>
+      ({
+        ...parentContext,
+        ...(navigation == null ? undefined : {navigation}),
+        ...(navigationEntry == null ? undefined : {navigationEntry}),
+        ...(localization == null ? undefined : {localization}),
+        ...(browser == null ? undefined : {browser}),
+        ...(assets == null ? undefined : {assets}),
+        ...(performance == null ? undefined : {performance}),
+        async: asyncValue,
+        ...(graphql == null ? undefined : {graphql}),
+      }) satisfies QuiltContext,
+    [
+      parentContext,
+      navigation,
+      navigationEntry,
+      localization,
+      browser,
+      assets,
+      performance,
+      asyncValue,
+      graphql,
+    ],
+  );
+
+  if (typeof document !== 'object') {
+    if (navigation?.cache) {
+      // Serialize the navigation cache for server-side rendering.
+      useAsyncActionCacheSerialization(navigation.cache, {
+        name: 'quilt:router',
+      });
+    }
+  }
+
+  return (
+    <>
+      {localization && (
+        <HTMLAttributes
+          lang={localization.locale}
+          dir={localization.direction}
+        />
+      )}
+      <QuiltFrameworkContextPreact.Provider value={memoizedValue}>
+        {children}
+      </QuiltFrameworkContextPreact.Provider>
+    </>
+  );
+}
+
+function useAsyncContext({
+  cache: asyncCache,
+  components: asyncComponents,
+  serialize: asyncSerialize = true,
+}: NonNullable<QuiltFrameworkContextProps['async']> = {}): AsyncContext {
+  // Hydration signal: starts false on the server, flips to true after
+  // the first client-side render. Stable across re-renders via useRef.
+  const hydratedSignal = useMemo(() => signal(false), []);
+
+  if (typeof document === 'object') {
+    useLayoutEffect(() => {
+      hydratedSignal.value = true;
+    }, []);
+  }
+
+  if (typeof document !== 'object') {
+    // Serialize the async action cache for server-side rendering.
+    useAsyncActionCacheSerialization(asyncSerialize ? asyncCache : undefined, {
+      name: 'quilt:async',
+      optional: true,
+    });
+  }
+
+  return useMemo(
+    () =>
+      ({
+        cache: asyncCache,
+        components: asyncComponents,
+        get isHydrated() {
+          return hydratedSignal.value;
+        },
+      }) satisfies AsyncContext,
+    [asyncCache, asyncComponents, hydratedSignal],
+  );
+}

package/source/context/testing.tsx

@@ -0,0 +1,77 @@
+import {useMemo} from 'preact/hooks';
+import type {ComponentChildren} from 'preact';
+
+import {QuiltFrameworkContextPreact} from '@quilted/preact-context';
+import {TestNavigation} from '@quilted/preact-router/testing';
+import {TestBrowser} from '@quilted/preact-browser/testing';
+import {Localization} from '@quilted/preact-localize';
+
+export interface QuiltFrameworkTestContextProps {
+  /**
+   * A custom navigation instance for the test. Defaults to a new `TestNavigation`
+   * pointed at `https://example.com/`.
+   *
+   * @see TestNavigation
+   */
+  navigation?: TestNavigation;
+
+  /**
+   * The localization instance for the test. Defaults to `new Localization('en')`.
+   *
+   * @see Localization
+   */
+  localization?: Localization;
+
+  /**
+   * A custom browser mock for the test. Defaults to a new `TestBrowser`.
+   *
+   * @see TestBrowser
+   */
+  browser?: TestBrowser;
+
+  children?: ComponentChildren;
+}
+
+/**
+ * Provides a `QuiltContext` configured with test-friendly instances of
+ * navigation, localization, and browser details. Use this in unit tests
+ * to wrap components that need Quilt context.
+ *
+ * @example
+ * const navigation = new TestNavigation('/my-page');
+ * render(
+ *   <QuiltFrameworkTestContext navigation={navigation} localization={new Localization('fr')}>
+ *     <MyComponent />
+ *   </QuiltFrameworkTestContext>
+ * );
+ */
+export function QuiltFrameworkTestContext({
+  navigation,
+  localization = new Localization('en'),
+  browser,
+  children,
+}: QuiltFrameworkTestContextProps) {
+  const resolvedNavigation = useMemo(
+    () => navigation ?? new TestNavigation(),
+    [navigation],
+  );
+  const resolvedBrowser = useMemo(
+    () => browser ?? new TestBrowser(),
+    [browser],
+  );
+
+  const value = useMemo(
+    () => ({
+      navigation: resolvedNavigation,
+      localization,
+      browser: resolvedBrowser,
+    }),
+    [resolvedNavigation, localization, resolvedBrowser],
+  );
+
+  return (
+    <QuiltFrameworkContextPreact.Provider value={value}>
+      {children}
+    </QuiltFrameworkContextPreact.Provider>
+  );
+}

package/source/context.ts

@@ -1 +1,14 @@
-export * from '@quilted/preact-context';
+export {
+  QuiltFrameworkContextPreact,
+  useQuiltContext,
+  createOptionalContext,
+  type QuiltContext,
+  type OptionalContext,
+  type OptionalContextOptions,
+  type UseQuiltContextHookType,
+} from '@quilted/preact-context';
+
+export {
+  QuiltFrameworkContext,
+  type QuiltFrameworkContextProps,
+} from './context/QuiltFrameworkContext.tsx';