@shopify/ui-extensions-server-kit 0.0.0-snapshot-20240814205424

package/src/context/constants.ts

@@ -0,0 +1,15 @@
+import {ExtensionServerClient} from '../ExtensionServerClient'
+import {INITIAL_STATE} from '../state'
+import {noop} from '../utilities'
+import {createContext} from 'react'
+
+import type {ExtensionServerContext} from './types'
+
+export const DEFAULT_VALUE: ExtensionServerContext = {
+  connect: noop,
+  dispatch: noop,
+  state: INITIAL_STATE,
+  client: new ExtensionServerClient(),
+}
+
+export const extensionServerContext = createContext<ExtensionServerContext>(DEFAULT_VALUE)

package/src/context/index.ts

@@ -0,0 +1,3 @@
+export * from './ExtensionServerProvider'
+export * from './constants'
+export * from './types'

package/src/context/types.ts

@@ -0,0 +1,13 @@
+import type {ExtensionServerState, ExtensionServerActions} from '../state'
+
+export interface ExtensionServerContext {
+  client: ExtensionServer.Client
+  state: ExtensionServerState
+  connect(options?: ExtensionServer.Options): void
+  dispatch(action: ExtensionServerActions): void
+}
+
+export interface ExtensionServerProviderProps {
+  children?: React.ReactNode
+  options: ExtensionServer.Options
+}

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+export * from './useExtensionClient'
+export * from './useExtensionServerContext'
+export * from './useExtensionServerEvent'
+export * from './useExtensionServerState'
+export * from './useIsomorphicLayoutEffect'

package/src/hooks/useExtensionClient.ts

@@ -0,0 +1,6 @@
+import {useExtensionServerContext} from './useExtensionServerContext'
+
+export function useExtensionClient() {
+  const {client} = useExtensionServerContext()
+  return client
+}

package/src/hooks/useExtensionServerContext.ts

@@ -0,0 +1,4 @@
+import {extensionServerContext} from '../context'
+import {useContext} from 'react'
+
+export const useExtensionServerContext = () => useContext(extensionServerContext)

package/src/hooks/useExtensionServerEvent.ts

@@ -0,0 +1,11 @@
+import {useExtensionServerContext} from './useExtensionServerContext'
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect'
+
+export function useExtensionServerEvent<TEvent extends keyof ExtensionServer.InboundEvents>(
+  event: TEvent,
+  listener: ExtensionServer.EventListener<TEvent>,
+): void {
+  const {client} = useExtensionServerContext()
+
+  useIsomorphicLayoutEffect(() => client.on(event, listener), [client, event, listener])
+}

package/src/hooks/useExtensionServerState.ts

@@ -0,0 +1,6 @@
+import {extensionServerReducer, INITIAL_STATE} from '../state'
+import {useReducer} from 'react'
+
+export function useExtensionServerState() {
+  return useReducer(extensionServerReducer, INITIAL_STATE)
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,6 @@
+import {useEffect, useLayoutEffect} from 'react'
+
+const isSSR =
+  typeof window === 'undefined' || !window.navigator || /ServerSideRendering|^Deno\//.test(window.navigator.userAgent)
+
+export const useIsomorphicLayoutEffect = isSSR ? useEffect : useLayoutEffect

package/src/i18n.test.ts

@@ -0,0 +1,417 @@
+import {flattenDevExtensionTranslations, resolveDevExtensionLocale, getFlattenedLocalization} from './i18n'
+
+/**
+ * These tests were adapted from https://github.com/Shopify/checkout-web/blob/master/app/utilities/development-mode/tests/i18n-utilities.test.tsx
+ * */
+
+describe('resolveDevExtensionLocale()', () => {
+  test('returns the user locale if it is provided as a supported locale', () => {
+    const userLocale = 'fr-FR'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+        'fr-FR': {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale})
+
+    expect(extensionLocale).toBe(userLocale)
+  })
+
+  test('returns the non-regional user locale if there is no exact match with user locale', async () => {
+    const userLocale = 'de-DE'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+        'fr-FR': {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale})
+
+    expect(extensionLocale).toBe(userLocale.split('-')[0])
+  })
+
+  test("returns the shop locale if it is provided as a supported locale and there isn't a match for the user locale", () => {
+    const shopLocale = 'fr-FR'
+    const userLocale = 'de-DE'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        'fr-FR': {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale, shop: shopLocale})
+
+    expect(extensionLocale).toBe(shopLocale)
+  })
+
+  test("returns the non-regional shop locale if it is provided as a supported locale and there isn't a match for the user locale", async () => {
+    const userLocale = 'ja-JP'
+    const shopLocale = 'de-DE'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale, shop: shopLocale})
+
+    expect(extensionLocale).toBe(shopLocale.split('-')[0])
+  })
+
+  test('returns the default translation locale when no full or partial match can be for neither user nor shop locale made', async () => {
+    const userLocale = 'en-US'
+    const shopLocale = 'ja'
+    const defaultLocale = 'fi'
+
+    const localization = {
+      defaultLocale,
+      lastUpdated: Date.now(),
+      translations: {
+        'en-CA': {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+        de: {
+          greetings: {
+            hello: 'Hallo',
+          },
+        },
+        fi: {
+          greetings: {
+            hello: 'Hei',
+          },
+        },
+      },
+    }
+
+    const extensionLocale = resolveDevExtensionLocale(localization, {user: userLocale, shop: shopLocale})
+
+    expect(extensionLocale).toBe(defaultLocale)
+  })
+})
+
+describe('flattenDevExtensionTranslations()', () => {
+  test('returns flattened translation keys using a single locale', () => {
+    const resolvedLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Hello',
+    })
+  })
+
+  test('returns flattened and merged translations with fallbacks for missing keys from the default locale', () => {
+    const resolvedLocale = 'en-GB'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+          },
+        },
+        'en-GB': {
+          greetings: {
+            hello: 'Hello, UK',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Hello, UK',
+      'greetings.goodbye': 'Goodbye',
+    })
+  })
+
+  test('returns flattened and merged translations based on exact match for locale translation', () => {
+    const resolvedLocale = 'fr-CA'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+            goodbye: 'Au revoir',
+          },
+        },
+        'fr-CA': {
+          greetings: {
+            hello: 'Bonjour, Canada',
+            goodbye: 'Au revoir, Canada',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Bonjour, Canada',
+      'greetings.goodbye': 'Au revoir, Canada',
+    })
+  })
+
+  test('returns flattened and merged translations based on non-regional match for locale translation', () => {
+    const resolvedLocale = 'fr-CA'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+            sorry: 'Sorry',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+            goodbye: 'Au revoir',
+            sorry: 'Désolé',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Bonjour',
+      'greetings.goodbye': 'Au revoir',
+      'greetings.sorry': 'Désolé',
+    })
+  })
+
+  test('returns the flattened default locale where no locale match is possible (full or non-regional)', () => {
+    const resolvedLocale = 'de'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+            goodbye: 'Goodbye',
+            sorry: 'Sorry',
+          },
+        },
+        fr: {
+          greetings: {
+            hello: 'Bonjour',
+            goodbye: 'Au revoir',
+            sorry: 'Désolé',
+          },
+        },
+        'de-DE': {
+          greetings: {
+            hello: 'Hallo',
+            goodbye: 'Auf Wiedersehen',
+            sorry: ' Entschuldigung',
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'greetings.hello': 'Hello',
+      'greetings.goodbye': 'Goodbye',
+      'greetings.sorry': 'Sorry',
+    })
+  })
+
+  test('returns flattened translations with pluralizations', () => {
+    const resolvedLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          pluralExample: {
+            one: 'You have {{count}} apple',
+            other: 'You have {{count}} apples',
+          },
+          example: {
+            of: {
+              nestedTranslation: 'This is a nested translation only in the default locale',
+              anotherNestedTranslation: 'This is another nested translation defined in the default locale',
+            },
+          },
+        },
+      },
+    }
+
+    const flattenedTranslations = flattenDevExtensionTranslations(localization, resolvedLocale)
+
+    expect(flattenedTranslations).toStrictEqual({
+      'pluralExample.one': 'You have {{count}} apple',
+      'pluralExample.other': 'You have {{count}} apples',
+      'example.of.nestedTranslation': 'This is a nested translation only in the default locale',
+      'example.of.anotherNestedTranslation': 'This is another nested translation defined in the default locale',
+    })
+  })
+})
+
+describe('getFlattenedLocalization()', () => {
+  test('returns flattened translations string and resolved extension locale when locales options are provided', () => {
+    const userLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+      },
+    }
+
+    const flattenedLocalization = getFlattenedLocalization(localization, {user: userLocale})
+
+    expect(flattenedLocalization).toStrictEqual({
+      extensionLocale: userLocale,
+      translations: '{"greetings.hello":"Hello"}',
+      lastUpdated: localization.lastUpdated,
+    })
+  })
+
+  test('return undefined when locales options are not provided', () => {
+    const userLocale = 'en'
+
+    const localization = {
+      defaultLocale: 'en',
+      lastUpdated: Date.now(),
+      translations: {
+        en: {
+          greetings: {
+            hello: 'Hello',
+          },
+        },
+      },
+    }
+
+    const flattenedLocalization = getFlattenedLocalization(localization)
+
+    expect(flattenedLocalization).toBeUndefined()
+  })
+
+  test('return undefined when localization is null', () => {
+    const userLocale = 'en'
+    const flattenedLocalization = getFlattenedLocalization(null, {user: userLocale})
+
+    expect(flattenedLocalization).toBeUndefined()
+  })
+
+  test('return flattened localization if localization is already flattened', () => {
+    const userLocale = 'en'
+
+    const localization = {
+      extensionLocale: userLocale,
+      lastUpdated: Date.now(),
+      translations: '{"greetings.hello":"Hello"}',
+    }
+
+    const flattenedLocalization = getFlattenedLocalization(localization, {user: userLocale})
+
+    expect(flattenedLocalization).toStrictEqual(localization)
+  })
+})

package/src/i18n.ts

@@ -0,0 +1,208 @@
+/**
+ * These translation utilities were adapted from https://github.com/Shopify/checkout-web/blob/master/app/utilities/development-mode/i18n-utilities.tsx
+ * */
+
+type Translation = string | {[key: string]: Translation}
+
+export interface Localization {
+  defaultLocale: string
+  translations: {[key: string]: {[key: string]: Translation}}
+  lastUpdated: number
+}
+
+export interface FlattenedLocalization {
+  extensionLocale: string
+  translations: string
+  lastUpdated: number
+}
+
+export interface LocalesOptions {
+  user: string
+  shop?: string
+}
+
+export interface TranslationDictionary {
+  [key: string]: string | TranslationDictionary
+}
+
+/**
+ * This is a flattened dictionary of extension translations for the active locale.
+ *
+ * Here are some examples for the 'en' locale.
+ *
+ * Nested keys are dot separated. Consider this translation definition:
+ *
+ * ```
+ * {
+ *   "greetings": {
+ *     "hello": "Hello {{user}}"
+ *   }
+ * }
+ * ```
+ *
+ * It would be represented in this flattened dictionary as:
+ * ```
+ * {
+ *   "greetings.hello": "Hello {{user}}"
+ * }
+ * ```
+ * Pluralized translations will also be flattened. Consider this definition:
+ * ```
+ * {
+ *   "loyaltyPointsRemaining": {
+ *     "one": "You have {{count}} loyalty point",
+ *     "other": "You have {{count}} loyalty points",
+ *   }
+ * }
+ * ```
+ * It would be represented in this flattened dictionary as:
+ * ```
+ * {
+ *   "loyaltyPointsRemaining.one":  "You have {{count}} loyalty point",
+ *   "loyaltyPointsRemaining.other": "You have {{count}} loyalty points",
+ * }
+ * ```
+ */
+export interface ExtensionTranslationMap {
+  [key: string]: string
+}
+
+export const TRANSLATED_KEYS = ['localization', 'name', 'description']
+/**
+ * From a nested dictionary like the following :
+ *
+ * ```typescript
+ * const dictionary = {
+ *   Foo: {
+ *     Bar: {
+ *        fooBar: 'something'
+ *     }
+ *   }
+ * }
+ *
+ * Returns a map containing this pair : {'Foo.Bar.fooBar': 'something'}
+ * ```
+ */
+export function dictionaryToFlatMap(dictionary: TranslationDictionary) {
+  const map = new Map<string, string>()
+
+  traverseDictionary(dictionary, (key, value) => map.set(key, value))
+
+  return map
+}
+
+function traverseDictionary(
+  dictionary: TranslationDictionary,
+  callback: (key: string, value: string) => void,
+  keyPrefix?: string,
+) {
+  Object.keys(dictionary).forEach((key: string) => {
+    const value = dictionary[key]
+    const translationKey = keyPrefix ? `${keyPrefix}.${key}` : key
+
+    if (value == null) {
+      return
+    }
+
+    if (typeof value === 'string') {
+      // eslint-disable-next-line node/callback-return
+      callback(translationKey, value)
+    } else {
+      traverseDictionary(value, callback, translationKey)
+    }
+  })
+}
+
+export function flattenDevExtensionTranslations(localization: Localization, locale: string): ExtensionTranslationMap {
+  const defaultTranslations = getFlatMap(localization.translations[localization.defaultLocale])
+
+  const nonRegionalLocale = getNonRegionalLocale(locale)
+  const nonRegionalTranslations = getFlatMap(localization.translations[nonRegionalLocale])
+
+  const userLocaleTranslations = getFlatMap(localization.translations[locale])
+
+  return convertMapToExtensionTranslationMap(
+    new Map([...defaultTranslations, ...nonRegionalTranslations, ...userLocaleTranslations]),
+  )
+}
+
+function getFlatMap(translationDictionary: TranslationDictionary | undefined) {
+  if (translationDictionary) {
+    return dictionaryToFlatMap(translationDictionary)
+  }
+  return new Map<string, string>()
+}
+
+export function resolveDevExtensionLocale(
+  localization: Localization,
+  locales: {
+    user: string
+    shop?: string
+  },
+): string {
+  const extensionLocales = new Set(Object.keys(localization.translations))
+
+  // 0. If no translations, use the user's locale
+  if (extensionLocales.size === 0) return locales.user
+
+  // 1. Attempt to match the user's locale exactly
+  if (extensionLocales.has(locales.user)) return locales.user
+
+  // 2. Attempt to match the non-regional part of the user's locale (i.e. 'fr-CA' becomes 'fr')
+  const nonRegionalUserLocale = getNonRegionalLocale(locales.user)
+  if (extensionLocales.has(nonRegionalUserLocale)) return nonRegionalUserLocale
+
+  // 3. Attempt to match the shop's default locale exactly
+  if (locales.shop && extensionLocales.has(locales.shop)) return locales.shop
+
+  // 4. Attempt to match the non-regional part of the shop's default locale (i.e. 'fr-CA' becomes 'fr')
+  const nonRegionalShopLocale = locales.shop && getNonRegionalLocale(locales.shop)
+  if (nonRegionalShopLocale && extensionLocales.has(nonRegionalShopLocale)) return nonRegionalShopLocale
+
+  // 5. Finally, return the default locale as a fallback
+  return localization.defaultLocale
+}
+
+function convertMapToExtensionTranslationMap(map: Map<string, string>): ExtensionTranslationMap {
+  const extTransMap: ExtensionTranslationMap = {}
+  for (const [key, value] of map) {
+    extTransMap[key] = value
+  }
+  return extTransMap
+}
+
+function getNonRegionalLocale(locale: string): string {
+  return locale.split('-')[0]
+}
+
+export function getFlattenedLocalization(
+  localization?: FlattenedLocalization | Localization | null,
+  locales?: LocalesOptions,
+) {
+  if (!localization || !locales) {
+    return
+  }
+
+  if (isFlattenedTranslations(localization)) {
+    return localization
+  }
+
+  const extensionLocale = resolveDevExtensionLocale(localization, locales)
+  const translations = JSON.stringify(flattenDevExtensionTranslations(localization, extensionLocale))
+
+  const flattenedLocalization: FlattenedLocalization = {
+    extensionLocale,
+    translations,
+    lastUpdated: localization.lastUpdated,
+  }
+  return flattenedLocalization
+}
+
+export function isFlattenedTranslations(
+  localization: Localization | FlattenedLocalization,
+): localization is FlattenedLocalization {
+  return (
+    typeof localization.translations === 'string' &&
+    Object.prototype.hasOwnProperty.call(localization, 'extensionLocale')
+  )
+}