@noy-db/in-pinia 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/index.d.ts

@@ -1,8 +1,18 @@
 import * as pinia from 'pinia';
 import { StateTree, PiniaPlugin } from 'pinia';
 import { ShallowRef, Ref, ComputedRef } from 'vue';
-import { Query, Noydb, StandardSchemaV1, Vault, NoydbStore as NoydbStore$1, NoydbOptions, Role } from '@noy-db/hub';
+import { Query, Noydb, StandardSchemaV1, Vault, I18nTextDescriptor, DictKeyDescriptor, NoydbStore as NoydbStore$1, NoydbOptions, Role } from '@noy-db/hub';
 
+/**
+ * i18n resolution mode for a store's reads.
+ * - `'raw'` (default) — items keep `{ [locale]: string }` maps (today's behavior).
+ * - `'follow'` — resolve to the global `useNoydbI18n` locale; re-read on flip.
+ * - `{ locale, fallback? }` — pin to a fixed locale or own ref.
+ */
+type NoydbStoreI18nMode = 'raw' | 'follow' | {
+    locale: string | Ref<string>;
+    fallback?: string | readonly string[];
+};
 /**
  * Reactive handle returned by `store.liveQuery(fn)`. Mirrors a hub
  * `LiveQuery<R>` into Vue refs; `items` updates on every left- or
@@ -24,8 +34,22 @@ interface NoydbLiveQuery<R> {
  * for full type safety.
  */
 interface NoydbStoreOptions<T> {
-    /** Vault (tenant) name. */
-    vault: string;
+    /**
+     * Vault (tenant) name, or a **resolver** evaluated at access time for
+     * federation routing (#383). A plain `string` binds the store to one
+     * vault for its lifetime (unchanged behavior). A `() => string` resolver
+     * is re-evaluated on every read/write and whenever its reactive
+     * dependencies change — so a store can follow the app's active scope into
+     * a per-client shard vault (e.g. `() => firm.shardVaultId(clientCode.value)`).
+     *
+     * When the resolved name changes, the store re-opens the new vault and
+     * re-hydrates `items` (mirrors the `i18n: 'follow'` re-read). If the
+     * resolver reads Vue reactive state, the re-hydrate is automatic; if it
+     * reads non-reactive state, the next `refresh()`/`add()`/`remove()`
+     * re-binds. Note: an in-flight `liveQuery()` handle stays bound to the
+     * vault it was created against — recreate it after a vault change.
+     */
+    vault: string | (() => string);
     /** Collection name within the vault. Defaults to the store id. */
     collection?: string;
     /**
@@ -60,6 +84,42 @@ interface NoydbStoreOptions<T> {
      * `@noy-db/attestation` `AttestationFieldSchema`. Stores without it behave as before.
      */
     attestation?: NonNullable<Parameters<Vault['collection']>[1]>['attestation'];
+    /**
+     * If true, the collection persists a JSON Schema baseline of `schema` so the
+     * schema-update protocol can detect drift on later opens. Forwarded as-is to
+     * the underlying `Collection`. Required for `schemaUpdate` to take effect.
+     */
+    persistJsonSchema?: NonNullable<Parameters<Vault['collection']>[1]>['persistJsonSchema'];
+    /**
+     * Ordered schema-update strategies (e.g. `coordinatedCutover`, `additiveOnly`,
+     * `lockSchema`) applied when a stored baseline differs from the current
+     * `schema`. Forwarded as-is to the underlying `Collection`. Requires
+     * `persistJsonSchema: true` (drift detection needs the persisted baseline).
+     * Lets a `defineNoydbStore`-defined collection opt into migration tracking
+     * declaratively, without a pre-registration `vault.collection(...)` call.
+     */
+    schemaUpdate?: NonNullable<Parameters<Vault['collection']>[1]>['schemaUpdate'];
+    /**
+     * Per-field `i18nText()` descriptors. Forwarded to the underlying
+     * `Collection` so locale resolution and required-translation validation
+     * run declaratively without a separate `vault.collection(name, { i18nFields })`
+     * pre-registration call.
+     */
+    i18nFields?: Record<string, I18nTextDescriptor>;
+    /**
+     * Per-field `dictKey()` descriptors. Forwarded to the underlying
+     * `Collection` so dictionary label resolution runs declaratively.
+     */
+    dictKeyFields?: Record<string, DictKeyDescriptor>;
+    /**
+     * How the store resolves i18nText/dictKey fields on read.
+     * Default `'raw'` — items keep `{ [locale]: string }` maps (today's
+     * behavior; zero breaking change). `'follow'` resolves to the global
+     * `useNoydbI18n` locale and re-reads when it changes. `{ locale }`
+     * pins to a fixed locale or own ref. Set `'raw'` for stores whose maps
+     * feed identity/export reads or a per-cell bilingual toggle.
+     */
+    i18n?: NoydbStoreI18nMode;
 }
 /**
  * The runtime shape of the store returned by `defineNoydbStore`.
@@ -153,6 +213,150 @@ declare function getActiveNoydb(): Noydb | null;
  */
 declare function resolveNoydb(explicit?: Noydb | null): Noydb;
 
+/** Minimal vault shape needed to sync an ambient locale. */
+interface LocaleSyncable {
+    setLocale(locale: string | undefined): void;
+}
+interface SetLocaleOptions {
+    /**
+     * Vault(s) to ALSO update via `vault.setLocale` (opt-in). Omit to keep
+     * the operation state-only — the safe default for locale-less vaults.
+     */
+    readonly syncVault?: LocaleSyncable | readonly LocaleSyncable[];
+}
+declare const useNoydbI18n: pinia.StoreDefinition<"noydb-i18n", Pick<{
+    locale: Ref<string, string>;
+    fallback: Ref<string[], string[]>;
+    setLocale: (l: string, opts?: SetLocaleOptions) => void;
+    setFallback: (chain: string[]) => void;
+    bindTo: (source: Ref<string>, opts?: {
+        immediate?: boolean;
+    }) => () => void;
+}, "locale" | "fallback">, Pick<{
+    locale: Ref<string, string>;
+    fallback: Ref<string[], string[]>;
+    setLocale: (l: string, opts?: SetLocaleOptions) => void;
+    setFallback: (chain: string[]) => void;
+    bindTo: (source: Ref<string>, opts?: {
+        immediate?: boolean;
+    }) => () => void;
+}, never>, Pick<{
+    locale: Ref<string, string>;
+    fallback: Ref<string[], string[]>;
+    setLocale: (l: string, opts?: SetLocaleOptions) => void;
+    setFallback: (chain: string[]) => void;
+    bindTo: (source: Ref<string>, opts?: {
+        immediate?: boolean;
+    }) => () => void;
+}, "setLocale" | "setFallback" | "bindTo">>;
+
+/**
+ * `useI18nField` — a reactive `pickLang` for a single i18nText map.
+ *
+ * Resolves a `{ [locale]: string }` map to the active locale, recomputing
+ * when the locale (or a reactive source) changes. Uses hub's
+ * `resolveI18nText` with `policy: 'null'`, so it never throws and never
+ * yields `undefined` — `null` when no locale (and no fallback) resolves.
+ *
+ * Follows the global `useNoydbI18n` locale/fallback unless overridden.
+ * Ideal for resolving one field at the edge while siblings stay raw
+ * (e.g. a bilingual section reading raw maps).
+ *
+ * @public
+ */
+
+type MapSource = Record<string, string> | (() => Record<string, string> | undefined | null);
+interface UseI18nFieldOptions {
+    /** Override the active locale (string or ref). Defaults to the global. */
+    readonly locale?: string | Ref<string>;
+    /** Override the fallback chain. Defaults to the global. */
+    readonly fallback?: string | readonly string[];
+}
+declare function useI18nField(source: MapSource, opts?: UseI18nFieldOptions): Ref<string | null>;
+
+/**
+ * `useDictLabel(name, options)` — Vue composable for rendering
+ * `dictKey` fields at template time.
+ *
+ * The i18n boundary pattern has records store a **stable key**; the
+ * label lives in a reserved `_dict_<name>` collection and is resolved
+ * at render time. Every Vue / Nuxt consumer ends up writing the same
+ * wrapper — this composable replaces that boilerplate.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ *   import { useDictLabel } from '@noy-db/in-pinia'
+ *   const label = useDictLabel('invoiceStatus')
+ * </script>
+ *
+ * <template>
+ *   <td v-for="inv in invoices" :key="inv.id">
+ *     {{ label(inv.status).value }}
+ *   </td>
+ * </template>
+ * ```
+ *
+ * ## Reactivity
+ *
+ * `label(key)` returns a `Ref<string>` that updates when the locale
+ * changes (via the passed-in `locale` ref).
+ *
+ * **Known limitation:** mutations via `vault.dictionary(name).put()`
+ * bypass the Collection emitter — the hub's `DictionaryHandle` writes
+ * through the adapter directly, so labels cached by this composable
+ * won't refresh for those writes until either (a) the locale changes
+ * or (b) the caller re-creates the composable. Tracked as a
+ * hub follow-up (route dict writes through the Collection emitter).
+ *
+ * The underlying fetch is async, so a newly-constructed label starts
+ * at its "missing" sentinel (the key itself by default) and updates
+ * to the resolved string within one tick.
+ *
+ * @module
+ */
+
+interface UseDictLabelOptions {
+    /**
+     * Explicit vault. Either a `Vault` instance or its name. When a
+     * name is provided the composable calls `db.vault(name)` — which
+     * requires the vault to already be open via
+     * `await db.openVault(name)` elsewhere.
+     *
+     * When omitted, uses the currently-active vault on the global
+     * Noydb instance set via `setActiveNoydb()`. If no vault is open
+     * and none is provided, setup throws.
+     */
+    readonly vault?: Vault | string;
+    /**
+     * Active locale. Pass a `Ref<string>` for live reactivity
+     * (e.g. `useI18n().locale` from vue-i18n, or `useLocale()` from a
+     * Nuxt module). A bare string is wrapped in a static ref.
+     * Defaults to `'en'`.
+     */
+    readonly locale?: Ref<string> | string;
+    /**
+     * Fallback locale chain — evaluated in order when the primary
+     * locale has no translation. Use `'any'` as the final entry to
+     * accept any available locale. Defaults to `['en', 'any']`.
+     */
+    readonly fallback?: string | readonly string[];
+    /**
+     * What to render when the key is absent from the dictionary.
+     *
+     *   - `'key'` (default) — return the key itself. Matches the hub's
+     *     stable-key invariant and surfaces typos during development.
+     *   - `'empty'` — return `''`. Best for cells where a missing
+     *     value should render blank.
+     *   - `'placeholder'` — return `⟨missing:{key}⟩` for visible
+     *     audit during QA.
+     */
+    readonly onMissing?: 'key' | 'empty' | 'placeholder';
+}
+/**
+ * Build a reactive label lookup. Returns a factory `(key) => Ref<string>`.
+ */
+declare function useDictLabel(dictionaryName: string, options?: UseDictLabelOptions): (key: string) => Ref<string>;
+
 /**
  * `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.
  *
@@ -415,4 +619,4 @@ interface UseCapabilityGrantReturn {
  */
 declare function useCapabilityGrant(capability: string, options: UseCapabilityGrantOptions): UseCapabilityGrantReturn;
 
-export { CAPABILITY_REQUESTS_COLLECTION, type CapabilityGrantRecord, type CapabilityGrantState, type NoydbLiveQuery, type NoydbPiniaPluginOptions, type NoydbStore, type NoydbStoreOptions, type StoreNoydbOptions, type UseCapabilityGrantOptions, type UseCapabilityGrantReturn, createNoydbPiniaPlugin, defineNoydbStore, getActiveNoydb, resolveNoydb, setActiveNoydb, useCapabilityGrant };
+export { CAPABILITY_REQUESTS_COLLECTION, type CapabilityGrantRecord, type CapabilityGrantState, type LocaleSyncable, type NoydbLiveQuery, type NoydbPiniaPluginOptions, type NoydbStore, type NoydbStoreOptions, type SetLocaleOptions, type StoreNoydbOptions, type UseCapabilityGrantOptions, type UseCapabilityGrantReturn, type UseDictLabelOptions, type UseI18nFieldOptions, createNoydbPiniaPlugin, defineNoydbStore, getActiveNoydb, resolveNoydb, setActiveNoydb, useCapabilityGrant, useDictLabel, useI18nField, useNoydbI18n };

package/dist/index.js

@@ -1,11 +1,13 @@
 // src/defineNoydbStore.ts
-import { defineStore } from "pinia";
+import { defineStore as defineStore2 } from "pinia";
 import {
   computed,
   getCurrentScope,
   onScopeDispose,
-  ref,
-  shallowRef
+  isRef,
+  ref as ref2,
+  shallowRef,
+  watch as watch2
 } from "vue";
 
 // src/context.ts
@@ -24,28 +26,80 @@ function resolveNoydb(explicit) {
   );
 }
 
+// src/useNoydbI18n.ts
+import { defineStore } from "pinia";
+import { ref, watch } from "vue";
+var useNoydbI18n = defineStore("noydb-i18n", () => {
+  const locale = ref("en");
+  const fallback = ref(["en", "any"]);
+  function setLocale(l, opts) {
+    locale.value = l;
+    const sync = opts?.syncVault;
+    if (sync) {
+      const vaults = Array.isArray(sync) ? sync : [sync];
+      for (const v of vaults) v.setLocale(l);
+    }
+  }
+  function setFallback(chain) {
+    fallback.value = chain;
+  }
+  function bindTo(source, opts) {
+    return watch(
+      source,
+      (v) => {
+        locale.value = v;
+      },
+      // sync flush so the mirror propagates immediately (no tick lag) —
+      // a locale change should be observable synchronously by dependents.
+      { immediate: opts?.immediate ?? true, flush: "sync" }
+    );
+  }
+  return { locale, fallback, setLocale, setFallback, bindTo };
+});
+
 // src/defineNoydbStore.ts
 function defineNoydbStore(id, options) {
   const collectionName = options.collection ?? id;
   const prefetch = options.prefetch ?? true;
-  return defineStore(id, () => {
+  return defineStore2(id, () => {
     const items = shallowRef([]);
     const count = computed(() => items.value.length);
+    const i18nMode = options.i18n ?? "raw";
+    const i18nStore = i18nMode === "follow" ? useNoydbI18n() : null;
+    function localeOpts() {
+      if (i18nMode === "raw") return { locale: "raw" };
+      if (i18nMode === "follow") {
+        return { locale: i18nStore.locale, fallback: i18nStore.fallback };
+      }
+      const l = i18nMode.locale;
+      return {
+        locale: typeof l === "string" ? l : l.value,
+        ...i18nMode.fallback !== void 0 ? { fallback: i18nMode.fallback } : {}
+      };
+    }
+    const resolveVaultName = () => typeof options.vault === "function" ? options.vault() : options.vault;
     let cachedCompartment = null;
     let cachedCollection = null;
+    let boundVaultName = null;
     async function getCollection() {
-      if (cachedCollection) return cachedCollection;
+      const vaultName = resolveVaultName();
+      if (cachedCollection && boundVaultName === vaultName) return cachedCollection;
       const noydb = resolveNoydb(options.noydb ?? null);
-      cachedCompartment = await noydb.openVault(options.vault);
+      cachedCompartment = await noydb.openVault(vaultName);
       const collOpts = {};
       if (options.schema !== void 0) collOpts.schema = options.schema;
       if (options.attestation !== void 0) collOpts.attestation = options.attestation;
+      if (options.persistJsonSchema !== void 0) collOpts.persistJsonSchema = options.persistJsonSchema;
+      if (options.schemaUpdate !== void 0) collOpts.schemaUpdate = options.schemaUpdate;
+      if (options.i18nFields !== void 0) collOpts.i18nFields = options.i18nFields;
+      if (options.dictKeyFields !== void 0) collOpts.dictKeyFields = options.dictKeyFields;
       cachedCollection = cachedCompartment.collection(collectionName, collOpts);
+      boundVaultName = vaultName;
       return cachedCollection;
     }
     async function refresh() {
       const c = await getCollection();
-      const list = await c.list();
+      const list = await c.list(localeOpts());
       items.value = list;
     }
     function byId(id2) {
@@ -57,7 +111,7 @@ function defineNoydbStore(id, options) {
     async function add(id2, record) {
       const c = await getCollection();
       await c.put(id2, record);
-      items.value = await c.list();
+      items.value = await c.list(localeOpts());
     }
     async function update(id2, record) {
       await add(id2, record);
@@ -65,7 +119,7 @@ function defineNoydbStore(id, options) {
     async function remove(id2) {
       const c = await getCollection();
       await c.delete(id2);
-      items.value = await c.list();
+      items.value = await c.list(localeOpts());
     }
     function query() {
       if (!cachedCollection) {
@@ -84,7 +138,7 @@ function defineNoydbStore(id, options) {
       const built = build(cachedCollection.query());
       const live = built.live();
       const items2 = shallowRef(live.value);
-      const error = ref(live.error);
+      const error = ref2(live.error);
       const unsubscribe = live.subscribe(() => {
         items2.value = live.value;
         error.value = live.error;
@@ -100,6 +154,23 @@ function defineNoydbStore(id, options) {
       return { items: items2, error, stop };
     }
     const $ready = prefetch ? refresh() : Promise.resolve();
+    if (i18nMode === "follow") {
+      watch2(
+        () => [i18nStore.locale, i18nStore.fallback],
+        () => {
+          void refresh();
+        }
+      );
+    } else if (typeof i18nMode === "object" && isRef(i18nMode.locale)) {
+      watch2(i18nMode.locale, () => {
+        void refresh();
+      });
+    }
+    if (typeof options.vault === "function") {
+      watch2(resolveVaultName, (next, prev) => {
+        if (next !== prev) void refresh();
+      });
+    }
     return {
       items,
       count,
@@ -115,6 +186,102 @@ function defineNoydbStore(id, options) {
   });
 }
 
+// src/useI18nField.ts
+import { computed as computed2, unref } from "vue";
+import { resolveI18nText } from "@noy-db/hub/i18n";
+function useI18nField(source, opts = {}) {
+  const i18n = useNoydbI18n();
+  return computed2(() => {
+    const map = typeof source === "function" ? source() : source;
+    if (!map || typeof map !== "object") return null;
+    const locale = opts.locale !== void 0 ? unref(opts.locale) : i18n.locale;
+    const fallback = opts.fallback ?? i18n.fallback;
+    const out = resolveI18nText(
+      map,
+      locale,
+      fallback,
+      void 0,
+      { policy: "null" }
+    );
+    return typeof out === "string" ? out : null;
+  });
+}
+
+// src/useDictLabel.ts
+import { ref as ref3, shallowRef as shallowRef2, toRef, watch as watch3 } from "vue";
+function useDictLabel(dictionaryName, options = {}) {
+  const vault = resolveVault(options.vault);
+  const handle = vault.dictionary(dictionaryName);
+  let storeLocale = null;
+  let storeFallback = null;
+  if (options.locale === void 0 || options.fallback === void 0) {
+    try {
+      const i18n = useNoydbI18n();
+      storeLocale = toRef(i18n, "locale");
+      storeFallback = i18n.fallback;
+    } catch {
+    }
+  }
+  const localeRef = options.locale !== void 0 ? normaliseLocale(options.locale) : storeLocale ?? ref3("en");
+  const fallback = options.fallback ?? storeFallback ?? ["en", "any"];
+  const onMissingMode = options.onMissing ?? "key";
+  const missing = (key) => onMissingMode === "empty" ? "" : onMissingMode === "placeholder" ? `\u27E8missing:${key}\u27E9` : key;
+  const cache = /* @__PURE__ */ new Map();
+  const db = resolveNoydb();
+  const dictCollection = `_dict_${dictionaryName}`;
+  const onChange = (event) => {
+    if (event.collection !== dictCollection) return;
+    for (const [key, r] of cache) {
+      void refresh(key, r);
+    }
+  };
+  db.on("change", onChange);
+  watch3(localeRef, () => {
+    for (const [key, r] of cache) {
+      void refresh(key, r);
+    }
+  });
+  async function refresh(key, r) {
+    try {
+      const resolved = await handle.resolveLabel(
+        key,
+        localeRef.value,
+        fallback
+      );
+      r.value = resolved ?? missing(key);
+    } catch {
+      r.value = missing(key);
+    }
+  }
+  return (key) => {
+    let r = cache.get(key);
+    if (r) return r;
+    r = shallowRef2(missing(key));
+    cache.set(key, r);
+    void refresh(key, r);
+    return r;
+  };
+}
+function resolveVault(source) {
+  const db = resolveNoydb();
+  if (source && typeof source !== "string") return source;
+  if (typeof source === "string") {
+    return db.vault(source);
+  }
+  const anyDb = db;
+  if (anyDb.vaultCache && anyDb.vaultCache.size > 0) {
+    return [...anyDb.vaultCache.values()][0];
+  }
+  throw new Error(
+    '[@noy-db/in-pinia] useDictLabel: no open vault. Pass `{ vault: "name" }` or `await db.openVault(name)` first.'
+  );
+}
+function normaliseLocale(locale) {
+  if (locale === void 0) return ref3("en");
+  if (typeof locale === "string") return ref3(locale);
+  return locale;
+}
+
 // src/plugin.ts
 import { createNoydb } from "@noy-db/hub";
 var STATE_DOC_ID = "__state__";
@@ -209,24 +376,24 @@ function pickKeys(state, persist) {
 
 // src/useCapabilityGrant.ts
 import {
-  computed as computed2,
+  computed as computed3,
   getCurrentScope as getCurrentScope2,
   onScopeDispose as onScopeDispose2,
-  ref as ref2,
-  shallowRef as shallowRef2,
-  watch
+  ref as ref4,
+  shallowRef as shallowRef3,
+  watch as watch4
 } from "vue";
 var CAPABILITY_REQUESTS_COLLECTION = "_capability_requests";
 function useCapabilityGrant(capability, options) {
-  const state = ref2("idle");
-  const error = ref2(null);
-  const recordRef = shallowRef2(null);
+  const state = ref4("idle");
+  const error = ref4(null);
+  const recordRef = shallowRef3(null);
   const inBrowser = typeof window !== "undefined";
   let expiryTimer = null;
   let unsubscribeChangeStream = null;
   let resolvedVault = null;
   let stopped = false;
-  async function resolveVault() {
+  async function resolveVault2() {
     if (resolvedVault) return resolvedVault;
     if (typeof options.vault === "string") {
       const noydb = resolveNoydb(null);
@@ -273,21 +440,21 @@ function useCapabilityGrant(capability, options) {
     state.value = "idle";
     recordRef.value = null;
   }
-  const now = ref2(Date.now());
+  const now = ref4(Date.now());
   const tickTimer = inBrowser ? setInterval(() => {
     now.value = Date.now();
   }, 1e3) : null;
-  const timeRemaining = computed2(() => {
+  const timeRemaining = computed3(() => {
     if (state.value !== "granted" || !recordRef.value?.expiresAt) return 0;
     void now.value;
     const ms = new Date(recordRef.value.expiresAt).getTime() - Date.now();
     return ms > 0 ? ms : 0;
   });
-  watch(
+  watch4(
     () => recordRef.value?.id,
     async (id) => {
       if (!inBrowser || !id || unsubscribeChangeStream) return;
-      const vault = await resolveVault();
+      const vault = await resolveVault2();
       const coll = vault.collection(
         CAPABILITY_REQUESTS_COLLECTION
       );
@@ -319,7 +486,7 @@ function useCapabilityGrant(capability, options) {
     error.value = null;
     if (!inBrowser) return;
     try {
-      const vault = await resolveVault();
+      const vault = await resolveVault2();
       const coll = vault.collection(
         CAPABILITY_REQUESTS_COLLECTION
       );
@@ -352,7 +519,7 @@ function useCapabilityGrant(capability, options) {
     }
     error.value = null;
     try {
-      const vault = await resolveVault();
+      const vault = await resolveVault2();
       if (vault.role !== options.approver && vault.role !== "owner") {
         throw new Error(
           `useCapabilityGrant: caller role "${vault.role}" cannot approve a "${options.approver}"-tier grant`
@@ -388,7 +555,7 @@ function useCapabilityGrant(capability, options) {
     error.value = null;
     try {
       clearExpiryTimer();
-      const vault = await resolveVault();
+      const vault = await resolveVault2();
       const released = { ...record, status: "released" };
       const coll = vault.collection(
         CAPABILITY_REQUESTS_COLLECTION
@@ -419,6 +586,9 @@ export {
   getActiveNoydb,
   resolveNoydb,
   setActiveNoydb,
-  useCapabilityGrant
+  useCapabilityGrant,
+  useDictLabel,
+  useI18nField,
+  useNoydbI18n
 };
 //# sourceMappingURL=index.js.map