@quilted/quilt 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,263 @@
 # @quilted/quilt
 
+## 0.9.2
+
+### Patch Changes
+
+- [#894](https://github.com/lemonmade/quilt/pull/894) [`fb998d1`](https://github.com/lemonmade/quilt/commit/fb998d1d0a7fb7981184daa5307320477355ace8) Thanks [@lemonmade](https://github.com/lemonmade)! - Consolidate all framework context into a unified `QuiltContext` architecture.
+
+  Previously, Quilt's context was fragmented across many standalone provider components (`AsyncContext`, `GraphQLContext`, `EmailContext`, etc.), each backed by its own Preact context object. This release consolidates everything into a single `QuiltContext` interface, augmented by each package via TypeScript module declaration merging, and provided by a single `<QuiltFrameworkContext>` component.
+
+  ## Breaking changes
+
+  ### All packages: unified `QuiltContext` interface
+
+  Each `@quilted/*` package now augments a single `QuiltContext` interface from `@quilted/preact-context` rather than maintaining its own standalone context. If you were accessing any Quilt context values directly via `useContext(SomeSpecificContext)`, switch to the appropriate `use*` hook instead.
+
+  ### `@quilted/preact-router`: `useRouter` renamed to `useNavigation`
+
+  ```ts
+  // Before
+  import {useRouter} from '@quilted/quilt/navigation';
+  const router = useRouter();
+
+  // After
+  import {useNavigation} from '@quilted/quilt/navigation';
+  const navigation = useNavigation();
+  ```
+
+  ### `@quilted/preact-router`: `router` QuiltContext field renamed to `navigation`
+
+  The `QuiltContext` field that holds the navigation instance is now `navigation` instead of `router`. This affects any code that reads the field directly, and the prop name on `<QuiltFrameworkContext>`.
+
+  ```tsx
+  // Before
+  <QuiltFrameworkContext router={myNavigation} />
+
+  // After
+  <QuiltFrameworkContext navigation={myNavigation} />
+  ```
+
+  ### `@quilted/preact-router`: `TestRouter` renamed to `TestNavigation`
+
+  ```ts
+  // Before
+  import {TestRouter} from '@quilted/quilt/navigation/testing';
+
+  // After
+  import {TestNavigation} from '@quilted/quilt/navigation/testing';
+  ```
+
+  ### `@quilted/preact-browser`: `browserDetails` and `browserAssets` QuiltContext fields renamed
+
+  The `QuiltContext` fields for browser environment details and the asset manifest have shorter, cleaner names:
+
+  - `browserDetails` → `browser`
+  - `browserAssets` → `assets`
+
+  These affect the props on `<QuiltFrameworkContext>` and any direct reads of the context.
+
+  ```tsx
+  // Before
+  <QuiltFrameworkContext browserDetails={browser} browserAssets={assets} />
+
+  // After
+  <QuiltFrameworkContext browser={browser} assets={assets} />
+  ```
+
+  ### `@quilted/preact-localize`: `localize` QuiltContext field renamed to `localization`
+
+  The QuiltContext field and the corresponding `<QuiltFrameworkContext>` prop are now `localization`:
+
+  ```tsx
+  // Before
+  <QuiltFrameworkContext localize={localization} />
+
+  // After
+  <QuiltFrameworkContext localization={localization} />
+  ```
+
+  ### `@quilted/preact-localize`: `createLocalizedFormatting` and `createLocalization` removed
+
+  These factory functions have been removed. Use the `Localization` class directly:
+
+  ```ts
+  // Before
+  import {createLocalization} from '@quilted/preact-localize';
+  const localization = createLocalization('en');
+
+  // After
+  import {Localization} from '@quilted/preact-localize';
+  const localization = new Localization('en');
+  ```
+
+  ### `@quilted/preact-async`: `AsyncContext` component removed
+
+  The standalone `<AsyncContext>` provider component has been removed. Pass async context directly to `<QuiltFrameworkContext>` instead:
+
+  ```tsx
+  // Before
+  import {AsyncContext, AsyncActionCache} from '@quilted/quilt/async';
+
+  <AsyncContext cache={cache}>
+    <App />
+  </AsyncContext>;
+
+  // After
+  import {QuiltFrameworkContext} from '@quilted/quilt/context';
+  import {AsyncActionCache} from '@quilted/quilt/async';
+
+  <QuiltFrameworkContext async={{cache}}>
+    <App />
+  </QuiltFrameworkContext>;
+  ```
+
+  `QuiltFrameworkContext` handles cache serialization for server-side rendering automatically, so no other changes are required.
+
+  ### `@quilted/preact-graphql`: `GraphQLContext` component removed
+
+  The standalone `<GraphQLContext>` provider component has been removed. The two separate `graphqlRun` and `graphqlCache` props on `<QuiltFrameworkContext>` have been replaced with a single `graphql` prop that accepts a `GraphQLClient` instance (or any object with `fetch` and `cache` properties):
+
+  ```tsx
+  // Before
+  import {GraphQLContext} from '@quilted/quilt/graphql';
+
+  <QuiltFrameworkContext navigation={navigation}>
+    <GraphQLContext fetch={myFetch} cache={myCache}>
+      <App />
+    </GraphQLContext>
+  </QuiltFrameworkContext>;
+
+  // After — using the new GraphQLClient class
+  import {GraphQLClient} from '@quilted/quilt/graphql';
+
+  const graphql = new GraphQLClient(myFetch);
+
+  <QuiltFrameworkContext navigation={navigation} graphql={graphql}>
+    <App />
+  </QuiltFrameworkContext>;
+  ```
+
+  ### `@quilted/preact-email`: `EmailContext` removed
+
+  The standalone `EmailContext` Preact context object has been removed. Email components should use the new `useEmailManager()` hook to access the email manager, which reads from the unified `QuiltContext`:
+
+  ```ts
+  // Before
+  import {useContext} from 'preact/hooks';
+  import {EmailContext} from '@quilted/preact-email';
+  const email = useContext(EmailContext);
+
+  // After
+  import {useEmailManager} from '@quilted/preact-email';
+  const email = useEmailManager();
+  ```
+
+  ### `@quilted/quilt`: `QuiltContext` component renamed to `QuiltFrameworkContext`
+
+  The provider component is now named `QuiltFrameworkContext` to avoid a name clash with the `QuiltContext` TypeScript interface:
+
+  ```tsx
+  // Before
+  import {QuiltContext} from '@quilted/quilt/context';
+  <QuiltContext navigation={navigation}>...</QuiltContext>;
+
+  // After
+  import {QuiltFrameworkContext} from '@quilted/quilt/context';
+  <QuiltFrameworkContext navigation={navigation}>...</QuiltFrameworkContext>;
+  ```
+
+  ### `@quilted/quilt`: `QuiltTestContext` renamed to `QuiltFrameworkTestContext`, takes `localization` instead of `locale`
+
+  The test context helper component is now `QuiltFrameworkTestContext` and accepts a `Localization` instance directly instead of a locale string:
+
+  ```tsx
+  // Before
+  import {QuiltTestContext} from '@quilted/quilt/context/testing';
+  <QuiltTestContext locale="fr">...</QuiltTestContext>;
+
+  // After
+  import {QuiltFrameworkTestContext} from '@quilted/quilt/context/testing';
+  import {Localization} from '@quilted/quilt/localize';
+  <QuiltFrameworkTestContext localization={new Localization('fr')}>
+    ...
+  </QuiltFrameworkTestContext>;
+  ```
+
+  ## New features
+
+  ### `@quilted/graphql`: `GraphQLClient` class
+
+  A new `GraphQLClient` class bundles a GraphQL fetch function and an optional result cache into a single object. A cache is created automatically by default, configured to use the same fetch function:
+
+  ```ts
+  import {createGraphQLFetch, GraphQLClient} from '@quilted/quilt/graphql';
+
+  // Cache created automatically from the fetch function
+  const client = new GraphQLClient(createGraphQLFetch({url: '/graphql'}));
+
+  // Disable caching
+  const client = new GraphQLClient(myFetch, {cache: false});
+
+  // Share an existing cache
+  const cache = new GraphQLCache();
+  const client = new GraphQLClient(myFetch, {cache});
+
+  // Use the client
+  client.fetch(MyQuery, {variables: {id: '1'}});
+  client.cache?.query(MyQuery, {variables: {id: '1'}});
+  ```
+
+  ### `@quilted/preact-router`: `useNavigation()` hook
+
+  The renamed `useNavigation()` hook returns the active `Navigation` instance from context, providing access to the current URL, navigation history, and programmatic navigation.
+
+  ### `@quilted/preact-email`: `useEmailManager()` hook
+
+  A new `useEmailManager()` hook provides access to the `EmailManager` instance from the unified `QuiltContext`. Returns `undefined` outside of an email rendering context.
+
+  ### `@quilted/preact-async`: signal-backed `async.isHydrated`
+
+  The `AsyncContext` interface (accessed via `useQuiltContext('async')`) now includes an `isHydrated` boolean getter backed by a Preact signal. Any component that reads `async.isHydrated` will automatically re-render when the client hydration completes, without requiring a manual signal subscription.
+
+  ### `@quilted/localize`: `Localization` class documentation
+
+  The `Localization` class now has full JSDoc documentation on the class, constructor, all properties (`locale`, `direction`, `numberFormatter`, `dateTimeFormatter`), and all methods (`formatNumber`, `formatCurrency`, `formatDate`).
+
+- Updated dependencies [[`fb998d1`](https://github.com/lemonmade/quilt/commit/fb998d1d0a7fb7981184daa5307320477355ace8)]:
+  - @quilted/graphql@3.4.0
+  - @quilted/preact-performance@0.1.3
+  - @quilted/preact-localize@0.4.2
+  - @quilted/preact-browser@0.2.7
+  - @quilted/preact-context@0.1.5
+  - @quilted/preact-graphql@0.1.10
+  - @quilted/preact-router@0.2.16
+  - @quilted/preact-async@0.1.23
+
+## 0.9.1
+
+### Patch Changes
+
+- [`e6fa47e`](https://github.com/lemonmade/quilt/commit/e6fa47e93981ce0eaebbe1546659aaa08cc22689) Thanks [@lemonmade](https://github.com/lemonmade)! - Update Preact and Signal dependencies
+
+- Updated dependencies [[`b1df5da`](https://github.com/lemonmade/quilt/commit/b1df5daff8441f8435a62b02b4ad3676d3ddcc3b), [`06b43bc`](https://github.com/lemonmade/quilt/commit/06b43bc44d271ce30798dc0b582870208bae1572), [`e6fa47e`](https://github.com/lemonmade/quilt/commit/e6fa47e93981ce0eaebbe1546659aaa08cc22689)]:
+  - @quilted/preact-browser@0.2.6
+  - @quilted/assets@0.1.11
+  - @quilted/preact-router@0.2.15
+  - @quilted/preact-performance@0.1.2
+  - @quilted/preact-localize@0.4.1
+  - @quilted/preact-context@0.1.4
+  - @quilted/preact-graphql@0.1.9
+  - @quilted/preact-signals@0.1.3
+  - @quilted/preact-testing@0.1.9
+  - @quilted/preact-workers@0.2.2
+  - @quilted/preact-async@0.1.22
+  - @quilted/react-dom@19.0.2
+  - @quilted/graphql@3.3.10
+  - @quilted/signals@0.2.4
+  - @quilted/threads@4.0.2
+  - @quilted/events@2.1.4
+
 ## 0.9.0
 
 ### Minor Changes

package/build/esm/context/QuiltFrameworkContext.mjs

@@ -0,0 +1,109 @@
+import { useContext, useMemo, useLayoutEffect } from 'preact/hooks';
+import { QuiltFrameworkContextPreact } from '@quilted/preact-context';
+import { HTMLAttributes } from '@quilted/preact-browser';
+import { signal } from '@quilted/preact-signals';
+import { useAsyncActionCacheSerialization } from '@quilted/preact-async';
+import { jsxs, Fragment, jsx } from 'preact/jsx-runtime';
+
+/**
+ * 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>
+ */
+function QuiltFrameworkContext({
+  navigation,
+  navigationEntry,
+  localization,
+  browser,
+  assets,
+  performance,
+  async: asyncProp,
+  graphql,
+  children
+}) {
+  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
+    })
+  }), [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 jsxs(Fragment, {
+    children: [localization && jsx(HTMLAttributes, {
+      lang: localization.locale,
+      dir: localization.direction
+    }), jsx(QuiltFrameworkContextPreact.Provider, {
+      value: memoizedValue,
+      children: children
+    })]
+  });
+}
+function useAsyncContext({
+  cache: asyncCache,
+  components: asyncComponents,
+  serialize: asyncSerialize = true
+} = {}) {
+  // 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;
+    }
+  }), [asyncCache, asyncComponents, hydratedSignal]);
+}
+
+export { QuiltFrameworkContext };

package/build/esm/context/testing.mjs

@@ -0,0 +1,40 @@
+import { useMemo } from 'preact/hooks';
+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';
+import { jsx } from 'preact/jsx-runtime';
+
+/**
+ * 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>
+ * );
+ */
+function QuiltFrameworkTestContext({
+  navigation,
+  localization = new Localization('en'),
+  browser,
+  children
+}) {
+  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 jsx(QuiltFrameworkContextPreact.Provider, {
+    value: value,
+    children: children
+  });
+}
+
+export { QuiltFrameworkTestContext };

package/build/esm/context.mjs

@@ -1 +1,2 @@
-export * from '@quilted/preact-context';
+export { QuiltFrameworkContextPreact, createOptionalContext, useQuiltContext } from '@quilted/preact-context';
+export { QuiltFrameworkContext } from './context/QuiltFrameworkContext.mjs';

package/build/esnext/context/QuiltFrameworkContext.esnext

@@ -0,0 +1,92 @@
+import { jsxs, Fragment, jsx } from 'preact/jsx-runtime';
+import { useContext, useMemo, useLayoutEffect } from 'preact/hooks';
+import { QuiltFrameworkContextPreact } from '@quilted/preact-context';
+import { HTMLAttributes } from '@quilted/preact-browser';
+import { signal } from '@quilted/preact-signals';
+import { useAsyncActionCacheSerialization } from '@quilted/preact-async';
+
+function QuiltFrameworkContext({
+  navigation,
+  navigationEntry,
+  localization,
+  browser,
+  assets,
+  performance,
+  async: asyncProp,
+  graphql,
+  children
+}) {
+  const parentContext = useContext(QuiltFrameworkContextPreact);
+  const asyncValue = useAsyncContext(asyncProp);
+  const memoizedValue = useMemo(
+    () => ({
+      ...parentContext,
+      ...navigation == null ? void 0 : { navigation },
+      ...navigationEntry == null ? void 0 : { navigationEntry },
+      ...localization == null ? void 0 : { localization },
+      ...browser == null ? void 0 : { browser },
+      ...assets == null ? void 0 : { assets },
+      ...performance == null ? void 0 : { performance },
+      async: asyncValue,
+      ...graphql == null ? void 0 : { graphql }
+    }),
+    [
+      parentContext,
+      navigation,
+      navigationEntry,
+      localization,
+      browser,
+      assets,
+      performance,
+      asyncValue,
+      graphql
+    ]
+  );
+  if (typeof document !== "object") {
+    if (navigation?.cache) {
+      useAsyncActionCacheSerialization(navigation.cache, {
+        name: "quilt:router"
+      });
+    }
+  }
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    localization && /* @__PURE__ */ jsx(
+      HTMLAttributes,
+      {
+        lang: localization.locale,
+        dir: localization.direction
+      }
+    ),
+    /* @__PURE__ */ jsx(QuiltFrameworkContextPreact.Provider, { value: memoizedValue, children })
+  ] });
+}
+function useAsyncContext({
+  cache: asyncCache,
+  components: asyncComponents,
+  serialize: asyncSerialize = true
+} = {}) {
+  const hydratedSignal = useMemo(() => signal(false), []);
+  if (typeof document === "object") {
+    useLayoutEffect(() => {
+      hydratedSignal.value = true;
+    }, []);
+  }
+  if (typeof document !== "object") {
+    useAsyncActionCacheSerialization(asyncSerialize ? asyncCache : void 0, {
+      name: "quilt:async",
+      optional: true
+    });
+  }
+  return useMemo(
+    () => ({
+      cache: asyncCache,
+      components: asyncComponents,
+      get isHydrated() {
+        return hydratedSignal.value;
+      }
+    }),
+    [asyncCache, asyncComponents, hydratedSignal]
+  );
+}
+
+export { QuiltFrameworkContext };

package/build/esnext/context/testing.esnext

@@ -0,0 +1,33 @@
+import { jsx } from 'preact/jsx-runtime';
+import { useMemo } from 'preact/hooks';
+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';
+
+function QuiltFrameworkTestContext({
+  navigation,
+  localization = new Localization("en"),
+  browser,
+  children
+}) {
+  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 /* @__PURE__ */ jsx(QuiltFrameworkContextPreact.Provider, { value, children });
+}
+
+export { QuiltFrameworkTestContext };

package/build/esnext/context.esnext

@@ -1 +1,2 @@
-export * from '@quilted/preact-context';
+export { QuiltFrameworkContextPreact, createOptionalContext, useQuiltContext } from '@quilted/preact-context';
+export { QuiltFrameworkContext } from './context/QuiltFrameworkContext.esnext';