@devslab/site-kit 0.4.1 → 0.5.1

package/src/core/locales.mjs

@@ -15,22 +15,89 @@ export const LOCALES = Object.freeze([
   { code: "ar", language: "Arabic", nativeName: "العربية", dir: "rtl" },
 ]);
 
-const byLower = new Map(LOCALES.map((locale) => [locale.code.toLowerCase(), locale]));
-const aliases = new Map([["zh", "zh-TW"], ["pt", "pt-BR"]]);
+const FAMILY_ALIASES = Object.freeze([["zh", "zh-TW"], ["pt", "pt-BR"]]);
 
-export function canonicalLocale(candidate) {
-  if (!candidate) return undefined;
-  const exact = byLower.get(String(candidate).trim().toLowerCase());
-  if (exact) return exact.code;
-  const base = String(candidate).trim().toLowerCase().split("-")[0];
-  if (aliases.has(base)) return aliases.get(base);
-  return byLower.get(base)?.code;
-}
+/**
+ * The languages a site actually sells in.
+ *
+ * The list above is the family's — what devslab.kr markets in, and the
+ * floor every product gets for free. It is not every product's list.
+ * BookLinq sells to salons in India and its assistant already answers in
+ * Tamil, Telugu, Bengali, Marathi, Gujarati and Kannada. Those are not
+ * family languages and are not going to become family languages: putting
+ * them in the list above would hand AskLinq and devslab.kr six entries
+ * they have no copy for. But a BookLinq page that cannot render them is a
+ * page that lies about what the product does.
+ *
+ * So the family owns the mechanism and the product names its own nouns. A
+ * registry is the family list plus whatever a product adds, and every
+ * locale-aware helper here can be bound to one. The bare exports at the
+ * bottom are the family registry, so a consumer that never calls this
+ * sees exactly what it saw before.
+ *
+ * An extra locale carries the same fields as a family one plus
+ * `flagCountry`, naming a flag this package already vendors (`FLAG_COUNTRY`
+ * lists them). Products do not ship SVG: flag data is licensed, generated
+ * and security-scanned here, and seven Indian languages share one flag
+ * anyway.
+ *
+ * @param {{ extra?: ReadonlyArray<object>, aliases?: ReadonlyArray<[string, string]> }} [options]
+ */
+export function defineLocaleRegistry(options = {}) {
+  const extra = options.extra ?? [];
+  const seen = new Set(LOCALES.map(({ code }) => code));
+  for (const locale of extra) {
+    if (!locale?.code) throw new TypeError("every extra locale needs a code");
+    if (seen.has(locale.code)) {
+      throw new RangeError(`${locale.code} is already a family locale — remove it from \`extra\``);
+    }
+    if (!locale.nativeName) throw new TypeError(`${locale.code} needs a nativeName — it is what the picker shows`);
+    if (locale.dir !== "ltr" && locale.dir !== "rtl") throw new RangeError(`${locale.code} needs dir "ltr" or "rtl"`);
+    seen.add(locale.code);
+  }
+
+  const locales = Object.freeze([...LOCALES, ...extra.map((locale) => Object.freeze({ ...locale }))]);
+  const byLower = new Map(locales.map((locale) => [locale.code.toLowerCase(), locale]));
+  const aliases = new Map([...FAMILY_ALIASES, ...(options.aliases ?? [])]);
+
+  function canonicalLocale(candidate) {
+    if (!candidate) return undefined;
+    const exact = byLower.get(String(candidate).trim().toLowerCase());
+    if (exact) return exact.code;
+    const base = String(candidate).trim().toLowerCase().split("-")[0];
+    if (aliases.has(base)) return aliases.get(base);
+    return byLower.get(base)?.code;
+  }
+
+  function definitionFor(locale) {
+    const canonical = canonicalLocale(locale);
+    if (!canonical) throw new RangeError(`Unsupported locale: ${locale}`);
+    return byLower.get(canonical.toLowerCase());
+  }
+
+  function localeAttributes(locale) {
+    const definition = definitionFor(locale);
+    // `dir` comes off the definition rather than a test for Arabic. The
+    // old form read `canonical === "ar" ? "rtl" : "ltr"`, which was right
+    // only while Arabic stayed the family's one RTL language — a product
+    // adding Urdu or Hebrew would have had it rendered left-to-right with
+    // every test still green.
+    return { lang: definition.code, dir: definition.dir };
+  }
 
-export function localeAttributes(locale) {
-  const canonical = canonicalLocale(locale);
-  if (!canonical) throw new RangeError(`Unsupported locale: ${locale}`);
-  return { lang: canonical, dir: canonical === "ar" ? "rtl" : "ltr" };
+  function resolveLocale({ pathname = "/", cookie = "", acceptLanguage = "", defaultLocale }) {
+    const routeLocale = canonicalLocale(pathname.split("/").filter(Boolean)[0]);
+    if (routeLocale) return { locale: routeLocale, source: "route" };
+    const storedLocale = canonicalLocale(cookieValue(cookie, "locale"));
+    if (storedLocale) return { locale: storedLocale, source: "cookie" };
+    const accepted = acceptedLocales(acceptLanguage, canonicalLocale)[0]?.locale;
+    if (accepted) return { locale: accepted, source: "accept-language" };
+    const fallback = canonicalLocale(defaultLocale);
+    if (!fallback) throw new RangeError(`Unsupported default locale: ${defaultLocale}`);
+    return { locale: fallback, source: "default" };
+  }
+
+  return Object.freeze({ LOCALES: locales, canonicalLocale, localeAttributes, resolveLocale, definitionFor });
 }
 
 function cookieValue(header, name) {
@@ -45,7 +112,7 @@ function cookieValue(header, name) {
   return undefined;
 }
 
-function acceptedLocales(header) {
+function acceptedLocales(header, canonicalLocale) {
   return String(header ?? "").split(",").map((part, order) => {
     const [tag, ...parameters] = part.trim().split(";");
     const q = Number(parameters.find((parameter) => parameter.trim().startsWith("q="))?.split("=")[1] ?? 1);
@@ -53,14 +120,7 @@ function acceptedLocales(header) {
   }).filter(({ locale, q }) => locale && q > 0).sort((a, b) => b.q - a.q || a.order - b.order);
 }
 
-export function resolveLocale({ pathname = "/", cookie = "", acceptLanguage = "", defaultLocale }) {
-  const routeLocale = canonicalLocale(pathname.split("/").filter(Boolean)[0]);
-  if (routeLocale) return { locale: routeLocale, source: "route" };
-  const storedLocale = canonicalLocale(cookieValue(cookie, "locale"));
-  if (storedLocale) return { locale: storedLocale, source: "cookie" };
-  const accepted = acceptedLocales(acceptLanguage)[0]?.locale;
-  if (accepted) return { locale: accepted, source: "accept-language" };
-  const fallback = canonicalLocale(defaultLocale);
-  if (!fallback) throw new RangeError(`Unsupported default locale: ${defaultLocale}`);
-  return { locale: fallback, source: "default" };
-}
+/** The family registry — what every helper in this package uses by default. */
+export const FAMILY_LOCALES = defineLocaleRegistry();
+
+export const { canonicalLocale, localeAttributes, resolveLocale } = FAMILY_LOCALES;

package/src/core/seo.d.mts

@@ -1,16 +1,16 @@
-import type { SiteLocale, TextDirection } from "./locales.mjs";
-export interface MetadataInput { baseUrl: string; path: string; locale: SiteLocale; defaultLocale: SiteLocale; title: string; description: string; siteName: string; image: string }
-export interface SiteMetadata {
-  html: { lang: SiteLocale; dir: TextDirection };
+import type { LocaleRegistry, SiteLocale, TextDirection } from "./locales.mjs";
+export interface MetadataInput<Code extends string = SiteLocale> { baseUrl: string; path: string; locale: Code; defaultLocale: Code; title: string; description: string; siteName: string; image: string; registry?: LocaleRegistry<Code> }
+export interface SiteMetadata<Code extends string = SiteLocale> {
+  html: { lang: Code; dir: TextDirection };
   title: string; description: string; canonical: string;
-  alternates: Array<{ hreflang: SiteLocale | "x-default"; href: string }>;
-  openGraph: { type: "website"; locale: SiteLocale; url: string; siteName: string; title: string; description: string; images: Array<{ url: string }> };
+  alternates: Array<{ hreflang: Code | "x-default"; href: string }>;
+  openGraph: { type: "website"; locale: Code; url: string; siteName: string; title: string; description: string; images: Array<{ url: string }> };
   twitter: { card: "summary_large_image"; title: string; description: string; image: string };
 }
-export declare function localizedPath(path: string, locale: SiteLocale, defaultLocale: SiteLocale): string;
-export declare function localizedUrl(baseUrl: string, path: string, locale: SiteLocale, defaultLocale: SiteLocale): string;
-export declare function buildMetadata(input: MetadataInput): SiteMetadata;
-export declare function buildSitemap(input: { baseUrl: string; routes: string[]; defaultLocale: SiteLocale; lastModified?: string }): Array<{ loc: string; locale: SiteLocale; alternates: Array<{ hreflang: SiteLocale | "x-default"; href: string }>; lastmod?: string }>;
+export declare function localizedPath<Code extends string = SiteLocale>(path: string, locale: Code, defaultLocale: Code, registry?: LocaleRegistry<Code>): string;
+export declare function localizedUrl<Code extends string = SiteLocale>(baseUrl: string, path: string, locale: Code, defaultLocale: Code, registry?: LocaleRegistry<Code>): string;
+export declare function buildMetadata<Code extends string = SiteLocale>(input: MetadataInput<Code>): SiteMetadata<Code>;
+export declare function buildSitemap<Code extends string = SiteLocale>(input: { baseUrl: string; routes: string[]; defaultLocale: Code; lastModified?: string; registry?: LocaleRegistry<Code> }): Array<{ loc: string; locale: Code; alternates: Array<{ hreflang: Code | "x-default"; href: string }>; lastmod?: string }>;
 export declare function renderSitemapXml(entries: ReturnType<typeof buildSitemap>): string;
 export type RobotsPolicy = "allow" | "disallow";
 export declare const ROBOTS_USER_AGENTS: { readonly citation: readonly string[]; readonly modelTraining: readonly string[] };

package/src/core/seo.mjs

@@ -1,4 +1,10 @@
-import { LOCALES, canonicalLocale, localeAttributes } from "./locales.mjs";
+import { FAMILY_LOCALES } from "./locales.mjs";
+
+// Every function here that names a locale takes an optional `registry`.
+// Omitted it is the family's fourteen, which is what a family site wants.
+// A product that added its own languages must pass its registry, or the
+// hreflang alternates and the sitemap would quietly omit them — the page
+// would render in Tamil while telling search engines Tamil does not exist.
 
 const cleanBase = (baseUrl) => String(baseUrl).replace(/\/+$/, "");
 const cleanPath = (path) => {
@@ -6,27 +12,27 @@ const cleanPath = (path) => {
   return value === "/" ? "/" : value;
 };
 
-export function localizedPath(path, locale, defaultLocale) {
-  const canonical = canonicalLocale(locale);
-  const fallback = canonicalLocale(defaultLocale);
+export function localizedPath(path, locale, defaultLocale, registry = FAMILY_LOCALES) {
+  const canonical = registry.canonicalLocale(locale);
+  const fallback = registry.canonicalLocale(defaultLocale);
   if (!canonical || !fallback) throw new RangeError("localizedPath received an unsupported locale");
   const normalized = cleanPath(path);
   return canonical === fallback ? normalized : `/${canonical}${normalized === "/" ? "" : normalized}`;
 }
 
-export function localizedUrl(baseUrl, path, locale, defaultLocale) {
-  return `${cleanBase(baseUrl)}${localizedPath(path, locale, defaultLocale)}`;
+export function localizedUrl(baseUrl, path, locale, defaultLocale, registry = FAMILY_LOCALES) {
+  return `${cleanBase(baseUrl)}${localizedPath(path, locale, defaultLocale, registry)}`;
 }
 
-export function buildMetadata({ baseUrl, path, locale, defaultLocale, title, description, siteName, image }) {
-  const canonicalLocaleCode = canonicalLocale(locale);
+export function buildMetadata({ baseUrl, path, locale, defaultLocale, title, description, siteName, image, registry = FAMILY_LOCALES }) {
+  const canonicalLocaleCode = registry.canonicalLocale(locale);
   if (!canonicalLocaleCode) throw new RangeError(`Unsupported locale: ${locale}`);
-  const canonical = localizedUrl(baseUrl, path, canonicalLocaleCode, defaultLocale);
-  const alternates = LOCALES.map(({ code }) => ({ hreflang: code, href: localizedUrl(baseUrl, path, code, defaultLocale) }));
-  alternates.push({ hreflang: "x-default", href: localizedUrl(baseUrl, path, defaultLocale, defaultLocale) });
+  const canonical = localizedUrl(baseUrl, path, canonicalLocaleCode, defaultLocale, registry);
+  const alternates = registry.LOCALES.map(({ code }) => ({ hreflang: code, href: localizedUrl(baseUrl, path, code, defaultLocale, registry) }));
+  alternates.push({ hreflang: "x-default", href: localizedUrl(baseUrl, path, defaultLocale, defaultLocale, registry) });
   const imageUrl = new URL(image, `${cleanBase(baseUrl)}/`).href;
   return {
-    html: localeAttributes(canonicalLocaleCode),
+    html: registry.localeAttributes(canonicalLocaleCode),
     title,
     description,
     canonical,
@@ -44,13 +50,13 @@ export function buildMetadata({ baseUrl, path, locale, defaultLocale, title, des
   };
 }
 
-export function buildSitemap({ baseUrl, routes, defaultLocale, lastModified }) {
-  return routes.flatMap((path) => LOCALES.map(({ code }) => ({
-    loc: localizedUrl(baseUrl, path, code, defaultLocale),
+export function buildSitemap({ baseUrl, routes, defaultLocale, lastModified, registry = FAMILY_LOCALES }) {
+  return routes.flatMap((path) => registry.LOCALES.map(({ code }) => ({
+    loc: localizedUrl(baseUrl, path, code, defaultLocale, registry),
     locale: code,
     alternates: [
-      ...LOCALES.map(({ code: alternate }) => ({ hreflang: alternate, href: localizedUrl(baseUrl, path, alternate, defaultLocale) })),
-      { hreflang: "x-default", href: localizedUrl(baseUrl, path, defaultLocale, defaultLocale) },
+      ...registry.LOCALES.map(({ code: alternate }) => ({ hreflang: alternate, href: localizedUrl(baseUrl, path, alternate, defaultLocale, registry) })),
+      { hreflang: "x-default", href: localizedUrl(baseUrl, path, defaultLocale, defaultLocale, registry) },
     ],
     ...(lastModified ? { lastmod: lastModified } : {}),
   })));

package/src/tanstack-start.d.mts

@@ -1,3 +1,10 @@
 import type { SiteMetadata } from "./core/seo.mjs";
-export declare function toTanStackHead(metadata: SiteMetadata): { meta: Array<Record<string, string>>; links: Array<Record<string, string>> };
-export declare const toHtmlAttributes: (metadata: SiteMetadata) => { lang: string; dir: string };
+import type { SiteLocale } from "./core/locales.mjs";
+
+/**
+ * Generic over the locale code, like the builders that feed it. A product
+ * registry (D-018) yields `SiteMetadata<string>`; the adapter reads the
+ * same fields whatever the code type is, so it must not refuse that.
+ */
+export declare function toTanStackHead<Code extends string = SiteLocale>(metadata: SiteMetadata<Code>): { meta: Array<Record<string, string>>; links: Array<Record<string, string>> };
+export declare const toHtmlAttributes: <Code extends string = SiteLocale>(metadata: SiteMetadata<Code>) => { lang: Code; dir: string };