@sonenta/astro 0.1.0 → 0.2.0

package/dist/runtime.js

@@ -1,19 +1,29 @@
 import {
+  DEFAULT_SURFACE_BREAKPOINTS,
   buildBundleUrl,
+  buildOverlayUrl,
   createSonentaI18n,
   createT,
   fetchAll,
+  fetchAllOverlays,
   fetchBundle,
   fetchNamespace,
-  resolveCdnBase
-} from "./chunk-CK2DAB6G.js";
+  fetchOverlay,
+  resolveCdnBase,
+  surfaceForWidth
+} from "./chunk-RG6KTECT.js";
 export {
+  DEFAULT_SURFACE_BREAKPOINTS,
   buildBundleUrl,
+  buildOverlayUrl,
   createSonentaI18n,
   createT,
   fetchAll,
+  fetchAllOverlays,
   fetchBundle,
   fetchNamespace,
-  resolveCdnBase
+  fetchOverlay,
+  resolveCdnBase,
+  surfaceForWidth
 };
 //# sourceMappingURL=runtime.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonenta/astro",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official Astro integration for Sonenta i18n — build-time CDN translations, zero client JS (SSG).",
   "license": "MIT",
   "homepage": "https://sonenta.com",
@@ -31,10 +31,12 @@
       "types": "./dist/runtime.d.ts",
       "import": "./dist/runtime.js",
       "require": "./dist/runtime.cjs"
-    }
+    },
+    "./SurfaceText.astro": "./SurfaceText.astro"
   },
   "files": [
     "dist",
+    "SurfaceText.astro",
     "README.md",
     "CONTRACT.md",
     "LICENSE"

package/dist/chunk-CK2DAB6G.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/types.ts","../src/cdn.ts","../src/resolver.ts"],"sourcesContent":["/**\n * Public types for `@sonenta/astro` v0.1 (standalone, pre-core).\n *\n * FORWARD-COMPATIBILITY CONTRACT (frozen day-one — see CONTRACT.md): every\n * option key here is the SAME key the future `@sonenta/i18n-core`-backed\n * release will consume, so the later refactor (0.2.0) is a non-breaking,\n * additive internal swap. New capabilities (surfaces, a11y accessors, CLDR\n * plurals, variants) arrive ADDITIVELY; nothing here changes meaning.\n */\n\n/** A BCP-47 locale code, e.g. `\"fr\"`, `\"en\"`, `\"fr-CA\"`. */\nexport type Locale = string;\n\n/** A bundle namespace (the `{ns}.json` file on the CDN), e.g. `\"common\"`. */\nexport type Namespace = string;\n\n/** Interpolation variables for a `t()` call: `t(\"greeting\", { name: \"Ada\" })`. */\nexport type Vars = Record<string, string | number>;\n\n/** A resolved, per-locale translation function. */\nexport type TFn = (key: string, vars?: Vars) => string;\n\n/**\n * Configuration for the Sonenta Astro integration / runtime.\n *\n * Bundles are fetched at BUILD time from\n * `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`\n * (the canonical Sonenta CDN layout, identical to `@sonenta/react-i18next`).\n */\nexport interface SonentaI18nOptions {\n  /** Project UUID from your Sonenta dashboard. Required. */\n  project: string;\n\n  /**\n   * Released version slug or pinned content hash. Default `\"main\"`.\n   * The CDN serves the latest release of this version under `/latest/`.\n   */\n  version?: string;\n\n  /**\n   * Locales to fetch and freeze into the static build. Required, non-empty.\n   * A locale whose bundle 404s (e.g. a plan-limit-blocked language) is kept\n   * as `null` and transparently falls back to the source language.\n   */\n  locales: Locale[];\n\n  /**\n   * Source / default locale. Default = `locales[0]`. Used as the implicit\n   * final fallback target and as Astro's source language.\n   */\n  defaultLocale?: Locale;\n\n  /**\n   * Ordered fallback chain applied when a key is missing in the active\n   * locale. Default = `[defaultLocale]`. v0.1 applies these locales in\n   * order; BCP-47 variant→base inheritance (`fr-CA → fr`) is deliberately\n   * left to the core-backed release.\n   */\n  fallbackLng?: Locale | Locale[];\n\n  /**\n   * Namespaces (bundle files) to fetch. Default `[\"common\"]`. The first\n   * entry is the default namespace for un-prefixed keys; address others with\n   * the i18next-style `\"ns:key\"` syntax.\n   */\n  namespaces?: Namespace[];\n\n  /**\n   * CDN host root for translation bundles, WITHOUT the `/p` segment.\n   * Default `\"https://cdn.sonenta.com\"`. Overridable via the\n   * `SONENTA_CDN_BASE` env var (also a bare host; for local dev point it at\n   * your translation CDN). The `/p/{project}/{version}/latest/...` path is\n   * appended by the loader.\n   */\n  cdnBase?: string;\n\n  /**\n   * API host root. Reserved for forward-compatibility (the core-backed\n   * release uses it for the public language manifest and dev-mode runtime\n   * fetch). Default `\"https://api.sonenta.dev\"`. Unused by v0.1's prod\n   * build-time path.\n   */\n  apiBase?: string;\n\n  /**\n   * Injectable `fetch` implementation (testing / proxies / custom agents).\n   * Defaults to the global `fetch`.\n   */\n  fetchImpl?: typeof fetch;\n}\n\n/**\n * The resolved Sonenta i18n handle returned by `createSonentaI18n` and\n * exposed through the `sonenta:i18n` virtual module.\n */\nexport interface SonentaI18n {\n  /** Build a translation function bound to `locale`. */\n  getT(locale: Locale): TFn;\n  /** The locales that were fetched (the configured `locales`). */\n  readonly locales: Locale[];\n  /** The resolved source/default locale. */\n  readonly defaultLocale: Locale;\n  /**\n   * Raw fetched dictionary for `locale` / `namespace` (default namespace when\n   * omitted), or `null` when that bundle was absent (404 / plan-limit).\n   */\n  getCatalog(locale: Locale, namespace?: Namespace): Record<string, unknown> | null;\n}\n\n/** Default CDN host (no `/p`). */\nexport const DEFAULT_CDN_BASE = \"https://cdn.sonenta.com\";\n/** Default API host. */\nexport const DEFAULT_API_BASE = \"https://api.sonenta.dev\";\n/** Default version slug. */\nexport const DEFAULT_VERSION = \"main\";\n/** Default namespace. */\nexport const DEFAULT_NAMESPACE = \"common\";\n","/**\n * Build-time CDN loader for Sonenta translation bundles.\n *\n * Mirrors the canonical Sonenta CDN layout used by `@sonenta/react-i18next`:\n *   `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`\n *\n * Pure data fetch — no DOM, no React, no runtime. Called during `astro build`\n * so the strings inline into the static HTML (zero client JS).\n */\n\nimport {\n  DEFAULT_CDN_BASE,\n  DEFAULT_VERSION,\n  type Locale,\n  type Namespace,\n  type SonentaI18nOptions,\n} from \"./types\";\n\n/** A fetched bundle (a flat or nested dictionary of message strings). */\nexport type Bundle = Record<string, unknown>;\n\n/** Strip trailing slashes so URL joins never double up. */\nfunction trimSlashes(s: string): string {\n  return s.replace(/\\/+$/, \"\");\n}\n\n/**\n * Resolve the effective CDN host (no `/p`): explicit option wins, then the\n * `SONENTA_CDN_BASE` env var, then the production default.\n */\nexport function resolveCdnBase(opts: Pick<SonentaI18nOptions, \"cdnBase\">): string {\n  const env =\n    typeof process !== \"undefined\" ? process.env?.SONENTA_CDN_BASE : undefined;\n  return trimSlashes(opts.cdnBase ?? env ?? DEFAULT_CDN_BASE);\n}\n\n/**\n * Build the bundle URL for one `(locale, namespace)` pair.\n * `{cdnBase}/p/{project}/{version}/latest/{locale}/{namespace}.json`\n */\nexport function buildBundleUrl(\n  opts: Pick<SonentaI18nOptions, \"project\" | \"version\" | \"cdnBase\">,\n  locale: Locale,\n  namespace: Namespace,\n): string {\n  const base = resolveCdnBase(opts);\n  const version = opts.version ?? DEFAULT_VERSION;\n  return `${base}/p/${opts.project}/${version}/latest/${locale}/${namespace}.json`;\n}\n\n/**\n * Fetch a single bundle. Resolves to `null` on 404 (locale absent from the\n * project — e.g. a plan-limit-blocked language) so callers fall back to the\n * source language. Any other non-OK status or transport error throws so a\n * misconfigured build fails loudly rather than silently shipping empty pages.\n */\nexport async function fetchBundle(\n  opts: Pick<SonentaI18nOptions, \"project\" | \"version\" | \"cdnBase\" | \"fetchImpl\">,\n  locale: Locale,\n  namespace: Namespace,\n): Promise<Bundle | null> {\n  const url = buildBundleUrl(opts, locale, namespace);\n  const doFetch = opts.fetchImpl ?? fetch;\n  let res: Response;\n  try {\n    res = await doFetch(url, { method: \"GET\" });\n  } catch (e) {\n    throw new Error(\n      `[@sonenta/astro] CDN fetch failed for ${locale}/${namespace}: ${\n        (e as Error).message\n      }`,\n    );\n  }\n  if (!res.ok) {\n    if (res.status === 404) return null;\n    throw new Error(`[@sonenta/astro] CDN ${res.status} on ${url}`);\n  }\n  return (await res.json()) as Bundle;\n}\n\n/**\n * Fetch one namespace across every locale, in parallel. Absent locales map to\n * `null`. Returns `Record<Locale, Bundle | null>`.\n */\nexport async function fetchNamespace(\n  opts: Pick<\n    SonentaI18nOptions,\n    \"project\" | \"version\" | \"cdnBase\" | \"fetchImpl\"\n  >,\n  locales: Locale[],\n  namespace: Namespace,\n): Promise<Record<Locale, Bundle | null>> {\n  const entries = await Promise.all(\n    locales.map(\n      async (l) => [l, await fetchBundle(opts, l, namespace)] as const,\n    ),\n  );\n  return Object.fromEntries(entries) as Record<Locale, Bundle | null>;\n}\n\n/**\n * Fetch every `(locale, namespace)` pair. Returns a nested map keyed by\n * locale then namespace: `data[locale][namespace] = Bundle | null`.\n */\nexport async function fetchAll(\n  opts: Pick<\n    SonentaI18nOptions,\n    \"project\" | \"version\" | \"cdnBase\" | \"fetchImpl\"\n  >,\n  locales: Locale[],\n  namespaces: Namespace[],\n): Promise<Record<Locale, Record<Namespace, Bundle | null>>> {\n  const out: Record<Locale, Record<Namespace, Bundle | null>> = {};\n  for (const l of locales) out[l] = {};\n  await Promise.all(\n    locales.flatMap((l) =>\n      namespaces.map(async (ns) => {\n        out[l]![ns] = await fetchBundle(opts, l, ns);\n      }),\n    ),\n  );\n  return out;\n}\n","/**\n * Build-time translation resolver.\n *\n * v0.1 SCOPE (frozen — see CONTRACT.md): string resolution + `{var}`\n * interpolation + source-language fallback ONLY. Deliberately NO CLDR\n * plurals, NO surfaces, NO a11y accessors, NO BCP-47 variant→base\n * inheritance — those carry real i18n SEMANTICS owned by `@sonenta/i18n-core`\n * and arrive additively in 0.2.0. Keeping them out of v0.1 means there is no\n * naive semantics to break when the core swaps in underneath this same API.\n */\n\nimport { fetchAll, type Bundle } from \"./cdn\";\nimport {\n  DEFAULT_NAMESPACE,\n  type Locale,\n  type Namespace,\n  type SonentaI18n,\n  type SonentaI18nOptions,\n  type TFn,\n  type Vars,\n} from \"./types\";\n\n/** Normalize `fallbackLng` (scalar | array | undefined) into a locale list. */\nfunction normalizeFallback(\n  fallbackLng: SonentaI18nOptions[\"fallbackLng\"],\n  defaultLocale: Locale,\n): Locale[] {\n  if (fallbackLng == null) return [defaultLocale];\n  return Array.isArray(fallbackLng) ? fallbackLng : [fallbackLng];\n}\n\n/** Split an i18next-style `\"ns:key\"` into `[namespace, key]`. */\nfunction splitKey(key: string, defaultNamespace: Namespace): [Namespace, string] {\n  const i = key.indexOf(\":\");\n  if (i === -1) return [defaultNamespace, key];\n  return [key.slice(0, i), key.slice(i + 1)];\n}\n\n/** Walk a dotted path (`\"home.title\"`) through a bundle; `undefined` on miss. */\nfunction walk(bundle: Bundle | null | undefined, path: string): unknown {\n  if (!bundle) return undefined;\n  let cursor: unknown = bundle;\n  for (const part of path.split(\".\")) {\n    if (cursor && typeof cursor === \"object\" && part in cursor) {\n      cursor = (cursor as Record<string, unknown>)[part];\n    } else {\n      return undefined;\n    }\n  }\n  return cursor;\n}\n\n/** Substitute `{var}` placeholders; unknown placeholders are left intact. */\nfunction interpolate(template: string, vars?: Vars): string {\n  if (!vars) return template;\n  return template.replace(/\\{(\\w+)\\}/g, (_, name: string) =>\n    name in vars ? String(vars[name]) : `{${name}}`,\n  );\n}\n\n/**\n * Build a `t()` bound to `locale`, given the fetched data and resolution\n * order. Lookup: active locale's namespace dict → each fallback locale's same\n * namespace dict → the raw key (i18next-parity missing-key behaviour).\n */\nexport function createT(\n  data: Record<Locale, Record<Namespace, Bundle | null>>,\n  locale: Locale,\n  fallbackChain: Locale[],\n  defaultNamespace: Namespace,\n): TFn {\n  // De-duped resolution order: active locale first, then configured\n  // fallbacks (skipping the active one if it reappears).\n  const order = [locale, ...fallbackChain.filter((l) => l !== locale)];\n  return function t(key: string, vars?: Vars): string {\n    const [ns, rest] = splitKey(key, defaultNamespace);\n    for (const l of order) {\n      const hit = walk(data[l]?.[ns], rest);\n      if (typeof hit === \"string\") return interpolate(hit, vars);\n    }\n    // Missing everywhere → return the raw key (unchanged), i18next-style.\n    return key;\n  };\n}\n\n/**\n * Fetch every configured bundle at build time and return a resolved\n * {@link SonentaI18n} handle. Call once (top-level `await`) and reuse its\n * `getT(locale)` across pages.\n */\nexport async function createSonentaI18n(\n  options: SonentaI18nOptions,\n): Promise<SonentaI18n> {\n  if (!options.project) {\n    throw new Error(\"[@sonenta/astro] `project` (UUID) is required.\");\n  }\n  if (!options.locales?.length) {\n    throw new Error(\"[@sonenta/astro] `locales` must be a non-empty array.\");\n  }\n  const locales = options.locales;\n  const defaultLocale = options.defaultLocale ?? locales[0]!;\n  const namespaces =\n    options.namespaces?.length ? options.namespaces : [DEFAULT_NAMESPACE];\n  const defaultNamespace = namespaces[0]!;\n  const fallbackChain = normalizeFallback(options.fallbackLng, defaultLocale);\n\n  const data = await fetchAll(options, locales, namespaces);\n\n  return {\n    locales,\n    defaultLocale,\n    getT(locale: Locale): TFn {\n      return createT(data, locale, fallbackChain, defaultNamespace);\n    },\n    getCatalog(locale: Locale, namespace?: Namespace): Bundle | null {\n      return data[locale]?.[namespace ?? defaultNamespace] ?? null;\n    },\n  };\n}\n"],"mappings":"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","names":[]}