@noy-db/in-pinia 0.2.0-pre.2 → 0.2.0-pre.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +201 -29
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +215 -4
- package/dist/index.d.ts +215 -4
- package/dist/index.js +197 -26
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
1
|
import * as pinia from 'pinia';
|
|
2
2
|
import { StateTree, PiniaPlugin } from 'pinia';
|
|
3
3
|
import { ShallowRef, Ref, ComputedRef } from 'vue';
|
|
4
|
-
import { Query, Noydb, StandardSchemaV1, NoydbStore as NoydbStore$1, NoydbOptions, Role
|
|
4
|
+
import { Query, Noydb, StandardSchemaV1, Vault, I18nTextDescriptor, DictKeyDescriptor, NoydbStore as NoydbStore$1, NoydbOptions, Role } from '@noy-db/hub';
|
|
5
5
|
|
|
6
|
+
/**
|
|
7
|
+
* i18n resolution mode for a store's reads.
|
|
8
|
+
* - `'raw'` (default) — items keep `{ [locale]: string }` maps (today's behavior).
|
|
9
|
+
* - `'follow'` — resolve to the global `useNoydbI18n` locale; re-read on flip.
|
|
10
|
+
* - `{ locale, fallback? }` — pin to a fixed locale or own ref.
|
|
11
|
+
*/
|
|
12
|
+
type NoydbStoreI18nMode = 'raw' | 'follow' | {
|
|
13
|
+
locale: string | Ref<string>;
|
|
14
|
+
fallback?: string | readonly string[];
|
|
15
|
+
};
|
|
6
16
|
/**
|
|
7
17
|
* Reactive handle returned by `store.liveQuery(fn)`. Mirrors a hub
|
|
8
18
|
* `LiveQuery<R>` into Vue refs; `items` updates on every left- or
|
|
@@ -24,8 +34,22 @@ interface NoydbLiveQuery<R> {
|
|
|
24
34
|
* for full type safety.
|
|
25
35
|
*/
|
|
26
36
|
interface NoydbStoreOptions<T> {
|
|
27
|
-
/**
|
|
28
|
-
|
|
37
|
+
/**
|
|
38
|
+
* Vault (tenant) name, or a **resolver** evaluated at access time for
|
|
39
|
+
* federation routing (#383). A plain `string` binds the store to one
|
|
40
|
+
* vault for its lifetime (unchanged behavior). A `() => string` resolver
|
|
41
|
+
* is re-evaluated on every read/write and whenever its reactive
|
|
42
|
+
* dependencies change — so a store can follow the app's active scope into
|
|
43
|
+
* a per-client shard vault (e.g. `() => firm.shardVaultId(clientCode.value)`).
|
|
44
|
+
*
|
|
45
|
+
* When the resolved name changes, the store re-opens the new vault and
|
|
46
|
+
* re-hydrates `items` (mirrors the `i18n: 'follow'` re-read). If the
|
|
47
|
+
* resolver reads Vue reactive state, the re-hydrate is automatic; if it
|
|
48
|
+
* reads non-reactive state, the next `refresh()`/`add()`/`remove()`
|
|
49
|
+
* re-binds. Note: an in-flight `liveQuery()` handle stays bound to the
|
|
50
|
+
* vault it was created against — recreate it after a vault change.
|
|
51
|
+
*/
|
|
52
|
+
vault: string | (() => string);
|
|
29
53
|
/** Collection name within the vault. Defaults to the store id. */
|
|
30
54
|
collection?: string;
|
|
31
55
|
/**
|
|
@@ -53,6 +77,49 @@ interface NoydbStoreOptions<T> {
|
|
|
53
77
|
* perf cost, backwards compatible with usage).
|
|
54
78
|
*/
|
|
55
79
|
schema?: StandardSchemaV1<unknown, T>;
|
|
80
|
+
/**
|
|
81
|
+
* Optional per-field attestation schema. When set, it's installed on the
|
|
82
|
+
* underlying `Collection` (alongside `schema`) so `vault.issueAttestation(name, id)`
|
|
83
|
+
* can commit the declared fields against the firm's signing key — see
|
|
84
|
+
* `@noy-db/attestation` `AttestationFieldSchema`. Stores without it behave as before.
|
|
85
|
+
*/
|
|
86
|
+
attestation?: NonNullable<Parameters<Vault['collection']>[1]>['attestation'];
|
|
87
|
+
/**
|
|
88
|
+
* If true, the collection persists a JSON Schema baseline of `schema` so the
|
|
89
|
+
* schema-update protocol can detect drift on later opens. Forwarded as-is to
|
|
90
|
+
* the underlying `Collection`. Required for `schemaUpdate` to take effect.
|
|
91
|
+
*/
|
|
92
|
+
persistJsonSchema?: NonNullable<Parameters<Vault['collection']>[1]>['persistJsonSchema'];
|
|
93
|
+
/**
|
|
94
|
+
* Ordered schema-update strategies (e.g. `coordinatedCutover`, `additiveOnly`,
|
|
95
|
+
* `lockSchema`) applied when a stored baseline differs from the current
|
|
96
|
+
* `schema`. Forwarded as-is to the underlying `Collection`. Requires
|
|
97
|
+
* `persistJsonSchema: true` (drift detection needs the persisted baseline).
|
|
98
|
+
* Lets a `defineNoydbStore`-defined collection opt into migration tracking
|
|
99
|
+
* declaratively, without a pre-registration `vault.collection(...)` call.
|
|
100
|
+
*/
|
|
101
|
+
schemaUpdate?: NonNullable<Parameters<Vault['collection']>[1]>['schemaUpdate'];
|
|
102
|
+
/**
|
|
103
|
+
* Per-field `i18nText()` descriptors. Forwarded to the underlying
|
|
104
|
+
* `Collection` so locale resolution and required-translation validation
|
|
105
|
+
* run declaratively without a separate `vault.collection(name, { i18nFields })`
|
|
106
|
+
* pre-registration call.
|
|
107
|
+
*/
|
|
108
|
+
i18nFields?: Record<string, I18nTextDescriptor>;
|
|
109
|
+
/**
|
|
110
|
+
* Per-field `dictKey()` descriptors. Forwarded to the underlying
|
|
111
|
+
* `Collection` so dictionary label resolution runs declaratively.
|
|
112
|
+
*/
|
|
113
|
+
dictKeyFields?: Record<string, DictKeyDescriptor>;
|
|
114
|
+
/**
|
|
115
|
+
* How the store resolves i18nText/dictKey fields on read.
|
|
116
|
+
* Default `'raw'` — items keep `{ [locale]: string }` maps (today's
|
|
117
|
+
* behavior; zero breaking change). `'follow'` resolves to the global
|
|
118
|
+
* `useNoydbI18n` locale and re-reads when it changes. `{ locale }`
|
|
119
|
+
* pins to a fixed locale or own ref. Set `'raw'` for stores whose maps
|
|
120
|
+
* feed identity/export reads or a per-cell bilingual toggle.
|
|
121
|
+
*/
|
|
122
|
+
i18n?: NoydbStoreI18nMode;
|
|
56
123
|
}
|
|
57
124
|
/**
|
|
58
125
|
* The runtime shape of the store returned by `defineNoydbStore`.
|
|
@@ -146,6 +213,150 @@ declare function getActiveNoydb(): Noydb | null;
|
|
|
146
213
|
*/
|
|
147
214
|
declare function resolveNoydb(explicit?: Noydb | null): Noydb;
|
|
148
215
|
|
|
216
|
+
/** Minimal vault shape needed to sync an ambient locale. */
|
|
217
|
+
interface LocaleSyncable {
|
|
218
|
+
setLocale(locale: string | undefined): void;
|
|
219
|
+
}
|
|
220
|
+
interface SetLocaleOptions {
|
|
221
|
+
/**
|
|
222
|
+
* Vault(s) to ALSO update via `vault.setLocale` (opt-in). Omit to keep
|
|
223
|
+
* the operation state-only — the safe default for locale-less vaults.
|
|
224
|
+
*/
|
|
225
|
+
readonly syncVault?: LocaleSyncable | readonly LocaleSyncable[];
|
|
226
|
+
}
|
|
227
|
+
declare const useNoydbI18n: pinia.StoreDefinition<"noydb-i18n", Pick<{
|
|
228
|
+
locale: Ref<string, string>;
|
|
229
|
+
fallback: Ref<string[], string[]>;
|
|
230
|
+
setLocale: (l: string, opts?: SetLocaleOptions) => void;
|
|
231
|
+
setFallback: (chain: string[]) => void;
|
|
232
|
+
bindTo: (source: Ref<string>, opts?: {
|
|
233
|
+
immediate?: boolean;
|
|
234
|
+
}) => () => void;
|
|
235
|
+
}, "locale" | "fallback">, Pick<{
|
|
236
|
+
locale: Ref<string, string>;
|
|
237
|
+
fallback: Ref<string[], string[]>;
|
|
238
|
+
setLocale: (l: string, opts?: SetLocaleOptions) => void;
|
|
239
|
+
setFallback: (chain: string[]) => void;
|
|
240
|
+
bindTo: (source: Ref<string>, opts?: {
|
|
241
|
+
immediate?: boolean;
|
|
242
|
+
}) => () => void;
|
|
243
|
+
}, never>, Pick<{
|
|
244
|
+
locale: Ref<string, string>;
|
|
245
|
+
fallback: Ref<string[], string[]>;
|
|
246
|
+
setLocale: (l: string, opts?: SetLocaleOptions) => void;
|
|
247
|
+
setFallback: (chain: string[]) => void;
|
|
248
|
+
bindTo: (source: Ref<string>, opts?: {
|
|
249
|
+
immediate?: boolean;
|
|
250
|
+
}) => () => void;
|
|
251
|
+
}, "setLocale" | "setFallback" | "bindTo">>;
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* `useI18nField` — a reactive `pickLang` for a single i18nText map.
|
|
255
|
+
*
|
|
256
|
+
* Resolves a `{ [locale]: string }` map to the active locale, recomputing
|
|
257
|
+
* when the locale (or a reactive source) changes. Uses hub's
|
|
258
|
+
* `resolveI18nText` with `policy: 'null'`, so it never throws and never
|
|
259
|
+
* yields `undefined` — `null` when no locale (and no fallback) resolves.
|
|
260
|
+
*
|
|
261
|
+
* Follows the global `useNoydbI18n` locale/fallback unless overridden.
|
|
262
|
+
* Ideal for resolving one field at the edge while siblings stay raw
|
|
263
|
+
* (e.g. a bilingual section reading raw maps).
|
|
264
|
+
*
|
|
265
|
+
* @public
|
|
266
|
+
*/
|
|
267
|
+
|
|
268
|
+
type MapSource = Record<string, string> | (() => Record<string, string> | undefined | null);
|
|
269
|
+
interface UseI18nFieldOptions {
|
|
270
|
+
/** Override the active locale (string or ref). Defaults to the global. */
|
|
271
|
+
readonly locale?: string | Ref<string>;
|
|
272
|
+
/** Override the fallback chain. Defaults to the global. */
|
|
273
|
+
readonly fallback?: string | readonly string[];
|
|
274
|
+
}
|
|
275
|
+
declare function useI18nField(source: MapSource, opts?: UseI18nFieldOptions): Ref<string | null>;
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* `useDictLabel(name, options)` — Vue composable for rendering
|
|
279
|
+
* `dictKey` fields at template time.
|
|
280
|
+
*
|
|
281
|
+
* The i18n boundary pattern has records store a **stable key**; the
|
|
282
|
+
* label lives in a reserved `_dict_<name>` collection and is resolved
|
|
283
|
+
* at render time. Every Vue / Nuxt consumer ends up writing the same
|
|
284
|
+
* wrapper — this composable replaces that boilerplate.
|
|
285
|
+
*
|
|
286
|
+
* ```vue
|
|
287
|
+
* <script setup lang="ts">
|
|
288
|
+
* import { useDictLabel } from '@noy-db/in-pinia'
|
|
289
|
+
* const label = useDictLabel('invoiceStatus')
|
|
290
|
+
* </script>
|
|
291
|
+
*
|
|
292
|
+
* <template>
|
|
293
|
+
* <td v-for="inv in invoices" :key="inv.id">
|
|
294
|
+
* {{ label(inv.status).value }}
|
|
295
|
+
* </td>
|
|
296
|
+
* </template>
|
|
297
|
+
* ```
|
|
298
|
+
*
|
|
299
|
+
* ## Reactivity
|
|
300
|
+
*
|
|
301
|
+
* `label(key)` returns a `Ref<string>` that updates when the locale
|
|
302
|
+
* changes (via the passed-in `locale` ref).
|
|
303
|
+
*
|
|
304
|
+
* **Known limitation:** mutations via `vault.dictionary(name).put()`
|
|
305
|
+
* bypass the Collection emitter — the hub's `DictionaryHandle` writes
|
|
306
|
+
* through the adapter directly, so labels cached by this composable
|
|
307
|
+
* won't refresh for those writes until either (a) the locale changes
|
|
308
|
+
* or (b) the caller re-creates the composable. Tracked as a
|
|
309
|
+
* hub follow-up (route dict writes through the Collection emitter).
|
|
310
|
+
*
|
|
311
|
+
* The underlying fetch is async, so a newly-constructed label starts
|
|
312
|
+
* at its "missing" sentinel (the key itself by default) and updates
|
|
313
|
+
* to the resolved string within one tick.
|
|
314
|
+
*
|
|
315
|
+
* @module
|
|
316
|
+
*/
|
|
317
|
+
|
|
318
|
+
interface UseDictLabelOptions {
|
|
319
|
+
/**
|
|
320
|
+
* Explicit vault. Either a `Vault` instance or its name. When a
|
|
321
|
+
* name is provided the composable calls `db.vault(name)` — which
|
|
322
|
+
* requires the vault to already be open via
|
|
323
|
+
* `await db.openVault(name)` elsewhere.
|
|
324
|
+
*
|
|
325
|
+
* When omitted, uses the currently-active vault on the global
|
|
326
|
+
* Noydb instance set via `setActiveNoydb()`. If no vault is open
|
|
327
|
+
* and none is provided, setup throws.
|
|
328
|
+
*/
|
|
329
|
+
readonly vault?: Vault | string;
|
|
330
|
+
/**
|
|
331
|
+
* Active locale. Pass a `Ref<string>` for live reactivity
|
|
332
|
+
* (e.g. `useI18n().locale` from vue-i18n, or `useLocale()` from a
|
|
333
|
+
* Nuxt module). A bare string is wrapped in a static ref.
|
|
334
|
+
* Defaults to `'en'`.
|
|
335
|
+
*/
|
|
336
|
+
readonly locale?: Ref<string> | string;
|
|
337
|
+
/**
|
|
338
|
+
* Fallback locale chain — evaluated in order when the primary
|
|
339
|
+
* locale has no translation. Use `'any'` as the final entry to
|
|
340
|
+
* accept any available locale. Defaults to `['en', 'any']`.
|
|
341
|
+
*/
|
|
342
|
+
readonly fallback?: string | readonly string[];
|
|
343
|
+
/**
|
|
344
|
+
* What to render when the key is absent from the dictionary.
|
|
345
|
+
*
|
|
346
|
+
* - `'key'` (default) — return the key itself. Matches the hub's
|
|
347
|
+
* stable-key invariant and surfaces typos during development.
|
|
348
|
+
* - `'empty'` — return `''`. Best for cells where a missing
|
|
349
|
+
* value should render blank.
|
|
350
|
+
* - `'placeholder'` — return `⟨missing:{key}⟩` for visible
|
|
351
|
+
* audit during QA.
|
|
352
|
+
*/
|
|
353
|
+
readonly onMissing?: 'key' | 'empty' | 'placeholder';
|
|
354
|
+
}
|
|
355
|
+
/**
|
|
356
|
+
* Build a reactive label lookup. Returns a factory `(key) => Ref<string>`.
|
|
357
|
+
*/
|
|
358
|
+
declare function useDictLabel(dictionaryName: string, options?: UseDictLabelOptions): (key: string) => Ref<string>;
|
|
359
|
+
|
|
149
360
|
/**
|
|
150
361
|
* `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.
|
|
151
362
|
*
|
|
@@ -408,4 +619,4 @@ interface UseCapabilityGrantReturn {
|
|
|
408
619
|
*/
|
|
409
620
|
declare function useCapabilityGrant(capability: string, options: UseCapabilityGrantOptions): UseCapabilityGrantReturn;
|
|
410
621
|
|
|
411
|
-
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 };
|
|
622
|
+
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.d.ts
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
1
|
import * as pinia from 'pinia';
|
|
2
2
|
import { StateTree, PiniaPlugin } from 'pinia';
|
|
3
3
|
import { ShallowRef, Ref, ComputedRef } from 'vue';
|
|
4
|
-
import { Query, Noydb, StandardSchemaV1, NoydbStore as NoydbStore$1, NoydbOptions, Role
|
|
4
|
+
import { Query, Noydb, StandardSchemaV1, Vault, I18nTextDescriptor, DictKeyDescriptor, NoydbStore as NoydbStore$1, NoydbOptions, Role } from '@noy-db/hub';
|
|
5
5
|
|
|
6
|
+
/**
|
|
7
|
+
* i18n resolution mode for a store's reads.
|
|
8
|
+
* - `'raw'` (default) — items keep `{ [locale]: string }` maps (today's behavior).
|
|
9
|
+
* - `'follow'` — resolve to the global `useNoydbI18n` locale; re-read on flip.
|
|
10
|
+
* - `{ locale, fallback? }` — pin to a fixed locale or own ref.
|
|
11
|
+
*/
|
|
12
|
+
type NoydbStoreI18nMode = 'raw' | 'follow' | {
|
|
13
|
+
locale: string | Ref<string>;
|
|
14
|
+
fallback?: string | readonly string[];
|
|
15
|
+
};
|
|
6
16
|
/**
|
|
7
17
|
* Reactive handle returned by `store.liveQuery(fn)`. Mirrors a hub
|
|
8
18
|
* `LiveQuery<R>` into Vue refs; `items` updates on every left- or
|
|
@@ -24,8 +34,22 @@ interface NoydbLiveQuery<R> {
|
|
|
24
34
|
* for full type safety.
|
|
25
35
|
*/
|
|
26
36
|
interface NoydbStoreOptions<T> {
|
|
27
|
-
/**
|
|
28
|
-
|
|
37
|
+
/**
|
|
38
|
+
* Vault (tenant) name, or a **resolver** evaluated at access time for
|
|
39
|
+
* federation routing (#383). A plain `string` binds the store to one
|
|
40
|
+
* vault for its lifetime (unchanged behavior). A `() => string` resolver
|
|
41
|
+
* is re-evaluated on every read/write and whenever its reactive
|
|
42
|
+
* dependencies change — so a store can follow the app's active scope into
|
|
43
|
+
* a per-client shard vault (e.g. `() => firm.shardVaultId(clientCode.value)`).
|
|
44
|
+
*
|
|
45
|
+
* When the resolved name changes, the store re-opens the new vault and
|
|
46
|
+
* re-hydrates `items` (mirrors the `i18n: 'follow'` re-read). If the
|
|
47
|
+
* resolver reads Vue reactive state, the re-hydrate is automatic; if it
|
|
48
|
+
* reads non-reactive state, the next `refresh()`/`add()`/`remove()`
|
|
49
|
+
* re-binds. Note: an in-flight `liveQuery()` handle stays bound to the
|
|
50
|
+
* vault it was created against — recreate it after a vault change.
|
|
51
|
+
*/
|
|
52
|
+
vault: string | (() => string);
|
|
29
53
|
/** Collection name within the vault. Defaults to the store id. */
|
|
30
54
|
collection?: string;
|
|
31
55
|
/**
|
|
@@ -53,6 +77,49 @@ interface NoydbStoreOptions<T> {
|
|
|
53
77
|
* perf cost, backwards compatible with usage).
|
|
54
78
|
*/
|
|
55
79
|
schema?: StandardSchemaV1<unknown, T>;
|
|
80
|
+
/**
|
|
81
|
+
* Optional per-field attestation schema. When set, it's installed on the
|
|
82
|
+
* underlying `Collection` (alongside `schema`) so `vault.issueAttestation(name, id)`
|
|
83
|
+
* can commit the declared fields against the firm's signing key — see
|
|
84
|
+
* `@noy-db/attestation` `AttestationFieldSchema`. Stores without it behave as before.
|
|
85
|
+
*/
|
|
86
|
+
attestation?: NonNullable<Parameters<Vault['collection']>[1]>['attestation'];
|
|
87
|
+
/**
|
|
88
|
+
* If true, the collection persists a JSON Schema baseline of `schema` so the
|
|
89
|
+
* schema-update protocol can detect drift on later opens. Forwarded as-is to
|
|
90
|
+
* the underlying `Collection`. Required for `schemaUpdate` to take effect.
|
|
91
|
+
*/
|
|
92
|
+
persistJsonSchema?: NonNullable<Parameters<Vault['collection']>[1]>['persistJsonSchema'];
|
|
93
|
+
/**
|
|
94
|
+
* Ordered schema-update strategies (e.g. `coordinatedCutover`, `additiveOnly`,
|
|
95
|
+
* `lockSchema`) applied when a stored baseline differs from the current
|
|
96
|
+
* `schema`. Forwarded as-is to the underlying `Collection`. Requires
|
|
97
|
+
* `persistJsonSchema: true` (drift detection needs the persisted baseline).
|
|
98
|
+
* Lets a `defineNoydbStore`-defined collection opt into migration tracking
|
|
99
|
+
* declaratively, without a pre-registration `vault.collection(...)` call.
|
|
100
|
+
*/
|
|
101
|
+
schemaUpdate?: NonNullable<Parameters<Vault['collection']>[1]>['schemaUpdate'];
|
|
102
|
+
/**
|
|
103
|
+
* Per-field `i18nText()` descriptors. Forwarded to the underlying
|
|
104
|
+
* `Collection` so locale resolution and required-translation validation
|
|
105
|
+
* run declaratively without a separate `vault.collection(name, { i18nFields })`
|
|
106
|
+
* pre-registration call.
|
|
107
|
+
*/
|
|
108
|
+
i18nFields?: Record<string, I18nTextDescriptor>;
|
|
109
|
+
/**
|
|
110
|
+
* Per-field `dictKey()` descriptors. Forwarded to the underlying
|
|
111
|
+
* `Collection` so dictionary label resolution runs declaratively.
|
|
112
|
+
*/
|
|
113
|
+
dictKeyFields?: Record<string, DictKeyDescriptor>;
|
|
114
|
+
/**
|
|
115
|
+
* How the store resolves i18nText/dictKey fields on read.
|
|
116
|
+
* Default `'raw'` — items keep `{ [locale]: string }` maps (today's
|
|
117
|
+
* behavior; zero breaking change). `'follow'` resolves to the global
|
|
118
|
+
* `useNoydbI18n` locale and re-reads when it changes. `{ locale }`
|
|
119
|
+
* pins to a fixed locale or own ref. Set `'raw'` for stores whose maps
|
|
120
|
+
* feed identity/export reads or a per-cell bilingual toggle.
|
|
121
|
+
*/
|
|
122
|
+
i18n?: NoydbStoreI18nMode;
|
|
56
123
|
}
|
|
57
124
|
/**
|
|
58
125
|
* The runtime shape of the store returned by `defineNoydbStore`.
|
|
@@ -146,6 +213,150 @@ declare function getActiveNoydb(): Noydb | null;
|
|
|
146
213
|
*/
|
|
147
214
|
declare function resolveNoydb(explicit?: Noydb | null): Noydb;
|
|
148
215
|
|
|
216
|
+
/** Minimal vault shape needed to sync an ambient locale. */
|
|
217
|
+
interface LocaleSyncable {
|
|
218
|
+
setLocale(locale: string | undefined): void;
|
|
219
|
+
}
|
|
220
|
+
interface SetLocaleOptions {
|
|
221
|
+
/**
|
|
222
|
+
* Vault(s) to ALSO update via `vault.setLocale` (opt-in). Omit to keep
|
|
223
|
+
* the operation state-only — the safe default for locale-less vaults.
|
|
224
|
+
*/
|
|
225
|
+
readonly syncVault?: LocaleSyncable | readonly LocaleSyncable[];
|
|
226
|
+
}
|
|
227
|
+
declare const useNoydbI18n: pinia.StoreDefinition<"noydb-i18n", Pick<{
|
|
228
|
+
locale: Ref<string, string>;
|
|
229
|
+
fallback: Ref<string[], string[]>;
|
|
230
|
+
setLocale: (l: string, opts?: SetLocaleOptions) => void;
|
|
231
|
+
setFallback: (chain: string[]) => void;
|
|
232
|
+
bindTo: (source: Ref<string>, opts?: {
|
|
233
|
+
immediate?: boolean;
|
|
234
|
+
}) => () => void;
|
|
235
|
+
}, "locale" | "fallback">, Pick<{
|
|
236
|
+
locale: Ref<string, string>;
|
|
237
|
+
fallback: Ref<string[], string[]>;
|
|
238
|
+
setLocale: (l: string, opts?: SetLocaleOptions) => void;
|
|
239
|
+
setFallback: (chain: string[]) => void;
|
|
240
|
+
bindTo: (source: Ref<string>, opts?: {
|
|
241
|
+
immediate?: boolean;
|
|
242
|
+
}) => () => void;
|
|
243
|
+
}, never>, Pick<{
|
|
244
|
+
locale: Ref<string, string>;
|
|
245
|
+
fallback: Ref<string[], string[]>;
|
|
246
|
+
setLocale: (l: string, opts?: SetLocaleOptions) => void;
|
|
247
|
+
setFallback: (chain: string[]) => void;
|
|
248
|
+
bindTo: (source: Ref<string>, opts?: {
|
|
249
|
+
immediate?: boolean;
|
|
250
|
+
}) => () => void;
|
|
251
|
+
}, "setLocale" | "setFallback" | "bindTo">>;
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* `useI18nField` — a reactive `pickLang` for a single i18nText map.
|
|
255
|
+
*
|
|
256
|
+
* Resolves a `{ [locale]: string }` map to the active locale, recomputing
|
|
257
|
+
* when the locale (or a reactive source) changes. Uses hub's
|
|
258
|
+
* `resolveI18nText` with `policy: 'null'`, so it never throws and never
|
|
259
|
+
* yields `undefined` — `null` when no locale (and no fallback) resolves.
|
|
260
|
+
*
|
|
261
|
+
* Follows the global `useNoydbI18n` locale/fallback unless overridden.
|
|
262
|
+
* Ideal for resolving one field at the edge while siblings stay raw
|
|
263
|
+
* (e.g. a bilingual section reading raw maps).
|
|
264
|
+
*
|
|
265
|
+
* @public
|
|
266
|
+
*/
|
|
267
|
+
|
|
268
|
+
type MapSource = Record<string, string> | (() => Record<string, string> | undefined | null);
|
|
269
|
+
interface UseI18nFieldOptions {
|
|
270
|
+
/** Override the active locale (string or ref). Defaults to the global. */
|
|
271
|
+
readonly locale?: string | Ref<string>;
|
|
272
|
+
/** Override the fallback chain. Defaults to the global. */
|
|
273
|
+
readonly fallback?: string | readonly string[];
|
|
274
|
+
}
|
|
275
|
+
declare function useI18nField(source: MapSource, opts?: UseI18nFieldOptions): Ref<string | null>;
|
|
276
|
+
|
|
277
|
+
/**
|
|
278
|
+
* `useDictLabel(name, options)` — Vue composable for rendering
|
|
279
|
+
* `dictKey` fields at template time.
|
|
280
|
+
*
|
|
281
|
+
* The i18n boundary pattern has records store a **stable key**; the
|
|
282
|
+
* label lives in a reserved `_dict_<name>` collection and is resolved
|
|
283
|
+
* at render time. Every Vue / Nuxt consumer ends up writing the same
|
|
284
|
+
* wrapper — this composable replaces that boilerplate.
|
|
285
|
+
*
|
|
286
|
+
* ```vue
|
|
287
|
+
* <script setup lang="ts">
|
|
288
|
+
* import { useDictLabel } from '@noy-db/in-pinia'
|
|
289
|
+
* const label = useDictLabel('invoiceStatus')
|
|
290
|
+
* </script>
|
|
291
|
+
*
|
|
292
|
+
* <template>
|
|
293
|
+
* <td v-for="inv in invoices" :key="inv.id">
|
|
294
|
+
* {{ label(inv.status).value }}
|
|
295
|
+
* </td>
|
|
296
|
+
* </template>
|
|
297
|
+
* ```
|
|
298
|
+
*
|
|
299
|
+
* ## Reactivity
|
|
300
|
+
*
|
|
301
|
+
* `label(key)` returns a `Ref<string>` that updates when the locale
|
|
302
|
+
* changes (via the passed-in `locale` ref).
|
|
303
|
+
*
|
|
304
|
+
* **Known limitation:** mutations via `vault.dictionary(name).put()`
|
|
305
|
+
* bypass the Collection emitter — the hub's `DictionaryHandle` writes
|
|
306
|
+
* through the adapter directly, so labels cached by this composable
|
|
307
|
+
* won't refresh for those writes until either (a) the locale changes
|
|
308
|
+
* or (b) the caller re-creates the composable. Tracked as a
|
|
309
|
+
* hub follow-up (route dict writes through the Collection emitter).
|
|
310
|
+
*
|
|
311
|
+
* The underlying fetch is async, so a newly-constructed label starts
|
|
312
|
+
* at its "missing" sentinel (the key itself by default) and updates
|
|
313
|
+
* to the resolved string within one tick.
|
|
314
|
+
*
|
|
315
|
+
* @module
|
|
316
|
+
*/
|
|
317
|
+
|
|
318
|
+
interface UseDictLabelOptions {
|
|
319
|
+
/**
|
|
320
|
+
* Explicit vault. Either a `Vault` instance or its name. When a
|
|
321
|
+
* name is provided the composable calls `db.vault(name)` — which
|
|
322
|
+
* requires the vault to already be open via
|
|
323
|
+
* `await db.openVault(name)` elsewhere.
|
|
324
|
+
*
|
|
325
|
+
* When omitted, uses the currently-active vault on the global
|
|
326
|
+
* Noydb instance set via `setActiveNoydb()`. If no vault is open
|
|
327
|
+
* and none is provided, setup throws.
|
|
328
|
+
*/
|
|
329
|
+
readonly vault?: Vault | string;
|
|
330
|
+
/**
|
|
331
|
+
* Active locale. Pass a `Ref<string>` for live reactivity
|
|
332
|
+
* (e.g. `useI18n().locale` from vue-i18n, or `useLocale()` from a
|
|
333
|
+
* Nuxt module). A bare string is wrapped in a static ref.
|
|
334
|
+
* Defaults to `'en'`.
|
|
335
|
+
*/
|
|
336
|
+
readonly locale?: Ref<string> | string;
|
|
337
|
+
/**
|
|
338
|
+
* Fallback locale chain — evaluated in order when the primary
|
|
339
|
+
* locale has no translation. Use `'any'` as the final entry to
|
|
340
|
+
* accept any available locale. Defaults to `['en', 'any']`.
|
|
341
|
+
*/
|
|
342
|
+
readonly fallback?: string | readonly string[];
|
|
343
|
+
/**
|
|
344
|
+
* What to render when the key is absent from the dictionary.
|
|
345
|
+
*
|
|
346
|
+
* - `'key'` (default) — return the key itself. Matches the hub's
|
|
347
|
+
* stable-key invariant and surfaces typos during development.
|
|
348
|
+
* - `'empty'` — return `''`. Best for cells where a missing
|
|
349
|
+
* value should render blank.
|
|
350
|
+
* - `'placeholder'` — return `⟨missing:{key}⟩` for visible
|
|
351
|
+
* audit during QA.
|
|
352
|
+
*/
|
|
353
|
+
readonly onMissing?: 'key' | 'empty' | 'placeholder';
|
|
354
|
+
}
|
|
355
|
+
/**
|
|
356
|
+
* Build a reactive label lookup. Returns a factory `(key) => Ref<string>`.
|
|
357
|
+
*/
|
|
358
|
+
declare function useDictLabel(dictionaryName: string, options?: UseDictLabelOptions): (key: string) => Ref<string>;
|
|
359
|
+
|
|
149
360
|
/**
|
|
150
361
|
* `createNoydbPiniaPlugin` — augmentation path for existing Pinia stores.
|
|
151
362
|
*
|
|
@@ -408,4 +619,4 @@ interface UseCapabilityGrantReturn {
|
|
|
408
619
|
*/
|
|
409
620
|
declare function useCapabilityGrant(capability: string, options: UseCapabilityGrantOptions): UseCapabilityGrantReturn;
|
|
410
621
|
|
|
411
|
-
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 };
|
|
622
|
+
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 };
|