@salesforce/ui-bundle-template-app-react-template-b2x 11.55.1 → 11.56.0

package/dist/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.56.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.55.1...v11.56.0) (2026-08-12)
+
+**Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project
+
+
+
+
+
 ## [11.55.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v11.55.0...v11.55.1) (2026-08-11)
 
 **Note:** Version bump only for package @salesforce/ui-bundle-template-base-sfdx-project

package/dist/force-app/main/default/uiBundles/reactexternalapp/package.json

@@ -18,8 +18,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/platform-sdk": "^11.55.1",
-    "@salesforce/ui-bundle": "^11.55.1",
+    "@salesforce/platform-sdk": "^11.56.0",
+    "@salesforce/ui-bundle": "^11.56.0",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -46,8 +46,8 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/graphiti": "^11.55.1",
-    "@salesforce/vite-plugin-ui-bundle": "^11.55.1",
+    "@salesforce/graphiti": "^11.56.0",
+    "@salesforce/vite-plugin-ui-bundle": "^11.56.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/language-switcher/LanguageSwitcher.tsx

@@ -0,0 +1,116 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Drop-in language switcher for B2X (Experience) apps.
+ *
+ * Renders a labeled `<select>` of the site's supported {@link LANGUAGES}.
+ * Choosing a language rewrites the current URL so the chosen code becomes the
+ * first path segment after `basePath` (see {@link buildLanguageUrl}) and reloads
+ * the page via `window.location.assign`. A full reload lets the platform serve
+ * the correctly localized content — this component owns only the URL rewrite.
+ */
+
+import { buildLanguageUrl, getLanguageFromUrl, urlSegmentToCode } from "./buildLanguageUrl";
+import { DEFAULT_LANGUAGE, LANGUAGE_CODES, LANGUAGES } from "./languages";
+
+/**
+ * The subset of `SFDC_ENV` this component reads. We type it structurally here
+ * (rather than relying on the ambient `SfdcEnv`) so the feature type-checks in
+ * isolation: its ambient augmentation intentionally declares only `language?`,
+ * while `basePath` is provided by the platform types once composed into an app.
+ */
+interface SfdcEnvSubset {
+	basePath?: string;
+	/** Page locale in hyphenated form, e.g. "en-US" (the platform's injected form). */
+	language?: string;
+}
+
+/** Read `SFDC_ENV` off the global scope without assuming it exists. */
+function getSfdcEnv(): SfdcEnvSubset | undefined {
+	return (globalThis as { SFDC_ENV?: SfdcEnvSubset }).SFDC_ENV;
+}
+
+/**
+ * Resolve the active language, in precedence order:
+ *
+ * 1. `SFDC_ENV.language` — authoritative when the platform provides it. The
+ *    platform injects this in hyphenated form (e.g. `"en-US"`), so it is
+ *    remapped back to a locale code (`en_US`) before matching, mirroring how the
+ *    URL segment is handled.
+ * 2. The leading URL path segment after `basePath`, when it is a supported
+ *    language code — reflects the page the user is actually viewing (e.g. a
+ *    direct hit on `/shop/fr/catalog`) even before the runtime populates
+ *    `SFDC_ENV.language`.
+ * 3. {@link DEFAULT_LANGUAGE}.
+ *
+ * Only codes in {@link LANGUAGES} are honored; anything else falls through.
+ */
+export function getCurrentLanguage(): string {
+	const envLanguage = getSfdcEnv()?.language;
+	if (envLanguage) {
+		const envCode = urlSegmentToCode(envLanguage);
+		if (LANGUAGE_CODES.has(envCode)) {
+			return envCode;
+		}
+	}
+
+	const basePath = getSfdcEnv()?.basePath ?? "";
+	const urlLanguage = getLanguageFromUrl(window.location.href, basePath, LANGUAGE_CODES);
+	return urlLanguage ?? DEFAULT_LANGUAGE;
+}
+
+export interface LanguageSwitcherProps {
+	/** Accessible label for the control. Defaults to "Language". */
+	label?: string;
+	/** Extra classes merged onto the `<select>`. */
+	className?: string;
+}
+
+export function LanguageSwitcher({ label = "Language", className }: LanguageSwitcherProps) {
+	// Render nothing when there is no real choice to make. A single-option
+	// dropdown is an inert control: it can't change anything, yet it still takes
+	// a focus stop and is announced as a "1 of 1" menu, implying options that
+	// don't exist. Omitting it entirely keeps the accessibility tree honest.
+	if (LANGUAGES.length < 2) {
+		return null;
+	}
+
+	const current = getCurrentLanguage();
+
+	const handleChange = (event: React.ChangeEvent<HTMLSelectElement>) => {
+		const next = event.target.value;
+		// No-op when the selection already matches the active language.
+		if (next === current) return;
+
+		const basePath = getSfdcEnv()?.basePath ?? "";
+		const nextUrl = buildLanguageUrl(
+			window.location.href,
+			basePath,
+			next,
+			LANGUAGE_CODES,
+			DEFAULT_LANGUAGE,
+		);
+		window.location.assign(nextUrl);
+	};
+
+	return (
+		<select
+			aria-label={label}
+			value={current}
+			onChange={handleChange}
+			className={
+				className ?? "rounded-md border border-border bg-card px-3 py-1.5 text-sm text-foreground"
+			}
+		>
+			{LANGUAGES.map((language) => (
+				<option key={language.code} value={language.code}>
+					{language.label}
+				</option>
+			))}
+		</select>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/language-switcher/__examples__/language-switcher-example.tsx

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Example: mounting <LanguageSwitcher /> in an app layout/header.
+ *
+ * This file is illustrative — it is copied into the app as an example, not wired
+ * into routing. To adopt the switcher, render <LanguageSwitcher /> wherever your
+ * app's chrome lives (typically the nav/header in `appLayout.tsx`). It manages
+ * its own state from the URL + SFDC_ENV, so no props are required.
+ */
+
+import { Outlet } from "react-router";
+import { LanguageSwitcher } from "../index";
+
+export default function AppLayoutWithLanguageSwitcher() {
+	return (
+		<>
+			<nav className="bg-white border-b border-gray-200">
+				<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+					<div className="flex justify-between items-center h-16">
+						<span className="text-xl font-semibold text-gray-900">React App</span>
+						<div className="flex items-center gap-2">
+							{/* Drop the switcher anywhere in your header/chrome. */}
+							<LanguageSwitcher />
+						</div>
+					</div>
+				</div>
+			</nav>
+			<Outlet />
+		</>
+	);
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/language-switcher/__examples__/vite-config-site-example.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Example: switching your app's `vite.config.ts` to the SITE entry of
+ * `@salesforce/vite-plugin-ui-bundle` so language switching works in local dev.
+ *
+ * This file is illustrative — it is copied into the app as an example, not used
+ * directly. Apply the two changes below to your real `vite.config.ts`.
+ *
+ * WHY: On a deployed Experience site the platform injects `SFDC_ENV.language`
+ * and folds the active language into `SFDC_ENV.basePath` (e.g. `/shop/fr`),
+ * recomputed from the URL on every load. The generic local Vite dev server does
+ * neither — `SFDC_ENV.language` is absent and `basePath` is always `/` — so the
+ * switcher can't route a non-default language locally (the reload 404s and the
+ * labels never flip). The SITE entry mirrors production for local dev only.
+ *
+ * HOW: change the import from the generic plugin to the `/site` subpath, and
+ * pass the feature's supported `LANGUAGES` (the single source of truth). The
+ * plugin needs the language CODES, so map the `{ code, label }` list to codes.
+ * The FIRST entry is the default, served un-prefixed at `/` — matching
+ * `DEFAULT_LANGUAGE` in `languages.ts`.
+ *
+ * This has NO effect on a deployed build; non-site bundles keep the generic
+ * `@salesforce/vite-plugin-ui-bundle` import unchanged.
+ */
+
+// 1. Replace the generic plugin import:
+//      import salesforce from "@salesforce/vite-plugin-ui-bundle";
+//    with the site entry + the feature's language list:
+import siteUiBundlePlugin from "@salesforce/vite-plugin-ui-bundle/site";
+import { LANGUAGES } from "../languages";
+
+// 2. In your `defineConfig({ plugins: [...] })`, replace the `salesforce()`
+//    call with `siteUiBundlePlugin(...)`, passing the language codes:
+export const examplePlugins = [
+	// tailwindcss(),
+	// react(),
+	siteUiBundlePlugin({ languages: LANGUAGES.map((l) => l.code) }),
+	// ...codegen
+];

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/language-switcher/buildLanguageUrl.ts

@@ -0,0 +1,158 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** Strip leading and trailing slashes from a path fragment. */
+function trimSlashes(value: string): string {
+	return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+/**
+ * Convert a Salesforce locale code to the form used in the URL path.
+ *
+ * Locale codes use underscores (e.g. `en_US`), but URL path segments use hyphens
+ * (e.g. `en-US`). This maps a code to its URL segment.
+ */
+function codeToUrlSegment(code: string): string {
+	return code.replace(/_/g, "-");
+}
+
+/**
+ * Convert a hyphenated language token back to a Salesforce locale code — the
+ * inverse of {@link codeToUrlSegment} (e.g. `en-US` → `en_US`). Locale codes
+ * never contain hyphens, so this remapping is unambiguous. Used both for URL
+ * path segments and for the hyphenated `SFDC_ENV.language` value the platform
+ * injects (e.g. `"en-US"`), which share the same hyphen convention.
+ */
+export function urlSegmentToCode(segment: string): string {
+	return segment.replace(/-/g, "_");
+}
+
+/**
+ * Recover the true, language-free site root from `basePath`.
+ *
+ * When a non-default language is active, the platform folds the language segment
+ * into `SFDC_ENV.basePath` itself — `/shop` becomes `/shop/fr` — rather than
+ * leaving `basePath` as the stable site root with the language living in the path
+ * after it. If we took `basePath` at face value, the language segment would be
+ * treated as part of the base and never seen as a leading language segment, so
+ * switching to the default (which should remove the segment) and switching
+ * between non-default languages (which should replace it) would both fail.
+ *
+ * Strip a single trailing segment when it is a known language (remapped from its
+ * URL form back to a locale code), yielding the language-free site root so the
+ * rest of this module can treat the leading path segment after it as the language.
+ */
+function normalizeBasePath(basePath: string, knownCodes: ReadonlySet<string>): string {
+	const segments = trimSlashes(basePath).split("/").filter(Boolean);
+	const last = segments[segments.length - 1];
+	if (last && knownCodes.has(urlSegmentToCode(last))) {
+		segments.pop();
+	}
+	return segments.join("/");
+}
+
+/**
+ * Return the path segments that live AFTER `basePath` in `pathname`.
+ * Both are compared with leading/trailing slashes normalized.
+ */
+function segmentsAfterBase(pathname: string, basePath: string): string[] {
+	const base = trimSlashes(basePath);
+	const trimmedPath = trimSlashes(pathname);
+
+	let rest = trimmedPath;
+	if (base && (trimmedPath === base || trimmedPath.startsWith(`${base}/`))) {
+		rest = trimmedPath.slice(base.length);
+	}
+	return trimSlashes(rest).split("/").filter(Boolean);
+}
+
+/**
+ * Read the language encoded in a URL: the first path segment after `basePath`,
+ * remapped from its URL form (hyphens) back to a locale code (underscores) and
+ * returned only when it is one of `knownCodes`. Returns `undefined` when the
+ * leading segment is absent or is not a known language code.
+ *
+ * @param currentUrl Absolute URL to inspect (e.g. `window.location.href`).
+ * @param basePath   Site root path (e.g. `SFDC_ENV.basePath`); may be `""`.
+ * @param knownCodes Language codes considered valid leading segments.
+ * @returns The matched locale code (e.g. `en_US`), or `undefined`.
+ */
+export function getLanguageFromUrl(
+	currentUrl: string,
+	basePath: string,
+	knownCodes: ReadonlySet<string>,
+): string | undefined {
+	const { pathname } = new URL(currentUrl);
+	const siteRoot = normalizeBasePath(basePath, knownCodes);
+	const [first] = segmentsAfterBase(pathname, siteRoot);
+	if (!first) {
+		return undefined;
+	}
+	const code = urlSegmentToCode(first);
+	return knownCodes.has(code) ? code : undefined;
+}
+
+/**
+ * Rewrite `currentUrl` so `language` is reflected in the first path segment after
+ * `basePath`. The rest of the path, the query string, and the hash are preserved.
+ *
+ * The leading segment after `basePath` is examined and remapped from its URL form
+ * (hyphens) back to a locale code before being compared against `knownCodes`:
+ *
+ * - **Default language** (`language === defaultLanguage`): the default is the
+ *   implicit, un-prefixed language, so NO segment is written. An existing
+ *   known-language leading segment is REMOVED (`/shop/fr/page` → `/shop/page`);
+ *   if there is none, the path is left unchanged.
+ * - **Non-default language**: an existing known-language leading segment is
+ *   REPLACED — so switching never stacks segments (`/en-US/fr/page`) — otherwise
+ *   the language is INSERTED as a new first segment. The written segment uses the
+ *   URL form of the code (underscores → hyphens, e.g. `en_US` → `en-US`).
+ *
+ * When a non-default language is active the platform folds that language into
+ * `basePath` itself (`/shop` → `/shop/fr`); a trailing known-language segment is
+ * stripped from `basePath` first (see {@link normalizeBasePath}) so the leading
+ * segment after the true site root is always what gets replaced/removed/inserted.
+ *
+ * `basePath` is matched with trailing slashes normalized, and the result never
+ * contains double slashes.
+ *
+ * @param currentUrl      Absolute URL to rewrite (e.g. `window.location.href`).
+ * @param basePath        Site root path (e.g. `SFDC_ENV.basePath`); may be `""`.
+ * @param language        Locale code to reflect after `basePath` (e.g. `en_US`).
+ * @param knownCodes      Language codes eligible for the leading-segment check.
+ * @param defaultLanguage Locale code that is served without a URL segment.
+ * @returns The rewritten absolute URL as a string.
+ */
+export function buildLanguageUrl(
+	currentUrl: string,
+	basePath: string,
+	language: string,
+	knownCodes: ReadonlySet<string>,
+	defaultLanguage: string,
+): string {
+	const url = new URL(currentUrl);
+
+	const base = normalizeBasePath(basePath, knownCodes);
+	const segments = segmentsAfterBase(url.pathname, base);
+	const leadingIsLanguage = segments.length > 0 && knownCodes.has(urlSegmentToCode(segments[0]));
+
+	if (language === defaultLanguage) {
+		// The default language is served un-prefixed. Drop an existing language
+		// segment so switching back to default removes it, rather than writing one.
+		if (leadingIsLanguage) {
+			segments.shift();
+		}
+	} else if (leadingIsLanguage) {
+		segments[0] = codeToUrlSegment(language);
+	} else {
+		segments.unshift(codeToUrlSegment(language));
+	}
+
+	const rebuiltPath = [base, ...segments].filter(Boolean).join("/");
+	url.pathname = `/${rebuiltPath}`;
+
+	return url.toString();
+}

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/language-switcher/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * Public API for the language switcher feature.
+ *
+ * Most apps only need:
+ *   ```tsx
+ *   import { LanguageSwitcher } from ".../features/language-switcher";
+ *   <LanguageSwitcher />
+ *   ```
+ *
+ * Lower-level pieces are exported for custom UIs and testing:
+ *   - {@link getCurrentLanguage} to read the active language
+ *   - {@link buildLanguageUrl} to compute the rewritten URL yourself
+ *   - {@link LANGUAGES} / {@link DEFAULT_LANGUAGE} for the supported set
+ */
+
+export { LanguageSwitcher, getCurrentLanguage } from "./LanguageSwitcher";
+export type { LanguageSwitcherProps } from "./LanguageSwitcher";
+
+export { buildLanguageUrl, getLanguageFromUrl } from "./buildLanguageUrl";
+
+export { LANGUAGES, DEFAULT_LANGUAGE, LANGUAGE_CODES } from "./languages";
+export type { LanguageOption } from "./languages";

package/dist/force-app/main/default/uiBundles/reactexternalapp/src/features/language-switcher/languages.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/** A single language option offered by the switcher. */
+export interface LanguageOption {
+	/** Salesforce locale code, e.g. "en_US". Used as the URL path segment. */
+	code: string;
+	/** Human-readable label shown in the dropdown, e.g. "English". */
+	label: string;
+}
+
+/**
+ * The languages this app offers in the switcher.
+ *
+ * IMPORTANT — keep this list in sync BY HAND with the site's language settings:
+ *   digitalExperiences/site/<siteName>/sfdc_cms__languageSettings/content.json
+ *
+ * There is no runtime API to read `sfdc_cms__languageSettings` on a published
+ * site, so the supported languages are baked into the bundle at authoring time.
+ * When the site's content.json changes, update this array (and
+ * {@link DEFAULT_LANGUAGE}) to match.
+ *
+ * `code` values are Salesforce locale codes (underscores). They are converted to
+ * hyphenated form for use as the first URL path segment after `basePath` (e.g.
+ * `en_US` → `/en-US/...`, `fr` → `/fr/...`). Display order here is the order shown
+ * in the dropdown.
+ */
+export const LANGUAGES: readonly LanguageOption[] = [
+	{ code: "en_US", label: "English" },
+	{ code: "fr", label: "Français" },
+	{ code: "es", label: "Español" },
+	{ code: "de", label: "Deutsch" },
+	{ code: "ja", label: "日本語" },
+];
+
+/**
+ * Language used when `SFDC_ENV.language` is missing or is not one of
+ * {@link LANGUAGES}. Should match the site's default language in content.json.
+ */
+export const DEFAULT_LANGUAGE = "en_US";
+
+/** Set of known language codes, for fast membership checks. */
+export const LANGUAGE_CODES: ReadonlySet<string> = new Set(LANGUAGES.map((l) => l.code));