@octabits-io/nuxt-ui-kit 0.2.1 → 0.3.0

package/dist/index.js

@@ -1,323 +1,4 @@
-import { UserManager, WebStorageStateStore } from "oidc-client-ts";
-import { computed, ref, watch } from "vue";
-import { treaty } from "@elysiajs/eden";
-//#region src/auth/oidc.ts
-/**
-* Lazily-created `UserManager` singleton bound to `window.localStorage`.
-* Call the returned getter from plugins/stores/composables — the manager is
-* constructed on first call (client-side only; requires `window`).
-*/
-function createUserManagerFactory(options) {
-	let userManager = null;
-	return function getUserManager() {
-		if (userManager) return userManager;
-		const { issuerUrl, clientId } = options.getConfig();
-		if (!issuerUrl || !clientId) (options.onMissingConfig ?? console.error)("Missing OIDC issuer URL or client id in runtime config");
-		userManager = new UserManager({
-			authority: issuerUrl,
-			client_id: clientId,
-			redirect_uri: `${window.location.origin}${options.redirectPath ?? "/auth/callback"}`,
-			post_logout_redirect_uri: `${window.location.origin}${options.postLogoutRedirectPath ?? "/login"}`,
-			response_type: "code",
-			scope: options.scope,
-			automaticSilentRenew: options.automaticSilentRenew ?? true,
-			...options.refreshTokenAllowedScope ? { refreshTokenAllowedScope: options.refreshTokenAllowedScope } : {},
-			userStore: new WebStorageStateStore({ store: window.localStorage }),
-			...options.settings
-		});
-		return userManager;
-	};
-}
-/**
-* Remove any `oidc.user:` storage keys that don't belong to the current
-* authority+clientId — leftovers from environment switches would otherwise
-* shadow or bloat the session storage.
-*/
-function removeStaleOidcKeys(authority, clientId, storage = globalThis.localStorage) {
-	const currentKey = `oidc.user:${authority}:${clientId}`;
-	for (let i = storage.length - 1; i >= 0; i--) {
-		const key = storage.key(i);
-		if (key && key.startsWith("oidc.user:") && key !== currentKey) storage.removeItem(key);
-	}
-}
-/** Refresh tokens fail unrecoverably with these OIDC error codes — user must re-auth. */
-function isUnrecoverableRenewError(message) {
-	return message.includes("login_required") || message.includes("invalid_grant") || message.includes("interaction_required") || message.includes("consent_required");
-}
-/**
-* Build a `redirectToLogin()` that starts an OIDC signin redirect carrying the
-* current path as returnUrl state, with a plain `/login?redirect=` navigation
-* fallback when the IdP redirect cannot even be started. No-ops on auth routes.
-*/
-function createLoginRedirector(options) {
-	const loginPath = options.loginPath ?? "/login";
-	const isAuthRoute = options.isAuthRoute ?? ((path) => path === loginPath || path.startsWith("/auth/"));
-	return async function redirectToLogin() {
-		const path = window.location.pathname;
-		if (isAuthRoute(path)) return;
-		const returnUrl = path + window.location.search;
-		try {
-			await options.getUserManager().signinRedirect({ state: returnUrl });
-		} catch (err) {
-			(options.log ?? console.error)("[oidc] signinRedirect failed, falling back to login navigation", err);
-			window.location.href = `${loginPath}?redirect=${encodeURIComponent(returnUrl)}`;
-		}
-	};
-}
-/**
-* Wire oidc-client-ts session events to app callbacks:
-*
-* - silent-renew error → `notify` (`renew-failed`, or `session-expired` when the
-*   error is unrecoverable — see {@link isUnrecoverableRenewError}); an
-*   unrecoverable error also triggers the login redirect
-* - access token expired without renewal → `notify(session-expired)` +
-*   `onSessionLost` + login redirect
-* - back-channel signout at the IdP → `onSessionLost` + login redirect (no notice
-*   — the user initiated it elsewhere)
-*
-* Returns a detach function.
-*/
-function attachSessionLifecycleHandlers(userManager, handlers) {
-	const log = handlers.log ?? console.warn;
-	const onSilentRenewError = (error) => {
-		log("[oidc] silent token renew failed:", error);
-		const unrecoverable = isUnrecoverableRenewError(error.message);
-		handlers.notify?.(unrecoverable ? {
-			kind: "session-expired",
-			error
-		} : {
-			kind: "renew-failed",
-			error
-		});
-		if (unrecoverable) handlers.redirectToLogin();
-	};
-	const onAccessTokenExpired = () => {
-		log("[oidc] access token expired without silent renewal");
-		handlers.notify?.({ kind: "session-expired" });
-		handlers.onSessionLost?.();
-		handlers.redirectToLogin();
-	};
-	const onUserSignedOut = () => {
-		log("[oidc] user signed out at IdP (back-channel)");
-		handlers.onSessionLost?.();
-		handlers.redirectToLogin();
-	};
-	userManager.events.addSilentRenewError(onSilentRenewError);
-	userManager.events.addAccessTokenExpired(onAccessTokenExpired);
-	userManager.events.addUserSignedOut(onUserSignedOut);
-	return () => {
-		userManager.events.removeSilentRenewError(onSilentRenewError);
-		userManager.events.removeAccessTokenExpired(onAccessTokenExpired);
-		userManager.events.removeUserSignedOut(onUserSignedOut);
-	};
-}
-//#endregion
-//#region src/auth/zitadel.ts
-/**
-* Zitadel scope presets for {@link createUserManagerFactory}.
-*
-* The URN scopes request the resource-owner (organization) claim and the
-* project role grants; `offline_access` requests a refresh token.
-*/
-const ZITADEL_ORG_PROJECT_SCOPE = "openid profile email urn:zitadel:iam:user:resourceowner urn:zitadel:iam:org:project:roles offline_access";
-/**
-* Zitadel only accepts standard OIDC scopes on the refresh-token grant —
-* sending `offline_access` or the `urn:zitadel:*` scopes returns
-* `invalid_scope` even though they were granted at the initial auth. The
-* URN-based claims still need to land in the refreshed access token; that
-* depends on "Assert Roles on Authentication" being enabled at the Zitadel
-* project level.
-*/
-const ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE = "openid profile email";
-//#endregion
-//#region src/auth/bypass.ts
-/**
-* Dev/E2E auth bypass: seed storage with a fake oidc-client-ts user whose
-* `access_token` is the bypass secret, so the app considers the session
-* authenticated and the API client sends the secret as Bearer.
-*
-* Call from a plugin that runs before the OIDC plugin. Skips seeding when a
-* valid (non-expired) session already exists; overwrites corrupt entries.
-* Returns whether a session was seeded.
-*/
-function seedAuthBypassSession(options) {
-	if (options.isProductionBuild) return false;
-	if (!options.bypassSecret) return false;
-	const storage = options.storage ?? globalThis.localStorage;
-	const storageKey = `oidc.user:${options.issuerUrl}:${options.clientId}`;
-	const existing = storage.getItem(storageKey);
-	if (existing) try {
-		if ((JSON.parse(existing).expires_at ?? 0) > Date.now() / 1e3) return false;
-	} catch {}
-	(options.warn ?? console.warn)("[auth-bypass] Seeding storage with bypass token for dev/E2E testing");
-	storage.setItem(storageKey, JSON.stringify({
-		access_token: options.bypassSecret,
-		token_type: "Bearer",
-		expires_at: Math.floor(Date.now() / 1e3) + (options.sessionTtlSeconds ?? 86400),
-		profile: options.profile ?? {
-			sub: "e2e-test-user",
-			email: "e2e@example.test",
-			name: "E2E Test User"
-		},
-		scope: "openid profile email"
-	}));
-	return true;
-}
-//#endregion
-//#region src/auth/session.ts
-function defaultAuthUserMapper(profile) {
-	return {
-		id: profile.sub,
-		email: profile.email ?? "",
-		name: profile.name ?? null,
-		picture: profile.picture ?? null
-	};
-}
-/**
-* Reactive OIDC session state + actions — the setup body of an auth store.
-* Wrap it in the app's own store so naming and registration stay app-owned:
-*
-* ```ts
-* export const useAuthStore = defineStore('auth', () =>
-*   createAuthSessionCore({ getUserManager, mapUser: defaultAuthUserMapper }),
-* )
-* ```
-*/
-function createAuthSessionCore(options) {
-	const log = options.log ?? console.warn;
-	const user = ref(null);
-	const initialized = ref(false);
-	const loading = ref(false);
-	const isAuthenticated = computed(() => !!user.value);
-	async function checkAuth() {
-		loading.value = true;
-		try {
-			const um = options.getUserManager();
-			let oidcUser = await um.getUser();
-			if (oidcUser && oidcUser.expired && oidcUser.refresh_token) try {
-				oidcUser = await um.signinSilent();
-			} catch (err) {
-				log("[auth] signinSilent failed during checkAuth", err);
-				oidcUser = null;
-			}
-			if (oidcUser && !oidcUser.expired) user.value = options.mapUser(oidcUser.profile);
-			else user.value = null;
-		} catch {
-			user.value = null;
-		} finally {
-			initialized.value = true;
-			loading.value = false;
-		}
-	}
-	async function login(returnUrl) {
-		await options.getUserManager().signinRedirect({ state: returnUrl ?? "/" });
-	}
-	async function handleCallback() {
-		loading.value = true;
-		try {
-			const oidcUser = await options.getUserManager().signinRedirectCallback();
-			user.value = options.mapUser(oidcUser.profile);
-			return oidcUser.state || "/";
-		} finally {
-			initialized.value = true;
-			loading.value = false;
-		}
-	}
-	async function logout() {
-		loading.value = true;
-		try {
-			const manager = options.getUserManager();
-			const idTokenHint = (await manager.getUser())?.id_token;
-			await manager.removeUser();
-			user.value = null;
-			await manager.signoutRedirect(idTokenHint ? { id_token_hint: idTokenHint } : void 0);
-		} finally {
-			loading.value = false;
-		}
-	}
-	return {
-		user,
-		initialized,
-		loading,
-		isAuthenticated,
-		checkAuth,
-		login,
-		handleCallback,
-		logout
-	};
-}
-//#endregion
-//#region src/auth/guard.ts
-/**
-* Build the body of a global auth route-middleware. The returned handler
-* yields a redirect target path or `undefined` to allow navigation; the app's
-* middleware maps that onto its router:
-*
-* ```ts
-* export default defineNuxtRouteMiddleware(async (to) => {
-*   const target = await guard(to)
-*   if (target) return navigateTo(target)
-* })
-* ```
-*/
-function createAuthGuard(options) {
-	const isPublicRoute = options.isPublicRoute ?? ((to) => to.path === "/login" || to.path.startsWith("/auth/"));
-	const loginRedirect = options.loginRedirect ?? ((returnTo) => `/login?redirect=${encodeURIComponent(returnTo)}`);
-	return async function guard(to) {
-		if (isPublicRoute(to)) return void 0;
-		if (!await options.ensureAuthenticated()) return loginRedirect(to.fullPath);
-		const target = await options.afterAuthenticated?.(to);
-		return typeof target === "string" ? target : void 0;
-	};
-}
-//#endregion
-//#region src/api/client.ts
-/**
-* Resolve the API base URL: configured value, else the page origin in
-* production builds (same-host ingress), else a localhost dev port.
-*/
-function resolveApiBaseUrl(options) {
-	if (options.configuredUrl) return options.configuredUrl;
-	return options.isProductionBuild ? options.origin ?? window.location.origin : `http://localhost:${options.devFallbackPort}`;
-}
-/**
-* Bearer-token provider backed by the OIDC session: resolves to the current
-* access token, or `null` when there is no non-expired session.
-*/
-function createAccessTokenProvider(getUserManager) {
-	return async function getAccessToken() {
-		const user = await getUserManager().getUser();
-		if (!user || user.expired) return null;
-		return user.access_token;
-	};
-}
-/**
-* Lazily-created Eden Treaty client singleton with OIDC bearer injection.
-*
-* ```ts
-* const getClient = createTreatyClientFactory<App>({ getBaseUrl, getAccessToken })
-* export function useApi() {
-*   const client = getClient()
-*   return { api: client.api, client }
-* }
-* ```
-*/
-function createTreatyClientFactory(options) {
-	let client = null;
-	return function getClient() {
-		if (client) return client;
-		client = treaty(options.getBaseUrl(), {
-			parseDate: options.parseDate ?? false,
-			headers: async () => {
-				const token = await options.getAccessToken();
-				if (token) return { authorization: `Bearer ${token}` };
-			},
-			...options.treatyConfig
-		});
-		return client;
-	};
-}
-//#endregion
+import { computed, reactive, ref, watch } from "vue";
 //#region src/org/orgStore.ts
 /**
 * Reactive granted-organizations state + switching — the setup body of an
@@ -379,6 +60,11 @@ function createOrgStoreCore(options) {
 	};
 }
 //#endregion
+//#region src/runtimeConfig.ts
+function resolveRuntimeConfigValue(appConfigKey, fallback) {
+	return (typeof window === "undefined" ? void 0 : window.__APP_CONFIG__)?.[appConfigKey] || fallback;
+}
+//#endregion
 //#region src/composables/useConfirm.ts
 const isOpen = ref(false);
 const currentOptions = ref({ title: "" });
@@ -470,6 +156,53 @@ function createApiErrorMessenger(options) {
 	};
 }
 //#endregion
+//#region src/composables/useHelpPanel.ts
+const HELP_PANEL_KEY = Symbol("help-panel");
+/**
+* Provide/inject registry for a per-tab contextual help panel: pages register
+* help actions keyed by tab, `PageUtilityActions` renders the toggle, and a
+* panel component renders `currentActions`. Open state persists to
+* localStorage; switching to a tab without actions auto-closes the panel.
+*
+* Provide it per page: `provide(HELP_PANEL_KEY, useHelpPanel())`.
+*/
+function useHelpPanel(options = {}) {
+	const storageKey = options.storageKey ?? "help-panel-open";
+	const storage = options.storage ?? globalThis.localStorage;
+	const isOpen = ref(storage?.getItem(storageKey) === "true");
+	watch(isOpen, (open) => storage?.setItem(storageKey, String(open)));
+	const registrations = reactive(/* @__PURE__ */ new Map());
+	const activeTabValue = ref("");
+	const currentActions = computed(() => {
+		return registrations.get(activeTabValue.value)?.actions ?? [];
+	});
+	const hasActions = computed(() => currentActions.value.length > 0);
+	function register(tabValue, actions) {
+		registrations.set(tabValue, { actions });
+	}
+	function unregister(tabValue) {
+		registrations.delete(tabValue);
+	}
+	function setActiveTab(tabValue) {
+		activeTabValue.value = tabValue;
+		if (!registrations.has(tabValue)) isOpen.value = false;
+	}
+	function toggle() {
+		isOpen.value = !isOpen.value;
+	}
+	return {
+		registrations,
+		isOpen,
+		activeTabValue,
+		currentActions,
+		hasActions,
+		register,
+		unregister,
+		setActiveTab,
+		toggle
+	};
+}
+//#endregion
 //#region src/composables/useDirtyTracking.ts
 function deepClone(obj) {
 	return JSON.parse(JSON.stringify(obj));
@@ -535,4 +268,4 @@ function usePagination(options = {}) {
 	};
 }
 //#endregion
-export { ZITADEL_ORG_PROJECT_SCOPE, ZITADEL_REFRESH_TOKEN_ALLOWED_SCOPE, attachSessionLifecycleHandlers, createAccessTokenProvider, createApiErrorMessenger, createAuthGuard, createAuthSessionCore, createLoginRedirector, createOrgStoreCore, createTreatyClientFactory, createUserManagerFactory, defaultAuthUserMapper, isUnrecoverableRenewError, removeStaleOidcKeys, resolveApiBaseUrl, seedAuthBypassSession, useConfirm, useConfirmState, useDirtyTracking, usePagination };
+export { HELP_PANEL_KEY, createApiErrorMessenger, createOrgStoreCore, resolveRuntimeConfigValue, useConfirm, useConfirmState, useDirtyTracking, useHelpPanel, usePagination };

package/dist/locale/index.d.ts

@@ -0,0 +1,140 @@
+import { ComputedRef, InjectionKey, MaybeRefOrGetter, ModelRef, Ref } from "vue";
+import { LocaleMap } from "@octabits-io/framework/utils";
+//#region src/locale/pruneLocaleMap.d.ts
+/**
+ * Drop empty-string leaves from a `LocaleMap<string>` so cleared tabs fall
+ * back to the default locale instead of shadowing it with `''`. Returns a new
+ * map; use `Object.keys(result).length` to decide between map and `null` when
+ * the API expects `null` for "unset".
+ */
+declare function pruneLocaleMap(map: LocaleMap<string> | null | undefined): LocaleMap<string>;
+//#endregion
+//#region src/locale/index.d.ts
+/** Reactive source of the content-locale set a locale field edits against. */
+interface LocaleFieldSource {
+  /** Supported content locales (BCP-47 tags). */
+  locales: MaybeRefOrGetter<string[]>;
+  /** The locale whose value is required (completeness "error" dot). */
+  defaultLocale: MaybeRefOrGetter<string>;
+}
+type LocaleTabIndicator = {
+  kind: 'error';
+} | {
+  kind: 'warning';
+} | {
+  kind: 'inherits';
+} | null;
+/**
+ * Scope the locale field editors expose through their `#ai` slot, so a page
+ * can replace the default translate button with a combined AI menu without
+ * re-implementing the translate machinery.
+ */
+interface LocaleFieldTranslateScope {
+  /** Translate exists for this field at all (multiple locales, not `no-translate`). */
+  available: boolean;
+  /** Translate is currently actionable (some tab has text, empty targets exist). */
+  canTranslate: boolean;
+  translating: boolean;
+  translate: () => void;
+}
+/** What a quick-translate provider returns — drives the sparkle button. */
+interface LocaleFieldTranslator {
+  translating: Ref<boolean>;
+  canTranslate: Ref<boolean> | ComputedRef<boolean>;
+  translate: () => void;
+}
+interface UseTranslateOptions {
+  model: ModelRef<LocaleMap<string> | undefined>;
+  /** What the field is about (e.g. "Listing title") — passed as AI context. */
+  context: MaybeRefOrGetter<string | undefined>;
+  /** Source locale (from `useLocaleField().translateSource`). */
+  source: ComputedRef<string | null>;
+  /** Empty visible locales to fill (from `useLocaleField().translateTargets`). */
+  targetLocales: ComputedRef<string[]>;
+}
+/**
+ * App context the locale field components resolve at setup time. Both members
+ * are *factories invoked during the component's own setup*, so they may call
+ * composables (state, route, API clients) without executing at provide time.
+ */
+interface LocaleFieldContext {
+  /** Resolve the app's content-locale source. */
+  useSource: () => LocaleFieldSource;
+  /**
+   * Optional quick-translate provider; the AI-translate button renders only
+   * when this is present.
+   */
+  useTranslate?: (options: UseTranslateOptions) => LocaleFieldTranslator;
+}
+declare const LOCALE_FIELD_CONTEXT: InjectionKey<LocaleFieldContext>;
+/** Provide the locale-field context (call once, near the app root). */
+declare function provideLocaleFieldContext(context: LocaleFieldContext): void;
+/** Resolve the locale-field context inside a component (throws when absent). */
+declare function useLocaleFieldContext(): LocaleFieldContext;
+/**
+ * Tab plumbing shared by every per-locale field editor: one tab per content
+ * locale, an active-tab ref, and the completeness indicator. Value access
+ * stays with the caller — pass `hasValue` so the indicator works for any
+ * value type (strings, rich-text documents, …).
+ *
+ * **Register variants** (e.g. `de-formal`, whose base `de` is also supported)
+ * are a tone/overlay axis, not a real language: a label like "Hotel" is
+ * identical in both. So variant tabs are **hidden by default** and only shown
+ * when `registerOverride` is true (reader-addressing prose — descriptions,
+ * body copy). When shown, a blank variant value *inherits* its base locale
+ * (neutral hint, not a "missing" warning), and clearing the field should
+ * **delete the key** so the resolver falls through to the base
+ * (`de-formal → de`).
+ */
+declare function useLocaleTabs(hasValue: (locale: string) => boolean, source: LocaleFieldSource, registerOverride?: MaybeRefOrGetter<boolean>): {
+  items: ComputedRef<{
+    label: string;
+    value: string;
+  }[]>;
+  active: Ref<string, string>;
+  indicatorOf: (loc: string) => LocaleTabIndicator;
+  isVariant: (loc: string) => boolean;
+  defaultLocale: ComputedRef<string>;
+  visibleLocales: ComputedRef<string[]>;
+  translateSource: ComputedRef<string | null>;
+  translateTargets: ComputedRef<string[]>;
+};
+/**
+ * String-valued locale field over a single `LocaleMap<string>` model — the
+ * composable behind `LocaleInput` / `LocaleTextarea`. See
+ * {@link useLocaleTabs} for the tab/indicator semantics.
+ */
+declare function useLocaleField(model: ModelRef<LocaleMap<string> | undefined>, source: LocaleFieldSource, registerOverride?: MaybeRefOrGetter<boolean>): {
+  items: ComputedRef<{
+    label: string;
+    value: string;
+  }[]>;
+  active: Ref<string, string>;
+  activeValue: import("vue").WritableComputedRef<string, string>;
+  indicatorOf: (loc: string) => LocaleTabIndicator;
+  defaultLocale: ComputedRef<string>;
+  translateSource: ComputedRef<string | null>;
+  translateTargets: ComputedRef<string[]>;
+};
+/**
+ * Resolve a `LocaleMap<string>` to a single display string for list / detail
+ * surfaces, using the **default content locale** — deliberately decoupled
+ * from the app's own UI language, which is unrelated chrome and would
+ * otherwise select content arbitrarily. Lists therefore always show the
+ * canonical value, consistently for every user; the per-locale values stay
+ * fully editable via `LocaleInput` / `LocaleTextarea`.
+ */
+declare function createLocaleDisplay(source: Pick<LocaleFieldSource, 'defaultLocale'>): {
+  display: (map: LocaleMap<string> | null | undefined, fallback?: string) => string;
+};
+/**
+ * Translation-completeness summary rendered by `TranslationBadge`:
+ * `complete` when every in-use translatable leaf covers all supported
+ * locales; `missing` counts absent leaves per locale otherwise.
+ */
+interface TranslationStatus {
+  complete: boolean;
+  missing: Record<string, number>;
+}
+//#endregion
+export { LOCALE_FIELD_CONTEXT, LocaleFieldContext, LocaleFieldSource, LocaleFieldTranslateScope, LocaleFieldTranslator, LocaleTabIndicator, TranslationStatus, UseTranslateOptions, createLocaleDisplay, provideLocaleFieldContext, pruneLocaleMap, useLocaleField, useLocaleFieldContext, useLocaleTabs };

package/dist/locale/index.js

@@ -0,0 +1,140 @@
+import { computed, inject, provide, ref, toValue, watchEffect } from "vue";
+import { baseLocaleOf, resolveLocale } from "@octabits-io/framework/utils";
+//#region src/locale/pruneLocaleMap.ts
+/**
+* Drop empty-string leaves from a `LocaleMap<string>` so cleared tabs fall
+* back to the default locale instead of shadowing it with `''`. Returns a new
+* map; use `Object.keys(result).length` to decide between map and `null` when
+* the API expects `null` for "unset".
+*/
+function pruneLocaleMap(map) {
+	return Object.fromEntries(Object.entries(map ?? {}).filter(([, v]) => !!v));
+}
+//#endregion
+//#region src/locale/index.ts
+const LOCALE_FIELD_CONTEXT = Symbol("nuxt-ui-kit:locale-field-context");
+/** Provide the locale-field context (call once, near the app root). */
+function provideLocaleFieldContext(context) {
+	provide(LOCALE_FIELD_CONTEXT, context);
+}
+/** Resolve the locale-field context inside a component (throws when absent). */
+function useLocaleFieldContext() {
+	const context = inject(LOCALE_FIELD_CONTEXT, null);
+	if (!context) throw new Error("[nuxt-ui-kit] LocaleInput/LocaleTextarea need provideLocaleFieldContext() near the app root.");
+	return context;
+}
+/**
+* Tab plumbing shared by every per-locale field editor: one tab per content
+* locale, an active-tab ref, and the completeness indicator. Value access
+* stays with the caller — pass `hasValue` so the indicator works for any
+* value type (strings, rich-text documents, …).
+*
+* **Register variants** (e.g. `de-formal`, whose base `de` is also supported)
+* are a tone/overlay axis, not a real language: a label like "Hotel" is
+* identical in both. So variant tabs are **hidden by default** and only shown
+* when `registerOverride` is true (reader-addressing prose — descriptions,
+* body copy). When shown, a blank variant value *inherits* its base locale
+* (neutral hint, not a "missing" warning), and clearing the field should
+* **delete the key** so the resolver falls through to the base
+* (`de-formal → de`).
+*/
+function useLocaleTabs(hasValue, source, registerOverride = false) {
+	const supportedLocales = computed(() => toValue(source.locales));
+	const defaultLocale = computed(() => toValue(source.defaultLocale));
+	/** A locale whose base language is itself also supported (e.g. `de-formal` ⊂ `de`). */
+	const isVariant = (loc) => baseLocaleOf(loc) !== loc && supportedLocales.value.includes(baseLocaleOf(loc));
+	const visibleLocales = computed(() => {
+		const filtered = toValue(registerOverride) ? supportedLocales.value : supportedLocales.value.filter((loc) => !isVariant(loc));
+		return filtered.includes(defaultLocale.value) ? filtered : [...filtered, defaultLocale.value];
+	});
+	const active = ref("");
+	watchEffect(() => {
+		if (!visibleLocales.value.includes(active.value)) active.value = visibleLocales.value.includes(defaultLocale.value) ? defaultLocale.value : visibleLocales.value[0] ?? "";
+	});
+	/**
+	* A register variant carries a lowercase BCP-47 *variant* subtag (e.g.
+	* `de-formal`) — as opposed to a region (`de-AT`) or script (`zh-Hans`).
+	* Formality is a tenant-wide choice, so the tab reads as the plain language
+	* ("DE"), not the internal `DE-FORMAL` token.
+	*/
+	const REGISTER_VARIANT = /-[a-z]{4,8}$/;
+	const tabLabel = (loc) => (REGISTER_VARIANT.test(loc) ? baseLocaleOf(loc) : loc).toUpperCase();
+	const items = computed(() => visibleLocales.value.map((loc) => ({
+		label: tabLabel(loc),
+		value: loc
+	})));
+	const indicatorOf = (loc) => {
+		if (hasValue(loc)) return null;
+		if (isVariant(loc)) return { kind: "inherits" };
+		return loc === defaultLocale.value ? { kind: "error" } : { kind: "warning" };
+	};
+	/**
+	* Source locale for quick translate: the active tab when it has a value, so
+	* freshly edited text wins; otherwise the default locale, otherwise the
+	* first filled visible locale. `null` when every tab is empty. The fallback
+	* matters because the operator typically sits on the tab they want FILLED —
+	* translate must not go dead just because the active tab is the empty one.
+	*/
+	const translateSource = computed(() => {
+		if (hasValue(active.value)) return active.value;
+		if (hasValue(defaultLocale.value)) return defaultLocale.value;
+		return visibleLocales.value.find(hasValue) ?? null;
+	});
+	return {
+		items,
+		active,
+		indicatorOf,
+		isVariant,
+		defaultLocale,
+		visibleLocales,
+		translateSource,
+		translateTargets: computed(() => visibleLocales.value.filter((loc) => loc !== translateSource.value && !hasValue(loc) && (!isVariant(loc) || loc === defaultLocale.value)))
+	};
+}
+/**
+* String-valued locale field over a single `LocaleMap<string>` model — the
+* composable behind `LocaleInput` / `LocaleTextarea`. See
+* {@link useLocaleTabs} for the tab/indicator semantics.
+*/
+function useLocaleField(model, source, registerOverride = false) {
+	const hasValue = (loc) => {
+		const v = model.value?.[loc];
+		return typeof v === "string" && v.length > 0;
+	};
+	const { items, active, indicatorOf, isVariant, defaultLocale, translateSource, translateTargets } = useLocaleTabs(hasValue, source, registerOverride);
+	return {
+		items,
+		active,
+		activeValue: computed({
+			get: () => model.value?.[active.value] ?? "",
+			set: (val) => {
+				const next = { ...model.value ?? {} };
+				if (val === "" && isVariant(active.value)) delete next[active.value];
+				else next[active.value] = val;
+				model.value = next;
+			}
+		}),
+		indicatorOf,
+		defaultLocale,
+		translateSource,
+		translateTargets
+	};
+}
+/**
+* Resolve a `LocaleMap<string>` to a single display string for list / detail
+* surfaces, using the **default content locale** — deliberately decoupled
+* from the app's own UI language, which is unrelated chrome and would
+* otherwise select content arbitrarily. Lists therefore always show the
+* canonical value, consistently for every user; the per-locale values stay
+* fully editable via `LocaleInput` / `LocaleTextarea`.
+*/
+function createLocaleDisplay(source) {
+	/** Resolve a LocaleMap to its default-locale string, falling back when empty. */
+	function display(map, fallback = "") {
+		const defaultLocale = toValue(source.defaultLocale);
+		return resolveLocale(map, defaultLocale, defaultLocale) ?? fallback;
+	}
+	return { display };
+}
+//#endregion
+export { LOCALE_FIELD_CONTEXT, createLocaleDisplay, provideLocaleFieldContext, pruneLocaleMap, useLocaleField, useLocaleFieldContext, useLocaleTabs };