@revenexx/studio-shared 0.2.0 → 0.3.1

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

@@ -0,0 +1,41 @@
+/**
+ * Which of a DataTable's columns are drawn.
+ *
+ * Pulled out of `DataTable.vue` because the rule has a trap in it that a
+ * component test would not have caught cheaply, and that shipped once already.
+ *
+ * A table's column list is NOT fixed for the life of the component. A tab that
+ * only offers Markets once the service proves it has the column, or a validity
+ * window once the deployment has grown one, hands the table a LONGER array on a
+ * later render than the one it was set up with.
+ *
+ * The table used to seed a set of visible keys once and filter by membership.
+ * Every column that turned up afterwards was therefore missing from that set and
+ * arrived SWITCHED OFF — present in the picker, unticked, and invisible to
+ * everybody who did not go looking. Nobody reports that: from the outside it
+ * looks like the column was never built.
+ *
+ * So what is remembered is the user's own decisions — the columns they ticked
+ * away — and everything else follows its declared default. A column that
+ * appears later gets that default, which is what somebody adding a column
+ * expects and what the previous rule quietly denied them.
+ */
+export interface VisibilityColumn {
+    key: string;
+    /** `false` means "start hidden". Absent means shown. */
+    visible?: boolean;
+}
+/**
+ * The columns hidden before the user has touched anything — the declared
+ * defaults, and nothing else.
+ */
+export declare function initiallyHidden(columns: readonly VisibilityColumn[]): Set<string>;
+/**
+ * The columns to draw: everything except what the user put away.
+ *
+ * Deliberately keyed on hidden rather than on visible. The set of things a
+ * person has decided against is stable; the set of things that exist is not.
+ */
+export declare function visibleColumnsOf<T extends VisibilityColumn>(columns: readonly T[], hidden: ReadonlySet<string>): T[];
+/** Add or remove one column from the user's hidden set. */
+export declare function toggleHidden(hidden: ReadonlySet<string>, key: string): Set<string>;

package/dist/runtime/lib/columnVisibility.js

@@ -0,0 +1,12 @@
+export function initiallyHidden(columns) {
+  return new Set(columns.filter((c) => c.visible === false).map((c) => c.key));
+}
+export function visibleColumnsOf(columns, hidden) {
+  return columns.filter((c) => !hidden.has(c.key));
+}
+export function toggleHidden(hidden, key) {
+  const next = new Set(hidden);
+  if (next.has(key)) next.delete(key);
+  else next.add(key);
+  return next;
+}

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

@@ -0,0 +1,83 @@
+/**
+ * What a row's value is for a filter dimension — and why it can be several.
+ *
+ * Pulled out of `DataTable.vue` because the rule underneath it changed shape,
+ * and the change is the kind that reads as harmless and is not.
+ *
+ * ## A row used to belong to exactly one bucket
+ *
+ * `getter: (row) => string` gives every row ONE value per dimension. For status
+ * or channel that is the truth. For anything a row can have several of — the
+ * languages a template is written in, the markets it is scoped to, the tags on
+ * a product — it is not, and the only way to express it was to make the SET the
+ * value:
+ *
+ *   getter: r => r.locales.join(', ')
+ *
+ * which produces a filter menu that reads
+ *
+ *   Deutsch (Deutschland)                                              2
+ *   Deutsch (Deutschland) + British English                           19
+ *   Deutsch (Deutschland) + British English + polski (Polska)          2
+ *   Deutsch (Deutschland) + British English + français + polski        1
+ *   …
+ *
+ * Two things are wrong with that and only one of them is cosmetic.
+ *
+ * The visible one: the options are COMBINATIONS, so the list grows with the
+ * powerset of the values. Four languages produce up to fifteen entries, six up
+ * to sixty-three. No menu, panel or layout survives that.
+ *
+ * The one that matters: "which of these have Polish?" cannot be asked. The
+ * answer is spread across three options, and none of the counts is it. An
+ * operator who picks the option that looks closest gets a confident, wrong
+ * number — the counts adding up to exactly the row total is the tell that this
+ * is a partition rather than a set of overlapping questions.
+ *
+ * ## So a getter may now return an array
+ *
+ * `string | string[] | null | undefined`. A row lands in as many buckets as it
+ * has values, the options become the four languages rather than the fifteen
+ * combinations, and "polski 6" means what it says.
+ *
+ * ## The string path is byte-for-byte what it was
+ *
+ * Deliberately: every existing surface passes a string getter and none of them
+ * should move a pixel. A string — INCLUDING the empty string — is one value,
+ * and `null`/`undefined` still collapse to `''` and count under that key, which
+ * is what the old `String(getter(row) ?? '')` did. Only the array path is new.
+ *
+ * Inside an array, empty entries ARE dropped: a template with no languages
+ * belongs to no language, and letting it pile into a `''` bucket would invent a
+ * silent option nobody declared.
+ *
+ * ## The counts stop summing to the row total, on purpose
+ *
+ * For a multi-valued dimension they now overlap, because a row with three
+ * languages is counted under three of them. That looks like a bug to anybody
+ * who checks the arithmetic, and correcting it would restore exactly the
+ * defect this exists to remove.
+ */
+export type FilterGetter<T> = (row: T) => string | string[] | null | undefined;
+/**
+ * The buckets one row belongs to for one dimension.
+ *
+ * Always an array, so the caller never has to branch on which shape the surface
+ * happened to hand over.
+ */
+export declare function filterValues<T>(getter: FilterGetter<T>, row: T): string[];
+/** How many rows sit in each bucket. Overlapping where a row has several. */
+export declare function countByValue<T>(rows: readonly T[], getter: FilterGetter<T>): Record<string, number>;
+/**
+ * Does a row survive one dimension's active selection?
+ *
+ * `active` may be one value or SEVERAL, because the filter panel that replaced
+ * the old cascading menu lets a reader tick more than one option in a facet.
+ * Several means ANY of them — "Active or Draft", not "Active and Draft", which
+ * is the only reading that can ever match anything: a row has one status.
+ *
+ * Not filtering is `null`, `undefined` or an EMPTY array, and none of those is
+ * the same as filtering on nothing. "All" is the absence of a choice, and a row
+ * whose value happens to be `''` must not be the only thing that survives it.
+ */
+export declare function matchesFilter<T>(getter: FilterGetter<T>, row: T, active: string | readonly string[] | null | undefined): boolean;

package/dist/runtime/lib/dataTableFilters.js

@@ -0,0 +1,23 @@
+export function filterValues(getter, row) {
+  const raw = getter(row);
+  if (Array.isArray(raw)) {
+    return raw.map((v) => String(v ?? "")).filter((v) => v !== "");
+  }
+  return [String(raw ?? "")];
+}
+export function countByValue(rows, getter) {
+  const counts = {};
+  for (const row of rows) {
+    for (const value of filterValues(getter, row)) {
+      counts[value] = (counts[value] ?? 0) + 1;
+    }
+  }
+  return counts;
+}
+export function matchesFilter(getter, row, active) {
+  if (active == null) return true;
+  const wanted = typeof active === "string" ? [active] : active;
+  if (!wanted.length) return true;
+  const values = filterValues(getter, row);
+  return wanted.some((v) => values.includes(v));
+}

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);
+}

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

@@ -0,0 +1,36 @@
+import type { Ref } from 'vue';
+/** Interpolation values for a message with `{placeholders}`. */
+export type TranslateNamed = Record<string, unknown>;
+/**
+ * The subset of vue-i18n's `t` the packages are allowed to rely on:
+ * `t(key)`, `t(key, named)`, `t(key, plural)`, `t(key, named, plural)`.
+ *
+ * The last one is the order vue-i18n takes for a plural message that also has
+ * placeholders. Its `(key, plural, third)` overload reads the third argument as
+ * `TranslateOptions`, so a bare named bag passed there interpolates nothing —
+ * hence only the named-first form is offered here.
+ */
+export interface Translate {
+    (key: string): string;
+    (key: string, named: TranslateNamed): string;
+    (key: string, plural: number): string;
+    (key: string, named: TranslateNamed, plural: number): string;
+}
+export interface Translator {
+    t: Translate;
+    /** The host's current UI locale. Reactive, so computeds re-run on a switch. */
+    locale: Ref<string>;
+}
+/** Called once by the host. Pass `null` to detach (tests). */
+export declare function setTranslator(translator: Translator | null): void;
+/** Whether a host translator is installed. Rarely needed — prefer `translate`. */
+export declare function hasTranslator(): boolean;
+/** The host's current UI locale, or `'en'` when the host has no i18n. */
+export declare function currentLocale(): string;
+/**
+ * Translate through the host, or return the key unchanged.
+ *
+ * Reads `locale.value` before delegating so the caller picks up a reactive
+ * dependency on the locale even if the host's `t` were to memoize.
+ */
+export declare const translate: Translate;

package/dist/runtime/lib/i18nBridge.js

@@ -0,0 +1,17 @@
+import { shallowRef } from "vue";
+const registered = shallowRef(null);
+export function setTranslator(translator) {
+  registered.value = translator;
+}
+export function hasTranslator() {
+  return registered.value !== null;
+}
+export function currentLocale() {
+  return registered.value?.locale.value ?? "en";
+}
+export const translate = ((key, ...args) => {
+  const translator = registered.value;
+  if (!translator) return key;
+  void translator.locale.value;
+  return translator.t(key, ...args);
+});

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

@@ -0,0 +1,61 @@
+/**
+ * The two international lists every studio ends up needing: countries
+ * (ISO 3166-1 alpha-2) and currencies (ISO 4217).
+ *
+ * They live in `studio-shared` rather than in a studio because a country is
+ * not a Commerce concern — Mail wants a sender country, Analytics wants a
+ * region breakdown, and whichever surface asked second would otherwise make
+ * the second copy. This module is that first copy, and the only one.
+ *
+ * ## Codes are data, names are derived
+ *
+ * The country CODES are written out here, because that literally is the
+ * standard: 249 two-letter identifiers, stable, and not enumerable from any
+ * runtime API. The NAMES are not written out — `Intl.DisplayNames` has them
+ * for every locale the browser ships, so a German cockpit reads
+ * "Vereinigtes Königreich" without anyone translating a hardcoded English
+ * list. Currencies need neither: `Intl.supportedValuesOf('currency')` is the
+ * code list, and `Intl.DisplayNames` is the names.
+ *
+ * The practical consequence is that adding a language costs nothing here.
+ *
+ * ## Sorted by the label, never by the code
+ *
+ * An operator scans a country list alphabetically by what they read.
+ * "Ägypten" belongs at the top of a German list and "Egypt" belongs under E;
+ * sorting by `EG` would put it in neither place. So every list is collated in
+ * the locale it is being displayed in, and the sort is redone per locale.
+ * The result is cached per locale — the collation is the expensive part and
+ * the answer never changes within a session.
+ */
+/**
+ * The locale the lists are labelled in when a caller does not say. The cockpit
+ * is German-facing; when a real `useLocale()` lands, pass it through and this
+ * default stops being used.
+ */
+export declare const DEFAULT_ISO_LOCALE = "de";
+/** One choice: the stored code plus what a human reads in their language. */
+export interface IsoOption {
+    /** The value written to the column — `'DE'`, `'EUR'`. */
+    code: string;
+    /** Localized name — `'Deutschland'`, `'Euro'`. Falls back to the code. */
+    label: string;
+}
+/** ISO 3166-1 alpha-2, unsorted. Use `countryOptions()` to display them. */
+export declare function countryCodes(): readonly string[];
+/**
+ * ISO 4217, as the runtime knows it. Empty on an engine without
+ * `Intl.supportedValuesOf` — callers treat that like any other unresolvable
+ * list and fall back to whatever literal options they were given.
+ */
+export declare function currencyCodes(): readonly string[];
+/** Drop the memoised lists — for tests, and after a language switch. */
+export declare function clearIsoListCache(): void;
+/** Every country, sorted by its name in `locale`. */
+export declare function countryOptions(locale?: string): IsoOption[];
+/** Every currency the runtime knows, sorted by its name in `locale`. */
+export declare function currencyOptions(locale?: string): IsoOption[];
+/** `'DE'` → `'Deutschland'`. Unknown codes come back unchanged. */
+export declare function countryLabel(code: unknown, locale?: string): string;
+/** `'EUR'` → `'Euro'`. Unknown codes come back unchanged. */
+export declare function currencyLabel(code: unknown, locale?: string): string;

package/dist/runtime/lib/isoLists.js

@@ -0,0 +1,62 @@
+const COUNTRY_CODES = Object.freeze(
+  "AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW".split(" ")
+);
+export const DEFAULT_ISO_LOCALE = "de";
+export function countryCodes() {
+  return COUNTRY_CODES;
+}
+export function currencyCodes() {
+  const supported = Intl.supportedValuesOf;
+  if (typeof supported !== "function") return [];
+  try {
+    return Object.freeze(supported.call(Intl, "currency"));
+  } catch {
+    return [];
+  }
+}
+function displayNames(type, locale) {
+  try {
+    return new Intl.DisplayNames([locale], { type, fallback: "code" });
+  } catch {
+    return null;
+  }
+}
+function collator(locale) {
+  try {
+    return new Intl.Collator(locale);
+  } catch {
+    return { compare: (a, b) => a < b ? -1 : a > b ? 1 : 0 };
+  }
+}
+function build(codes, type, locale) {
+  const names = displayNames(type, locale);
+  const compare = collator(locale).compare;
+  return codes.map((code) => ({ code, label: names?.of(code) || code })).sort((a, b) => compare(a.label, b.label));
+}
+const cache = /* @__PURE__ */ new Map();
+function cached(key, make) {
+  const hit = cache.get(key);
+  if (hit) return hit;
+  const built = make();
+  cache.set(key, built);
+  return built;
+}
+export function clearIsoListCache() {
+  cache.clear();
+}
+export function countryOptions(locale = DEFAULT_ISO_LOCALE) {
+  return cached(`region:${locale}`, () => build(COUNTRY_CODES, "region", locale));
+}
+export function currencyOptions(locale = DEFAULT_ISO_LOCALE) {
+  return cached(`currency:${locale}`, () => build(currencyCodes(), "currency", locale));
+}
+export function countryLabel(code, locale = DEFAULT_ISO_LOCALE) {
+  const key = typeof code === "string" ? code.trim().toUpperCase() : "";
+  if (!key) return "";
+  return displayNames("region", locale)?.of(key) || key;
+}
+export function currencyLabel(code, locale = DEFAULT_ISO_LOCALE) {
+  const key = typeof code === "string" ? code.trim().toUpperCase() : "";
+  if (!key) return "";
+  return displayNames("currency", locale)?.of(key) || key;
+}

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

@@ -0,0 +1,34 @@
+import type { SidebarNavItem } from '../types/nav.js';
+/**
+ * Pure helpers behind `SidebarNav` / `SidebarNavLink`. They live outside the
+ * SFCs so the active-route and link-target rules can be tested without
+ * mounting a component (and so both SFCs share exactly one implementation).
+ *
+ * **`children` means tabs, not sub-navigation.** An item with children is one
+ * sidebar row; its children are the tabs of the page that row opens. Nothing
+ * here expands, so there is no collapse state to keep — the row is a link like
+ * any other, it just knows about the routes its tabs carry. Anything that
+ * should stand on its own in the sidebar is declared as its own item.
+ */
+/** Stable identity for `v-for` keys — `to` is unique where it exists. */
+export declare function sidebarItemKey(item: SidebarNavItem): string;
+/** True when `path` is the item's own route, or sits below it. */
+export declare function sidebarItemIsActive(item: SidebarNavItem, path: string): boolean;
+/** True when the item, or any of its tabs, matches `path`. */
+export declare function sidebarItemHoldsActive(item: SidebarNavItem, path: string): boolean;
+/**
+ * Which row gets the highlight. The tabs of a group are not rows of their own,
+ * so the group stays lit for every one of them — an operator on *Carriers*
+ * still sees where they are, which is **Shipping**.
+ */
+export declare function sidebarItemIsCurrent(item: SidebarNavItem, path: string): boolean;
+/**
+ * Where the row links. A group with a route of its own opens that (it is the
+ * default tab); a pure container — a heading several apps contribute to, where
+ * no single app's view is the right landing page — opens its first tab.
+ *
+ * `undefined` means the row has nothing to open at all. `navCompose` prunes
+ * those before they reach a sidebar, but the guard keeps a hand-written
+ * section (Settings, Apps, …) from rendering a dead row.
+ */
+export declare function sidebarItemTarget(item: SidebarNavItem): string | undefined;

package/dist/runtime/lib/sidebarNav.js

@@ -0,0 +1,22 @@
+export function sidebarItemKey(item) {
+  return item.key ?? item.to ?? item.label;
+}
+export function sidebarItemIsActive(item, path) {
+  if (!item.to) return false;
+  if (item.exact) return path === item.to;
+  return path === item.to || path.startsWith(`${item.to}/`);
+}
+export function sidebarItemHoldsActive(item, path) {
+  return sidebarItemIsActive(item, path) || (item.children ?? []).some((child) => sidebarItemHoldsActive(child, path));
+}
+export function sidebarItemIsCurrent(item, path) {
+  return sidebarItemHoldsActive(item, path);
+}
+export function sidebarItemTarget(item) {
+  if (item.to) return item.to;
+  for (const child of item.children ?? []) {
+    const target = sidebarItemTarget(child);
+    if (target) return target;
+  }
+  return void 0;
+}

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

@@ -0,0 +1,59 @@
+import type { ShallowRef } from 'vue';
+import type { Talkback, TalkbackOptions } from '@revenexx/talkback-js';
+export interface PlatformTalkbackConfig {
+    /** Centrifugo's client transport, e.g. `https://talkback.revenexx.com`. */
+    host: string;
+    /**
+     * Where a connection token is minted. The facade's own `${host}/v1/tokens` by
+     * default — the browser's Zitadel token authorises it directly, so no BFF route
+     * stands in between.
+     */
+    tokenEndpoint: string;
+    /** Likewise, `${host}/v1/subscription-tokens`. */
+    subscriptionTokenEndpoint: string;
+    /**
+     * The active tenant slug. A GETTER, not a value: operator impersonation
+     * changes it at run time, and it is positionally first in every channel name.
+     */
+    tenant: () => string;
+    /**
+     * The caller's Zitadel access token, passed to the facade as the bearer.
+     *
+     * The facade admits it because an end user holds `user` or `admin` in the
+     * Zitadel USER project, and such a caller may mint only for itself: the request
+     * carries no `user_id` and the facade fills it from this token's own `sub`.
+     */
+    getToken: () => Promise<string | null>;
+    /**
+     * Replaces the Centrifuge client. Left unset outside tests — the fake in
+     * `@revenexx/talkback-js/testing` satisfies it.
+     */
+    client?: TalkbackOptions['client'];
+    debug?: boolean;
+}
+/**
+ * The `sub` claim of a JWT, or null when it isn't one.
+ *
+ * This is where the client's `userId` comes from, and the choice is
+ * load-bearing rather than convenient. The BFF derives the token's subject from
+ * the same claim of the same token, so client and server cannot disagree about
+ * the name of the `user:` channel — a mismatch would mint a grant for one name
+ * and subscribe to another, which fails as a silent 403 on a channel nobody
+ * publishes to. Deliberately NOT verified: nothing is authorised here, and the
+ * BFF verifies the signature before it grants anything.
+ *
+ * Mirrors the base64url handling in the cockpit's `useConsoleAuth`.
+ */
+export declare function decodeJwtSub(jwt: string | null | undefined): string | null;
+/**
+ * Builds the client for a host.
+ *
+ * `tenant` and `userId` are providers because talkback-js reads them on every
+ * channel build; passing values would pin the first tenant the page saw.
+ */
+export declare function createPlatformTalkback(config: PlatformTalkbackConfig): Promise<Talkback>;
+/** Registered once by the host's provider. Pass `null` to detach (tests). */
+export declare function setTalkback(tb: Talkback | null): void;
+export declare function getTalkback(): Talkback | null;
+/** The registry itself, for composables that must react to it appearing. */
+export declare function talkbackRef(): ShallowRef<Talkback | null>;

package/dist/runtime/lib/talkback.js

@@ -0,0 +1,49 @@
+import { shallowRef } from "vue";
+export function decodeJwtSub(jwt) {
+  if (!jwt) return null;
+  try {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) return null;
+    const p = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const b64 = p.padEnd(p.length + (4 - p.length % 4) % 4, "=");
+    const claims = JSON.parse(atob(b64));
+    return typeof claims.sub === "string" && claims.sub ? claims.sub : null;
+  } catch {
+    return null;
+  }
+}
+export async function createPlatformTalkback(config) {
+  const { createTalkback } = await import("@revenexx/talkback-js");
+  let userId = "";
+  const accessToken = async () => {
+    const token = await config.getToken();
+    if (token) {
+      userId = decodeJwtSub(token) ?? userId;
+    }
+    return token;
+  };
+  try {
+    userId = decodeJwtSub(await config.getToken()) ?? "";
+  } catch {
+  }
+  return createTalkback({
+    host: config.host,
+    tenant: () => config.tenant(),
+    userId: () => userId,
+    tokenEndpoint: config.tokenEndpoint,
+    subscriptionTokenEndpoint: config.subscriptionTokenEndpoint,
+    accessToken,
+    ...config.client ? { client: config.client } : {},
+    ...config.debug === void 0 ? {} : { debug: config.debug }
+  });
+}
+const current = shallowRef(null);
+export function setTalkback(tb) {
+  current.value = tb;
+}
+export function getTalkback() {
+  return current.value;
+}
+export function talkbackRef() {
+  return current;
+}

package/dist/runtime/types/nav.d.ts

@@ -7,13 +7,27 @@ import type { Component } from 'vue';
  */
 export type SidebarNavItem = {
     label: string;
-    to: string;
+    /**
+     * Target route. Omit it for a pure container — a heading several apps
+     * contribute pages to, where no single view is the right landing page. The
+     * row then links to the first of its `children` instead.
+     */
+    to?: string;
     icon?: Component;
     badge?: number | string | null;
     /** Dim + show a "soon" tag (not-yet-shipped surfaces). */
     preview?: boolean;
     /** Match the route exactly (for studio roots like `/settings`). */
     exact?: boolean;
+    /**
+     * The item's **tabs**, not sub-navigation. The sidebar shows one row; the
+     * page it opens shows these across the top, each addressed by its own route
+     * (see `studio-commerce/lib/navGroups.ts`). The row stays highlighted on all
+     * of them.
+     */
+    children?: SidebarNavItem[];
+    /** Stable `v-for` key. Defaults to `to ?? label`. */
+    key?: string;
 };
 export type SidebarNavSection = {
     key: string;