@quilted/preact-localize 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,248 @@
 # @quilted/react-localize
 
+## 0.4.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/preact-browser@0.2.7
+  - @quilted/preact-context@0.1.5
+  - @quilted/preact-router@0.2.16
+  - @quilted/localize@0.2.3
+
+## 0.4.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/preact-router@0.2.15
+  - @quilted/preact-context@0.1.4
+  - @quilted/localize@0.2.2
+  - @quilted/signals@0.2.4
+
 ## 0.4.0
 
 ### Minor Changes

package/build/esm/hooks/formatting.mjs

@@ -1,5 +1,7 @@
-import { LocalizedFormattingContext } from '../context.mjs';
+import { useQuiltContext } from '@quilted/preact-context';
 
-const useLocalizedFormatting = LocalizedFormattingContext.use;
+function useLocalizedFormatting() {
+  return useQuiltContext('localization');
+}
 
 export { useLocalizedFormatting };

package/build/esm/hooks/locale.mjs

@@ -1,5 +1,7 @@
-import { LocaleContext } from '../context.mjs';
+import { useQuiltContext } from '@quilted/preact-context';
 
-const useLocale = LocaleContext.use;
+function useLocale() {
+  return useQuiltContext('localization').locale;
+}
 
 export { useLocale };

package/build/esm/index.mjs

@@ -1,13 +1,10 @@
-export { MissingTranslationError, MissingTranslationPlaceholderError, createLocalizedFormatting, createTranslate, parseAcceptLanguageHeader } from '@quilted/localize';
-export { Localization } from './Localization.mjs';
+export { Localization, MissingTranslationError, MissingTranslationPlaceholderError, createTranslate, parseAcceptLanguageHeader } from '@quilted/localize';
 export { useLocalizedFormatting } from './hooks/formatting.mjs';
 export { useLocale } from './hooks/locale.mjs';
 export { useAlternateURL } from './hooks/alternate-url.mjs';
 export { AlternateURL } from './components/AlternateURL.mjs';
-export { LocalizedFormattingContext } from './context.mjs';
 export { LocalizedLink } from './routing/LocalizedLink.mjs';
 export { LocalizedNavigation } from './routing/LocalizedNavigation.mjs';
-export { LocalizedRouter } from './routing/LocalizedRouter.mjs';
 export { useRouteLocalization } from './routing/context.mjs';
 export { createRouteLocalization } from './routing/localization/by-locale.mjs';
 export { createRoutePathLocalization } from './routing/localization/by-path.mjs';

package/build/esm/routing/LocalizedLink.mjs

@@ -1,5 +1,5 @@
 import { useMemo } from 'preact/hooks';
-import { useRouter, useCurrentURL, Link } from '@quilted/preact-router';
+import { useNavigation, useCurrentURL, Link } from '@quilted/preact-router';
 import { useRouteLocalization } from './context.mjs';
 import { jsx } from 'preact/jsx-runtime';
 
@@ -8,14 +8,14 @@ function LocalizedLink({
   locale,
   ...props
 }) {
-  const router = useRouter();
+  const navigation = useNavigation();
   const url = useCurrentURL();
   const {
     redirectURL
   } = useRouteLocalization();
-  const resolvedURL = useMemo(() => redirectURL(to ? router.resolve(to).url : url, {
+  const resolvedURL = useMemo(() => redirectURL(to ? navigation.resolve(to).url : url, {
     to: locale
-  }), [to, url, locale, redirectURL, router]);
+  }), [to, url, locale, redirectURL, navigation]);
   return jsx(Link, {
     hrefLang: locale,
     to: resolvedURL,

package/build/esm/routing/LocalizedNavigation.mjs

@@ -1,47 +1,38 @@
-import { useMemo } from 'preact/hooks';
-import { useBrowserDetails } from '@quilted/preact-browser';
 import { Navigation } from '@quilted/preact-router';
-import { Localization } from '../Localization.mjs';
-import { LocalizedRouter } from './LocalizedRouter.mjs';
-import { RouteLocalizationContext } from './context.mjs';
-import { jsx } from 'preact/jsx-runtime';
 
-function LocalizedNavigation({
-  locale: explicitLocale,
-  router,
-  routes,
-  context,
-  localization,
-  children
-}) {
-  const browser = useBrowserDetails({
-    optional: true
-  });
-  const resolvedRouter = useMemo(() => router ?? new LocalizedRouter(browser?.request.url, {
-    localization: localization
-  }), [router]);
-  const resolvedLocalization = resolvedRouter.localization;
-  const localeFromEnvironment = browser?.locale.value;
-  let resolvedLocale;
-  if (explicitLocale) {
-    resolvedLocale = explicitLocale;
-  } else if (localeFromEnvironment != null && localeFromEnvironment.toLowerCase().startsWith(resolvedLocalization.locale.toLowerCase())) {
-    resolvedLocale = localeFromEnvironment;
-  } else {
-    resolvedLocale = resolvedLocalization.locale;
+class LocalizedNavigation extends Navigation {
+  get locale() {
+    return this.routes.locale;
+  }
+  constructor(initial, {
+    routes,
+    isExternal: explicitIsExternal
+  }) {
+    const {
+      localeFromURL
+    } = routes;
+    let matchedLocale;
+    super(initial, {
+      isExternal(url, currentURL) {
+        return matchedLocale !== localeFromURL(url) || (explicitIsExternal?.(url, currentURL) ?? false);
+      }
+    });
+    const currentURL = this.currentRequest.url;
+    matchedLocale = localeFromURL(currentURL);
+    const resolvedLocalization = {
+      locale: matchedLocale ?? routes.defaultLocale,
+      ...routes
+    };
+    this.routes = resolvedLocalization;
+    const {
+      pathname: rootPath
+    } = routes.redirectURL(new URL('/', currentURL), {
+      to: resolvedLocalization.locale
+    });
+    if (rootPath.length > 1) Object.assign(this, {
+      base: rootPath
+    });
   }
-  return jsx(Localization, {
-    locale: resolvedLocale,
-    children: jsx(RouteLocalizationContext.Provider, {
-      value: resolvedLocalization,
-      children: jsx(Navigation, {
-        router: resolvedRouter,
-        routes: routes,
-        context: context,
-        children: children
-      })
-    })
-  });
 }
 
 export { LocalizedNavigation };

package/build/esm/routing/context.mjs

@@ -1,6 +1,12 @@
-import { createOptionalContext } from '@quilted/preact-context';
+import { useNavigation } from '@quilted/preact-router';
+import { LocalizedNavigation } from './LocalizedNavigation.mjs';
 
-const RouteLocalizationContext = createOptionalContext();
-const useRouteLocalization = RouteLocalizationContext.use;
+function useRouteLocalization() {
+  const navigation = useNavigation();
+  if (!(navigation instanceof LocalizedNavigation)) {
+    throw new Error('useRouteLocalization() requires a LocalizedNavigation instance to be provided in context. ' + 'Make sure you are passing a LocalizedNavigation to QuiltFrameworkContext.');
+  }
+  return navigation.routes;
+}
 
-export { RouteLocalizationContext, useRouteLocalization };
+export { useRouteLocalization };

package/build/esnext/hooks/formatting.esnext

@@ -1,5 +1,7 @@
-import { LocalizedFormattingContext } from '../context.esnext';
+import { useQuiltContext } from '@quilted/preact-context';
 
-const useLocalizedFormatting = LocalizedFormattingContext.use;
+function useLocalizedFormatting() {
+  return useQuiltContext("localization");
+}
 
 export { useLocalizedFormatting };

package/build/esnext/hooks/locale.esnext

@@ -1,5 +1,7 @@
-import { LocaleContext } from '../context.esnext';
+import { useQuiltContext } from '@quilted/preact-context';
 
-const useLocale = LocaleContext.use;
+function useLocale() {
+  return useQuiltContext("localization").locale;
+}
 
 export { useLocale };

package/build/esnext/index.esnext

@@ -1,13 +1,10 @@
-export { MissingTranslationError, MissingTranslationPlaceholderError, createLocalizedFormatting, createTranslate, parseAcceptLanguageHeader } from '@quilted/localize';
-export { Localization } from './Localization.esnext';
+export { Localization, MissingTranslationError, MissingTranslationPlaceholderError, createTranslate, parseAcceptLanguageHeader } from '@quilted/localize';
 export { useLocalizedFormatting } from './hooks/formatting.esnext';
 export { useLocale } from './hooks/locale.esnext';
 export { useAlternateURL } from './hooks/alternate-url.esnext';
 export { AlternateURL } from './components/AlternateURL.esnext';
-export { LocalizedFormattingContext } from './context.esnext';
 export { LocalizedLink } from './routing/LocalizedLink.esnext';
 export { LocalizedNavigation } from './routing/LocalizedNavigation.esnext';
-export { LocalizedRouter } from './routing/LocalizedRouter.esnext';
 export { useRouteLocalization } from './routing/context.esnext';
 export { createRouteLocalization } from './routing/localization/by-locale.esnext';
 export { createRoutePathLocalization } from './routing/localization/by-path.esnext';

package/build/esnext/routing/LocalizedLink.esnext

@@ -1,6 +1,6 @@
 import { jsx } from 'preact/jsx-runtime';
 import { useMemo } from 'preact/hooks';
-import { useRouter, useCurrentURL, Link } from '@quilted/preact-router';
+import { useNavigation, useCurrentURL, Link } from '@quilted/preact-router';
 import { useRouteLocalization } from './context.esnext';
 
 function LocalizedLink({
@@ -8,12 +8,12 @@ function LocalizedLink({
   locale,
   ...props
 }) {
-  const router = useRouter();
+  const navigation = useNavigation();
   const url = useCurrentURL();
   const { redirectURL } = useRouteLocalization();
   const resolvedURL = useMemo(
-    () => redirectURL(to ? router.resolve(to).url : url, { to: locale }),
-    [to, url, locale, redirectURL, router]
+    () => redirectURL(to ? navigation.resolve(to).url : url, { to: locale }),
+    [to, url, locale, redirectURL, navigation]
   );
   return /* @__PURE__ */ jsx(Link, { hrefLang: locale, to: resolvedURL, ...props });
 }

package/build/esnext/routing/LocalizedNavigation.esnext

@@ -1,35 +1,33 @@
-import { jsx } from 'preact/jsx-runtime';
-import { useMemo } from 'preact/hooks';
-import { useBrowserDetails } from '@quilted/preact-browser';
 import { Navigation } from '@quilted/preact-router';
-import { Localization } from '../Localization.esnext';
-import { LocalizedRouter } from './LocalizedRouter.esnext';
-import { RouteLocalizationContext } from './context.esnext';
 
-function LocalizedNavigation({
-  locale: explicitLocale,
-  router,
-  routes,
-  context,
-  localization,
-  children
-}) {
-  const browser = useBrowserDetails({ optional: true });
-  const resolvedRouter = useMemo(
-    () => router ?? new LocalizedRouter(browser?.request.url, { localization }),
-    [router]
-  );
-  const resolvedLocalization = resolvedRouter.localization;
-  const localeFromEnvironment = browser?.locale.value;
-  let resolvedLocale;
-  if (explicitLocale) {
-    resolvedLocale = explicitLocale;
-  } else if (localeFromEnvironment != null && localeFromEnvironment.toLowerCase().startsWith(resolvedLocalization.locale.toLowerCase())) {
-    resolvedLocale = localeFromEnvironment;
-  } else {
-    resolvedLocale = resolvedLocalization.locale;
+class LocalizedNavigation extends Navigation {
+  routes;
+  get locale() {
+    return this.routes.locale;
+  }
+  constructor(initial, {
+    routes,
+    isExternal: explicitIsExternal
+  }) {
+    const { localeFromURL } = routes;
+    let matchedLocale;
+    super(initial, {
+      isExternal(url, currentURL2) {
+        return matchedLocale !== localeFromURL(url) || (explicitIsExternal?.(url, currentURL2) ?? false);
+      }
+    });
+    const currentURL = this.currentRequest.url;
+    matchedLocale = localeFromURL(currentURL);
+    const resolvedLocalization = {
+      locale: matchedLocale ?? routes.defaultLocale,
+      ...routes
+    };
+    this.routes = resolvedLocalization;
+    const { pathname: rootPath } = routes.redirectURL(new URL("/", currentURL), {
+      to: resolvedLocalization.locale
+    });
+    if (rootPath.length > 1) Object.assign(this, { base: rootPath });
   }
-  return /* @__PURE__ */ jsx(Localization, { locale: resolvedLocale, children: /* @__PURE__ */ jsx(RouteLocalizationContext.Provider, { value: resolvedLocalization, children: /* @__PURE__ */ jsx(Navigation, { router: resolvedRouter, routes, context, children }) }) });
 }
 
 export { LocalizedNavigation };

package/build/esnext/routing/context.esnext

@@ -1,6 +1,14 @@
-import { createOptionalContext } from '@quilted/preact-context';
+import { useNavigation } from '@quilted/preact-router';
+import { LocalizedNavigation } from './LocalizedNavigation.esnext';
 
-const RouteLocalizationContext = createOptionalContext();
-const useRouteLocalization = RouteLocalizationContext.use;
+function useRouteLocalization() {
+  const navigation = useNavigation();
+  if (!(navigation instanceof LocalizedNavigation)) {
+    throw new Error(
+      "useRouteLocalization() requires a LocalizedNavigation instance to be provided in context. Make sure you are passing a LocalizedNavigation to QuiltFrameworkContext."
+    );
+  }
+  return navigation.routes;
+}
 
-export { RouteLocalizationContext, useRouteLocalization };
+export { useRouteLocalization };