@revenexx/studio-shared 0.1.2 → 0.3.0

package/dist/runtime/components/Shared/Wizard.vue

@@ -0,0 +1,66 @@
+<script setup>
+import { Button } from "@revenexx/studio";
+const props = defineProps({
+  steps: { type: Array, required: true },
+  modelValue: { type: Number, required: false, default: 0 },
+  canAdvance: { type: Boolean, required: false, default: true },
+  busy: { type: Boolean, required: false, default: false }
+});
+const emit = defineEmits(["update:modelValue", "finish"]);
+const t = useT();
+const index = computed({
+  get: () => props.modelValue,
+  set: (v) => emit("update:modelValue", v)
+});
+const isFirst = computed(() => index.value === 0);
+const isLast = computed(() => index.value === props.steps.length - 1);
+const activeStep = computed(() => props.steps[index.value]);
+function back() {
+  if (!isFirst.value) index.value--;
+}
+function next() {
+  if (!props.canAdvance || props.busy) return;
+  if (isLast.value) emit("finish");
+  else index.value++;
+}
+function goTo(i) {
+  if (i < index.value) index.value = i;
+}
+</script>
+
+<template>
+  <div class="space-y-5">
+    <!-- Go-Live-style stepper: a fill bar + label per step, completed steps
+         are clickable to jump back. -->
+    <div class="flex gap-3">
+      <div
+        v-for="(s, i) in steps"
+        :key="s.key"
+        class="flex-1"
+        :class="i < index ? 'cursor-pointer' : ''"
+        @click="goTo(i)"
+      >
+        <div class="h-1 rounded-full transition-colors" :class="i <= index ? 'bg-primary' : 'bg-border'" />
+        <div class="mt-2 text-xs font-medium" :class="i <= index ? 'text-primary' : 'text-muted-foreground'">{{ t("shared.wizard.step.label", { number: i + 1 }) }}</div>
+        <div class="text-sm" :class="i <= index ? 'text-[#0B0522]' : 'text-muted-foreground'">{{ s.title }}</div>
+      </div>
+    </div>
+
+    <div>
+      <slot :step="activeStep" :index="index" />
+    </div>
+
+    <div class="flex items-center justify-between border-t pt-3">
+      <!-- Custom footer (e.g. multiple finish actions on a review step). Falls
+           back to the standard Back / Next·Finish pair. -->
+      <slot name="footer" :back="back" :next="next" :is-first="isFirst" :is-last="isLast" :can-advance="canAdvance" :busy="busy" :index="index">
+        <Button variant="ghost" :disabled="isFirst || busy" @click="back">
+          {{ t("shared.wizard.action.back") }}
+        </Button>
+        <Button :disabled="!canAdvance || busy" class="gap-1" @click="next">
+          {{ isLast ? t("shared.wizard.action.finish") : t("shared.wizard.action.next") }}
+        </Button>
+      </slot>
+    </div>
+  </div>
+</template>

package/dist/runtime/components/Shared/Wizard.vue.d.ts

@@ -0,0 +1,47 @@
+interface Step {
+    key: string;
+    title: string;
+    description?: string;
+}
+type __VLS_Props = {
+    steps: Step[];
+    modelValue?: number;
+    /** Gate the Next/Finish button for the current step. */
+    canAdvance?: boolean;
+    busy?: boolean;
+};
+declare var __VLS_1: {
+    step: any;
+    index: any;
+}, __VLS_3: {
+    back: any;
+    next: any;
+    isFirst: any;
+    isLast: any;
+    canAdvance: any;
+    busy: any;
+    index: any;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+} & {
+    footer?: (props: typeof __VLS_3) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (args_0: number) => any;
+    finish: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onUpdate:modelValue"?: ((args_0: number) => any) | undefined;
+    onFinish?: (() => any) | undefined;
+}>, {
+    modelValue: number;
+    canAdvance: boolean;
+    busy: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/composables/useListRail.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Open/closed state for a list surface's left rail, remembered per surface.
+ *
+ * The rail is a filter affordance, not content: an operator who collapsed it
+ * to give the table the full width expects it to stay collapsed on the next
+ * visit. Reads happen on mount (SSR-safe) and every change is written back;
+ * a browser without usable storage simply keeps the state for the session.
+ */
+export declare function useListRail(key: string, initial?: boolean): any;

package/dist/runtime/composables/useListRail.js

@@ -0,0 +1,19 @@
+export function useListRail(key, initial = true) {
+  const storageKey = `commerce.listRail.${key}`;
+  const open = ref(initial);
+  onMounted(() => {
+    try {
+      const raw = window.localStorage.getItem(storageKey);
+      if (raw != null) open.value = raw === "1";
+    } catch {
+    }
+  });
+  watch(open, (v) => {
+    try {
+      if (typeof window === "undefined") return;
+      window.localStorage.setItem(storageKey, v ? "1" : "0");
+    } catch {
+    }
+  });
+  return open;
+}

package/dist/runtime/composables/useMediaLibrary.d.ts

@@ -0,0 +1,41 @@
+import type { Ref } from 'vue';
+import type { StorageAsset, StorageFolder, StorageFolderNode, UploadProgress } from '../types/storage.js';
+/**
+ * Media library provider seam — the storage client behind the shared media
+ * components (`MediaUploader`, `MediaPickerDialog`, `MediaFolderTree`).
+ *
+ * Same shape as the `usePlatformAuth` / `usePlatformTenant` contract: the
+ * components never import a host's storage client, they call this. The
+ * standalone default below is inert (no assets, uploads report as failed), so a
+ * module host that hasn't wired Storage still renders the dialogs instead of
+ * crashing. The full cockpit overrides it at `app/composables/useMediaLibrary.ts`
+ * — an app-level auto-import beats this module-registered one (priority -1).
+ */
+export type { StorageAsset, StorageFolder, StorageFolderNode, UploadProgress };
+export interface MediaLibraryClient {
+    /** Assets in the current view. */
+    assets: Ref<StorageAsset[]>;
+    /** Folders nested by `parent_id`, each level sorted by name. */
+    folderTree: Ref<StorageFolderNode[]>;
+    currentFolderId: Ref<string | null>;
+    /** 'all' = every asset; 'unfiled' = folder-less; 'folder' = `currentFolderId`. */
+    currentView: Ref<'all' | 'unfiled' | 'folder'>;
+    currentFolder: Ref<StorageFolder | null>;
+    loadingAssets: Ref<boolean>;
+    hasMore: Ref<boolean>;
+    /** Load folders + the current view's assets. */
+    init: () => Promise<void>;
+    openFolder: (folderId: string) => Promise<void>;
+    showAllMedia: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    /** Upload a batch into `folderId`, reporting per-file progress. */
+    uploadMany: (files: File[], folderId?: string | null, onItem?: (index: number, progress: UploadProgress) => void) => Promise<{
+        created: number;
+        failed: number;
+    }>;
+    /** Displayable thumbnail URL, or null when the kind has no preview. */
+    thumbnailUrl: (asset: StorageAsset, size?: number) => string | null;
+    /** True while the asset is still being scanned/processed. */
+    isProcessing: (asset: StorageAsset) => boolean;
+}
+export declare function useMediaLibrary(): MediaLibraryClient;

package/dist/runtime/composables/useMediaLibrary.js

@@ -0,0 +1,36 @@
+import { computed, ref } from "vue";
+export function useMediaLibrary() {
+  const assets = ref([]);
+  const folderTree = ref([]);
+  const currentFolderId = ref(null);
+  const currentView = ref("all");
+  const currentFolder = computed(() => null);
+  const loadingAssets = ref(false);
+  const hasMore = ref(false);
+  const noop = async () => {
+  };
+  return {
+    assets,
+    folderTree,
+    currentFolderId,
+    currentView,
+    currentFolder,
+    loadingAssets,
+    hasMore,
+    init: noop,
+    openFolder: noop,
+    showAllMedia: noop,
+    loadMore: noop,
+    async uploadMany(files, _folderId, onItem) {
+      files.forEach((file, i) => onItem?.(i, {
+        name: file.name,
+        pct: 0,
+        status: "failed",
+        error: useT()("shared.media.uploader.error.nostorage")
+      }));
+      return { created: 0, failed: files.length };
+    },
+    thumbnailUrl: () => null,
+    isProcessing: () => false
+  };
+}

package/dist/runtime/composables/usePlatformAuth.d.ts

@@ -0,0 +1,35 @@
+import type { Ref } from 'vue';
+/**
+ * Platform auth provider — the seam that lets a studio surface run either
+ * inside the full cockpit or standalone.
+ *
+ * This is the **standalone default**: it sources a bearer token from runtime
+ * config (`NUXT_PUBLIC_DEV_TOKEN`) or `localStorage['console.token']`. The
+ * full cockpit ships an override at `app/composables/usePlatformAuth.ts`
+ * (app-level auto-imports take precedence over this module's) that returns the
+ * real Appwrite/Console-sourced operator token.
+ *
+ * Studio modules (e.g. `@revenexx/studio-integrations`) call this instead of
+ * `useConsoleAuth` directly, so they carry no cockpit-only dependency.
+ */
+export interface PlatformAuth {
+    getToken: () => Promise<string | null>;
+    /**
+     * Whether a token is available NOW, as a reactive flag. OPTIONAL, because the
+     * standalone default below has nothing to report — a value in `localStorage` is
+     * either there or not, with no moment at which it becomes there.
+     *
+     * It exists for the hosts where `getToken()` legitimately answers null for a
+     * while and then starts working: the cockpit's override refreshes through
+     * `useConsoleAuth`, which backs off for 15s after a failed refresh and returns
+     * null for the duration. A consumer that only reacts to something ELSE changing
+     * — `usePlatformTalkback` watched the tenant slug — never retries and stays
+     * dead for the life of the tab.
+     *
+     * Deliberately a flag rather than the token itself: nothing outside the auth
+     * seam should hold a token it did not just ask for, and a stale one in a `ref`
+     * is exactly how that happens.
+     */
+    ready?: Readonly<Ref<boolean>>;
+}
+export declare function usePlatformAuth(): PlatformAuth;

package/dist/runtime/composables/usePlatformAuth.js

@@ -0,0 +1,17 @@
+export function usePlatformAuth() {
+  const config = useRuntimeConfig();
+  return {
+    async getToken() {
+      const fromConfig = config.public.devToken || null;
+      if (fromConfig) return fromConfig;
+      if (import.meta.client) {
+        try {
+          return localStorage.getItem("console.token");
+        } catch {
+          return null;
+        }
+      }
+      return null;
+    }
+  };
+}

package/dist/runtime/composables/usePlatformTalkback.d.ts

@@ -0,0 +1,29 @@
+import type { ShallowRef } from 'vue';
+import type { Talkback } from '@revenexx/talkback-js';
+/**
+ * Platform realtime provider — the third seam beside `usePlatformAuth` and
+ * `usePlatformTenant`, and it composes both of them.
+ *
+ * A studio module never builds a Talkback client itself: it calls
+ * `useTalkbackTopic()` / `useTalkbackResource()` and this decides whether there
+ * is a connection behind them. One client for the whole application — a second
+ * `createTalkback` would open a second WebSocket and mint its own connection
+ * token.
+ *
+ * OFF IS A FIRST-CLASS STATE. An empty `talkbackHost` means no client is built,
+ * neither `@revenexx/talkback-js` nor `centrifuge` is loaded, and the channel
+ * composables become no-ops — so a call site needs no guard and a host that has
+ * no realtime stack is not half-connected. That is also the production gate: the
+ * edge has not been shown to pass a WebSocket upgrade yet (PE-382 T0.2).
+ */
+export interface PlatformTalkback {
+    /**
+     * The client, or `null` while it is still loading or realtime is off.
+     * Reactive: the client arrives after a dynamic import, so a component that
+     * rendered first has to be able to pick it up.
+     */
+    talkback: ShallowRef<Talkback | null>;
+    /** Whether this host has realtime configured at all. */
+    enabled: boolean;
+}
+export declare function usePlatformTalkback(): PlatformTalkback;

package/dist/runtime/composables/usePlatformTalkback.js

@@ -0,0 +1,54 @@
+import { watch } from "vue";
+import { createPlatformTalkback, setTalkback, talkbackRef } from "../lib/talkback.js";
+function withAppBase(baseURL, path) {
+  if (/^https?:\/\//.test(path)) return path;
+  const base = (baseURL || "/").replace(/\/+$/, "");
+  return `${base}/${path.replace(/^\/+/, "")}`;
+}
+let started = false;
+export function usePlatformTalkback() {
+  const config = useRuntimeConfig();
+  const host = String(config.public.talkbackHost || "");
+  const enabled = Boolean(host);
+  if (enabled && import.meta.client && !started) {
+    started = true;
+    const { getToken, ready: authReady } = usePlatformAuth();
+    const { slug, load } = usePlatformTenant();
+    const baseURL = String(config.app?.baseURL || "/");
+    const facade = host.replace(/\/+$/, "");
+    const tokenEndpoint = withAppBase(baseURL, String(config.public.talkbackTokenEndpoint || `${facade}/v1/tokens`));
+    const subscriptionTokenEndpoint = withAppBase(baseURL, String(config.public.talkbackSubscriptionTokenEndpoint || `${facade}/v1/subscription-tokens`));
+    const start = (async () => {
+      const tb = await createPlatformTalkback({
+        host,
+        tokenEndpoint,
+        subscriptionTokenEndpoint,
+        tenant: () => slug.value ?? "",
+        getToken
+      });
+      setTalkback(tb);
+      let applied = null;
+      async function sync() {
+        if (!slug.value) {
+          try {
+            await load();
+          } catch {
+          }
+        }
+        const token = await getToken();
+        const next = slug.value && token ? slug.value : null;
+        if (next === applied) return;
+        tb.disconnect();
+        applied = next;
+        if (next) tb.connect();
+      }
+      const inputs = authReady ? [slug, authReady] : [slug];
+      watch(inputs, () => void sync(), { immediate: true });
+    })();
+    void start.catch((error) => {
+      if (!talkbackRef().value) started = false;
+      console.warn("[studio-shared] talkback failed to start", error);
+    });
+  }
+  return { talkback: talkbackRef(), enabled };
+}

package/dist/runtime/composables/usePlatformTenant.d.ts

@@ -0,0 +1,14 @@
+import type { Ref } from 'vue';
+/**
+ * Platform tenant provider — companion to `usePlatformAuth`.
+ *
+ * Standalone default: the active tenant slug comes from runtime config
+ * (`NUXT_PUBLIC_DEV_TENANT`) or `localStorage['cockpit.devTenant']`. The full
+ * cockpit overrides this at `app/composables/usePlatformTenant.ts` to return
+ * the real active-tenant slug from `useConsoleTenants`.
+ */
+export interface PlatformTenant {
+    slug: Ref<string | null>;
+    load: () => Promise<void>;
+}
+export declare function usePlatformTenant(): PlatformTenant;

package/dist/runtime/composables/usePlatformTenant.js

@@ -0,0 +1,18 @@
+import { computed, ref } from "vue";
+export function usePlatformTenant() {
+  const config = useRuntimeConfig();
+  const stored = ref(null);
+  if (import.meta.client) {
+    try {
+      stored.value = localStorage.getItem("cockpit.devTenant");
+    } catch {
+      stored.value = null;
+    }
+  }
+  const slug = computed(() => config.public.devTenant || stored.value);
+  return {
+    slug,
+    async load() {
+    }
+  };
+}

package/dist/runtime/composables/useT.d.ts

@@ -0,0 +1,11 @@
+import type { ComputedRef } from 'vue';
+import type { Translate } from '../lib/i18nBridge.js';
+export declare function useT(): Translate;
+/**
+ * The host's current UI locale (`'en'` when the host has no i18n).
+ *
+ * This is the INTERFACE language, not a content locale: it says which language
+ * the chrome is in, never which locale of a `labels` jsonb to show. For the
+ * latter see `useTenantLocales()` in `@revenexx/studio-commerce`.
+ */
+export declare function useUiLocale(): ComputedRef<string>;

package/dist/runtime/composables/useT.js

@@ -0,0 +1,8 @@
+import { computed } from "vue";
+import { currentLocale, translate } from "../lib/i18nBridge.js";
+export function useT() {
+  return translate;
+}
+export function useUiLocale() {
+  return computed(() => currentLocale());
+}

package/dist/runtime/composables/useTalkbackChannels.d.ts

@@ -0,0 +1,78 @@
+import type { ComputedRef } from 'vue';
+import type { EnvelopeListener, RawListener, ResyncContext } from '@revenexx/talkback-js';
+import type { MaybeRefOrGetter } from '@revenexx/talkback-js/vue';
+/**
+ * The five channel composables, re-exported through this package so a studio
+ * module can subscribe with a bare name and carry no Talkback dependency of its
+ * own — the same contract `usePlatformAuth` / `usePlatformTenant` already have.
+ *
+ * THREE THINGS THESE WRAPPERS ADD, and each is a bug without them:
+ *
+ * 1. **The client is passed explicitly, never injected.** talkback-js's
+ *    `useTalkback()` reads a module-PRIVATE `Symbol`, so two copies of the
+ *    package are two different keys: it throws inside a studio module while the
+ *    host looks healthy. Its `talkback` option exists for exactly this, and
+ *    using it means no consumer has to know a plugin ran in the right order.
+ *
+ * 2. **They tolerate a client that does not exist yet.** The client arrives
+ *    after a dynamic import, so any component that rendered first would
+ *    otherwise subscribe to nothing and never retry. The delegate runs in a
+ *    child `effectScope` that is created when the client appears and stopped
+ *    with the caller's scope — which is also what gives the delegate's own
+ *    `onScopeDispose(release)` a scope to bind to.
+ *
+ * 3. **`channel` is actually reactive.** Up to and including
+ *    `@revenexx/talkback-js@0.1.3`, `ChannelSubscription.channel` is
+ *    `{ value: null }` cast to a `Ref` — `ref` is never imported, so `isRef()`
+ *    is false and a template binding never updates. Fixed upstream in
+ *    talkback-js#11 but unreleased; this wrapper can be simplified to a
+ *    pass-through once that ships.
+ *
+ * With realtime off (`talkbackHost` empty) every one of these is a no-op that
+ * reports a null channel, so a call site needs no `if (enabled)`.
+ */
+/** Re-exported so a consumer types a ref-able argument without importing talkback-js. */
+export type TalkbackMaybeRef<T> = MaybeRefOrGetter<T>;
+export interface TalkbackChannelOptions {
+    /** One action, or several. Omit to receive every action on the channel. */
+    on?: string | readonly string[];
+    /** Called for each matching envelope. Events are refetch signals, not state. */
+    handler?: EnvelopeListener;
+    /** Every publication, envelope or not — how a `stream:` channel is read. */
+    raw?: RawListener;
+    /** The recovery buffer could not close the gap: refetch over HTTP. */
+    onResync?: (ctx: ResyncContext) => void;
+    /** Skip subscribing, e.g. while a route parameter is still empty. */
+    enabled?: TalkbackMaybeRef<boolean>;
+}
+export interface TalkbackChannel {
+    /** The currently subscribed channel, or null when nothing is subscribed. */
+    channel: ComputedRef<string | null>;
+    /** Releases early. Called automatically when the calling scope is disposed. */
+    stop: () => void;
+}
+/**
+ * The ACTION channel for a topic — a grid watching every instance of a kind.
+ *
+ * THE TOPIC INCLUDES THE ACTION, and one action is one channel (Centrifugo has
+ * no wildcards), so a grid watching three actions takes three calls:
+ *
+ * ```ts
+ * for (const action of ['started', 'finished', 'failed'] as const) {
+ *   useTalkbackTopic(`revenexx.integrations.run.${action}`, { handler: () => load(true) })
+ * }
+ * ```
+ */
+export declare function useTalkbackTopic(topic: TalkbackMaybeRef<string>, options?: TalkbackChannelOptions): TalkbackChannel;
+/**
+ * The RESOURCE channel — one detail view, every action on it. The id may be a
+ * ref or a getter, and the subscription follows it, releasing the old channel
+ * before taking the new one.
+ */
+export declare function useTalkbackResource(topic: TalkbackMaybeRef<string>, topicId: TalkbackMaybeRef<string | null | undefined>, options?: TalkbackChannelOptions): TalkbackChannel;
+/** The signed-in user's own channel — notifications and toasts. */
+export declare function useTalkbackUser(options?: TalkbackChannelOptions): TalkbackChannel;
+/** A `stream:` channel. `onResync` fires on EVERY subscribe here — it keeps no history. */
+export declare function useTalkbackStream(streamId: TalkbackMaybeRef<string | null | undefined>, options?: TalkbackChannelOptions): TalkbackChannel;
+/** Who else is looking at this resource. */
+export declare function useTalkbackPresence(vendor: TalkbackMaybeRef<string>, app: TalkbackMaybeRef<string>, entity: TalkbackMaybeRef<string>, id?: TalkbackMaybeRef<string | null | undefined>, options?: TalkbackChannelOptions): TalkbackChannel;

package/dist/runtime/composables/useTalkbackChannels.js

@@ -0,0 +1,52 @@
+import { computed, effectScope, onScopeDispose, ref, shallowRef, watch } from "vue";
+import { talkbackRef } from "../lib/talkback.js";
+function useDelegate(subscribe) {
+  const client = talkbackRef();
+  const name = ref(null);
+  const scope = shallowRef(null);
+  function stop() {
+    scope.value?.stop();
+    scope.value = null;
+    name.value = null;
+  }
+  const unwatch = watch(client, (tb) => {
+    stop();
+    if (!tb) return;
+    const child = effectScope();
+    scope.value = child;
+    void (async () => {
+      const vue = await import("@revenexx/talkback-js/vue");
+      if (scope.value !== child) return;
+      child.run(() => {
+        let sub;
+        try {
+          sub = subscribe(vue, tb);
+        } catch {
+          name.value = null;
+          return;
+        }
+        watch(() => sub.channel.value, (v) => name.value = v, { immediate: true, flush: "sync" });
+      });
+    })();
+  }, { immediate: true });
+  onScopeDispose(() => {
+    unwatch();
+    stop();
+  });
+  return { channel: computed(() => name.value), stop };
+}
+export function useTalkbackTopic(topic, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackTopic(topic, { ...options, talkback: tb }));
+}
+export function useTalkbackResource(topic, topicId, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackResource(topic, topicId, { ...options, talkback: tb }));
+}
+export function useTalkbackUser(options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackUser({ ...options, talkback: tb }));
+}
+export function useTalkbackStream(streamId, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackStream(streamId, { ...options, talkback: tb }));
+}
+export function useTalkbackPresence(vendor, app, entity, id = () => null, options = {}) {
+  return useDelegate((vue, tb) => vue.useTalkbackPresence(vendor, app, entity, id, { ...options, talkback: tb }));
+}

package/dist/runtime/lib/formatBridge.d.ts

@@ -0,0 +1,50 @@
+import type { Ref } from 'vue';
+/**
+ * What the host registers: both reactive, so a computed that formatted once
+ * re-runs when the operator changes the preference — no reload.
+ */
+export interface FormatPreferenceSource {
+    /** Resolved BCP-47 tag, e.g. `de-AT`. Never `'auto'` — the host resolves. */
+    locale: Ref<string>;
+    /**
+     * `true` forces a 12-hour clock, `false` a 24-hour one, `undefined` leaves
+     * the choice to the locale's own convention (which is what `Intl` does when
+     * the option is absent).
+     */
+    hour12: Ref<boolean | undefined>;
+}
+/** Used when there is no host AND no i18n bridge. See the file comment. */
+export declare const FALLBACK_FORMAT_LOCALE = "en-GB";
+/**
+ * The region an `auto` preference resolves to for a UI language.
+ *
+ * Takes the language subtag, so `en-US` and `en` land on the same answer, and
+ * falls back to {@link FALLBACK_FORMAT_LOCALE} for a language we do not ship.
+ */
+export declare function defaultRegionForLanguage(language: string | null | undefined): string;
+/** Called once by the host. Pass `null` to detach (tests). */
+export declare function setFormatPreferences(source: FormatPreferenceSource | null): void;
+/** Whether a host preference is installed. Rarely needed — prefer the getters. */
+export declare function hasFormatPreferences(): boolean;
+/** The BCP-47 tag every package should format in. */
+export declare function formatLocale(): string;
+/** The operator's clock, or `undefined` to let the locale decide. */
+export declare function hour12(): boolean | undefined;
+/**
+ * A cached `DateTimeFormat` for an explicitly given locale and clock.
+ *
+ * The host uses this one: it has already resolved both from its own reactive
+ * state and must not have the answer re-derived from a registry it may not
+ * have populated yet. Packages want {@link dateTimeFormat}.
+ *
+ * `clock` is folded into the options rather than left to each call site, but an
+ * explicit `hour12` in `options` still wins — a cell that must print a 24-hour
+ * timestamp regardless (a log line, a cron preview) can say so.
+ */
+export declare function dateTimeFormatFor(locale: string, options?: Intl.DateTimeFormatOptions, clock?: boolean): Intl.DateTimeFormat;
+/** A cached `NumberFormat` for an explicitly given locale. */
+export declare function numberFormatFor(locale: string, options?: Intl.NumberFormatOptions): Intl.NumberFormat;
+/** A `DateTimeFormat` for whatever the host registered. What packages call. */
+export declare function dateTimeFormat(options?: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+/** A `NumberFormat` for whatever the host registered. What packages call. */
+export declare function numberFormat(options?: Intl.NumberFormatOptions): Intl.NumberFormat;

package/dist/runtime/lib/formatBridge.js

@@ -0,0 +1,54 @@
+import { shallowRef } from "vue";
+import { currentLocale } from "./i18nBridge.js";
+export const FALLBACK_FORMAT_LOCALE = "en-GB";
+const DEFAULT_REGION_BY_LANGUAGE = {
+  de: "de-DE",
+  en: "en-GB"
+};
+export function defaultRegionForLanguage(language) {
+  if (!language) return FALLBACK_FORMAT_LOCALE;
+  const subtag = String(language).split(/[-_]/)[0].toLowerCase();
+  return DEFAULT_REGION_BY_LANGUAGE[subtag] ?? FALLBACK_FORMAT_LOCALE;
+}
+const registered = shallowRef(null);
+export function setFormatPreferences(source) {
+  registered.value = source;
+}
+export function hasFormatPreferences() {
+  return registered.value !== null;
+}
+export function formatLocale() {
+  const source = registered.value;
+  if (source) return source.locale.value;
+  return defaultRegionForLanguage(currentLocale());
+}
+export function hour12() {
+  return registered.value?.hour12.value;
+}
+const dateTimeFormats = /* @__PURE__ */ new Map();
+const numberFormats = /* @__PURE__ */ new Map();
+export function dateTimeFormatFor(locale, options = {}, clock) {
+  const resolved = clock === void 0 || "hour12" in options ? options : { ...options, hour12: clock };
+  const key = `${locale}|${JSON.stringify(resolved)}`;
+  let format = dateTimeFormats.get(key);
+  if (!format) {
+    format = new Intl.DateTimeFormat(locale, resolved);
+    dateTimeFormats.set(key, format);
+  }
+  return format;
+}
+export function numberFormatFor(locale, options = {}) {
+  const key = `${locale}|${JSON.stringify(options)}`;
+  let format = numberFormats.get(key);
+  if (!format) {
+    format = new Intl.NumberFormat(locale, options);
+    numberFormats.set(key, format);
+  }
+  return format;
+}
+export function dateTimeFormat(options = {}) {
+  return dateTimeFormatFor(formatLocale(), options, hour12());
+}
+export function numberFormat(options = {}) {
+  return numberFormatFor(formatLocale(), options);
+}