@_linked/translation 0.9.5 → 0.10.0

package/README.md

@@ -37,6 +37,7 @@ package works without either peer.
 - `@_linked/translation/key-sync` — development-time source extraction and sync
 - `@_linked/translation/key-sync/node` — recursive source-tree scan + dry-run/apply orchestration
 - `@_linked/translation/shape-catalog` — package-owned translations attached to stable shape/property IRIs
+- `@_linked/translation/shape-key-copies` — server-side: one shape key across every app that holds it (list, propagate, clear overrides)
 - `@_linked/translation/discovery` — portable declarations and deterministic inventory merging
 - `@_linked/translation/linked-discovery` — serialized LINKED package catalogs
 - `@_linked/translation/archive` — full-fidelity backup and pure restore planning
@@ -87,6 +88,35 @@ Existing app-authored translations are never overwritten. Packages may export
 the TypeScript object or ship the same contract as JSON for a host's tooling
 to discover without executing application code.
 
+### One shape key across apps
+
+Every app that uses a shape keeps its own copy of each key the shape carries.
+An app may reword its copy; that marks the copy `overridden` and keeps the
+shape's wording at that moment as `shapeSource`. The server-side
+`@_linked/translation/shape-key-copies` entry point acts on all copies of one
+shape key at once:
+
+```ts
+import {
+  listShapeKeyCopies,
+  propagateShapeKeySource,
+  clearShapeKeyOverride,
+} from '@_linked/translation/shape-key-copies';
+
+// Every app's copy, with its override state and translated languages.
+await listShapeKeyCopies({ shapeIri, key: 'person.givenName' });
+// New wording for every copy that follows the shape; overrides keep theirs.
+await propagateShapeKeySource({ shapeIri, key: 'person.givenName', sourceText: 'Given name' });
+// Revert overrides (all apps, or one with `appId`) so they follow the shape again.
+await clearShapeKeyOverride({ shapeIri, key: 'person.givenName', appId });
+```
+
+Each text change is a normal key write (`upsertTranslationKey`): it records a
+new key version and marks that key's units stale. A clear reverts to the text of
+a copy that still follows the shape, or else to the copy's own `shapeSource`.
+The operations run on the default dataset and check no permissions: the host
+decides who may call them and which dataset they run in.
+
 Authoring tools — editors, menus, entitlements, capability activation — are
 deliberately not part of this package. They belong to the host application, so
 any app can use this runtime without depending on a particular host.

package/lib/esm/shape-key-copies.d.ts

@@ -0,0 +1,62 @@
+import { type TranslationKeyWriteContext } from './shapes/TranslationProvider.js';
+/** One app's copy of a shape key. */
+export interface ShapeKeyCopyRecord {
+    /** The key node. */
+    id: string;
+    key: string;
+    shapeIri: string;
+    appId: string;
+    sourceText?: string;
+    /** The app reworded this copy; propagation leaves it alone. */
+    overridden: boolean;
+    /** The shape's text when the app first reworded the copy: what a clear reverts to without a sibling. */
+    shapeSource?: string;
+    ofProperty?: string;
+    fromPackage?: string;
+    namespace?: string;
+    description?: string;
+    kind?: 'ui' | 'content';
+    format?: 'simple' | 'icu';
+    /** The languages this copy has a unit for, sorted. */
+    languages: string[];
+}
+export interface ShapeKeyQuery {
+    /** One shape's keys; omitted, every shape key. */
+    shapeIri?: string;
+    /** One key name of that shape. */
+    key?: string;
+}
+/**
+ * The copies of the shape keys `query` names, one per app. A key that names no app is not a
+ * copy and is left out.
+ */
+export declare function listShapeKeyCopies(query?: ShapeKeyQuery): Promise<ShapeKeyCopyRecord[]>;
+export interface ShapeKeyPropagation {
+    /** Apps whose copy now has the new text (or had it already). */
+    updatedApps: string[];
+    /** Apps whose copy is overridden and was left alone. */
+    skippedOverrides: string[];
+}
+/**
+ * Give one shape key a new source text in every app whose copy follows the shape. Overridden
+ * copies keep their text. A copy whose text changes gets a new key version and stale units.
+ */
+export declare function propagateShapeKeySource(data: {
+    shapeIri: string;
+    key: string;
+    sourceText: string;
+}, authorship?: Pick<TranslationKeyWriteContext, 'createdBy'>): Promise<ShapeKeyPropagation>;
+/**
+ * Clear the override on one shape key's copies: every overridden copy, or only `appId`'s. Each
+ * reverts to the text of a copy that follows the shape, or, when none does, to its own snapshot
+ * (`shapeSource`); with neither, it keeps its own text. The flag is reset (`overridden: false`)
+ * and the snapshot removed, so the copy follows the shape again. Returns the apps cleared; a copy
+ * with no text at all is not written and not counted.
+ */
+export declare function clearShapeKeyOverride(data: {
+    shapeIri: string;
+    key: string;
+    appId?: string;
+}, authorship?: Pick<TranslationKeyWriteContext, 'createdBy'>): Promise<{
+    clearedApps: string[];
+}>;

package/lib/esm/shape-key-copies.js

@@ -0,0 +1,156 @@
+/**
+ * Shape keys across apps: every app that uses a shape holds its own copy of each translation key
+ * the shape carries (`TranslationKey` with `ofShape`, one per `ofApplication`). These operations
+ * act on all of a shape key's copies at once:
+ *
+ * - {@link listShapeKeyCopies} reads them, with each copy's override state and the languages it
+ *   is translated into;
+ * - {@link propagateShapeKeySource} gives every copy that follows the shape a new source text;
+ *   a copy the app reworded (`overridden`) keeps its own text;
+ * - {@link clearShapeKeyOverride} reverts overridden copies (all, or one app's) to the shape's
+ *   current text, so they follow the shape again.
+ *
+ * Every text change goes through {@link upsertTranslationKey}, so it gets a new key version and
+ * marks the key's units stale exactly as any other source change does. Like the other key writes,
+ * they run on the default dataset (`LinkedStorage`); a host that keeps each app's data in its own
+ * dataset runs them in that dataset's context. They decide nothing about who may call them: the
+ * host checks that before.
+ */
+import { TranslationKey } from './shapes/TranslationKey.js';
+import { TranslationUnit } from './shapes/TranslationUnit.js';
+import { upsertTranslationKey, } from './shapes/TranslationProvider.js';
+const iri = (value) => typeof value === 'string' ? value || undefined : (value === null || value === void 0 ? void 0 : value.id) || undefined;
+const text = (value) => value === undefined || value === null || value === '' ? undefined : String(value);
+/** The flag as stored: a boolean, or the string "true" an older writer left. */
+const isOverridden = (value) => value === true || value === 'true';
+/** The node a key write addresses: `upsertTranslationKey` keys a copy by its app and key name. */
+const keyIri = (appId, key) => `${appId.replace(/\/$/, '')}/translation/key/${encodeURIComponent(key)}`;
+const keyWhere = (query) => (k) => {
+    const shape = query.shapeIri ? k.ofShape.equals({ id: query.shapeIri }) : k.ofShape.isDefined();
+    return query.key === undefined ? shape : shape.and(k.key.equals(query.key));
+};
+/**
+ * The copies of the shape keys `query` names, one per app. A key that names no app is not a
+ * copy and is left out.
+ */
+export async function listShapeKeyCopies(query = {}) {
+    var _a, _b;
+    const [keys, units] = await Promise.all([
+        TranslationKey.select((k) => [
+            k.key,
+            k.ofShape,
+            k.ofApplication,
+            k.sourceText,
+            k.overridden,
+            k.shapeSource,
+            k.ofProperty,
+            k.fromPackage,
+            k.namespace,
+            k.description,
+            k.kind,
+            k.format,
+        ]).where(keyWhere(query)),
+        TranslationUnit.select((u) => [u.ofKey, u.language]).where(((u) => keyWhere(query)(u.ofKey))),
+    ]);
+    const languagesOf = new Map();
+    for (const unit of (units !== null && units !== void 0 ? units : [])) {
+        const keyId = iri(unit.ofKey);
+        const language = text(unit.language);
+        if (!keyId || !language)
+            continue;
+        const set = (_a = languagesOf.get(keyId)) !== null && _a !== void 0 ? _a : new Set();
+        set.add(language);
+        languagesOf.set(keyId, set);
+    }
+    const copies = [];
+    for (const row of (keys !== null && keys !== void 0 ? keys : [])) {
+        const id = iri(row.id);
+        const key = text(row.key);
+        const shapeIri = iri(row.ofShape);
+        const appId = iri(row.ofApplication);
+        if (!id || !key || !shapeIri || !appId)
+            continue;
+        copies.push({
+            id,
+            key,
+            shapeIri,
+            appId,
+            sourceText: text(row.sourceText),
+            overridden: isOverridden(row.overridden),
+            shapeSource: text(row.shapeSource),
+            ofProperty: iri(row.ofProperty),
+            fromPackage: text(row.fromPackage),
+            namespace: text(row.namespace),
+            description: text(row.description),
+            kind: row.kind === 'content' ? 'content' : row.kind === 'ui' ? 'ui' : undefined,
+            format: row.format === 'icu' ? 'icu' : row.format === 'simple' ? 'simple' : undefined,
+            languages: [...((_b = languagesOf.get(id)) !== null && _b !== void 0 ? _b : [])].sort(),
+        });
+    }
+    return copies;
+}
+/** The copy's own declaration, so a text write keeps what the copy declares. */
+function asKeyInput(copy, sourceText) {
+    if (copy.id !== keyIri(copy.appId, copy.key)) {
+        // A key write addresses the app's key node; writing this copy there would create a second key.
+        throw new Error(`Shape key copy ${copy.id} is not at its app's key node; it was not written.`);
+    }
+    return {
+        appId: copy.appId,
+        key: copy.key,
+        sourceText,
+        namespace: copy.namespace,
+        description: copy.description,
+        kind: copy.kind,
+        ofShape: copy.shapeIri,
+        ofProperty: copy.ofProperty,
+        fromPackage: copy.fromPackage,
+        format: copy.format,
+    };
+}
+const appsOf = (copies) => [...new Set(copies.map((c) => c.appId))].sort();
+/**
+ * Give one shape key a new source text in every app whose copy follows the shape. Overridden
+ * copies keep their text. A copy whose text changes gets a new key version and stale units.
+ */
+export async function propagateShapeKeySource(data, authorship = {}) {
+    var _a;
+    const sourceText = (_a = data.sourceText) === null || _a === void 0 ? void 0 : _a.trim();
+    if (!sourceText)
+        throw new Error('sourceText is required.');
+    const copies = await listShapeKeyCopies({ shapeIri: data.shapeIri, key: data.key });
+    const following = copies.filter((c) => !c.overridden);
+    for (const copy of following) {
+        // A declaration refresh: it never marks the copy overridden.
+        await upsertTranslationKey(asKeyInput(copy, sourceText), { ...authorship, source: 'declaration-sync' });
+    }
+    return { updatedApps: appsOf(following), skippedOverrides: appsOf(copies.filter((c) => c.overridden)) };
+}
+/**
+ * Clear the override on one shape key's copies: every overridden copy, or only `appId`'s. Each
+ * reverts to the text of a copy that follows the shape, or, when none does, to its own snapshot
+ * (`shapeSource`); with neither, it keeps its own text. The flag is reset (`overridden: false`)
+ * and the snapshot removed, so the copy follows the shape again. Returns the apps cleared; a copy
+ * with no text at all is not written and not counted.
+ */
+export async function clearShapeKeyOverride(data, authorship = {}) {
+    var _a, _b;
+    const copies = await listShapeKeyCopies({ shapeIri: data.shapeIri, key: data.key });
+    const overridden = copies.filter((c) => c.overridden && (data.appId === undefined || c.appId === data.appId));
+    const canonical = (_a = copies.find((c) => !c.overridden && c.sourceText !== undefined)) === null || _a === void 0 ? void 0 : _a.sourceText;
+    const cleared = [];
+    for (const copy of overridden) {
+        const next = (_b = canonical !== null && canonical !== void 0 ? canonical : copy.shapeSource) !== null && _b !== void 0 ? _b : copy.sourceText;
+        if (next === undefined)
+            continue;
+        // An explicit app edit: the only write that may reset the override flag.
+        await upsertTranslationKey({ ...asKeyInput(copy, next), overridden: false }, { ...authorship, source: 'app-edit' });
+        if (copy.shapeSource !== undefined) {
+            // In the mutation DSL an explicit `undefined` removes the value.
+            await TranslationKey.update({ shapeSource: undefined }).for({ id: copy.id });
+        }
+        cleared.push(copy);
+    }
+    return { clearedApps: appsOf(cleared) };
+}
+//# sourceMappingURL=shape-key-copies.js.map

package/lib/esm/shape-key-copies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-key-copies.js","sourceRoot":"","sources":["../../src/shape-key-copies.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shape keys across apps: every app that uses a shape holds its own copy of each translation key\n * the shape carries (`TranslationKey` with `ofShape`, one per `ofApplication`). These operations\n * act on all of a shape key's copies at once:\n *\n * - {@link listShapeKeyCopies} reads them, with each copy's override state and the languages it\n *   is translated into;\n * - {@link propagateShapeKeySource} gives every copy that follows the shape a new source text;\n *   a copy the app reworded (`overridden`) keeps its own text;\n * - {@link clearShapeKeyOverride} reverts overridden copies (all, or one app's) to the shape's\n *   current text, so they follow the shape again.\n *\n * Every text change goes through {@link upsertTranslationKey}, so it gets a new key version and\n * marks the key's units stale exactly as any other source change does. Like the other key writes,\n * they run on the default dataset (`LinkedStorage`); a host that keeps each app's data in its own\n * dataset runs them in that dataset's context. They decide nothing about who may call them: the\n * host checks that before.\n */\nimport { TranslationKey } from './shapes/TranslationKey.js';\nimport { TranslationUnit } from './shapes/TranslationUnit.js';\nimport {\n  upsertTranslationKey,\n  type TranslationKeyInput,\n  type TranslationKeyWriteContext,\n} from './shapes/TranslationProvider.js';\n\n/** One app's copy of a shape key. */\nexport interface ShapeKeyCopyRecord {\n  /** The key node. */\n  id: string;\n  key: string;\n  shapeIri: string;\n  appId: string;\n  sourceText?: string;\n  /** The app reworded this copy; propagation leaves it alone. */\n  overridden: boolean;\n  /** The shape's text when the app first reworded the copy: what a clear reverts to without a sibling. */\n  shapeSource?: string;\n  ofProperty?: string;\n  fromPackage?: string;\n  namespace?: string;\n  description?: string;\n  kind?: 'ui' | 'content';\n  format?: 'simple' | 'icu';\n  /** The languages this copy has a unit for, sorted. */\n  languages: string[];\n}\n\nexport interface ShapeKeyQuery {\n  /** One shape's keys; omitted, every shape key. */\n  shapeIri?: string;\n  /** One key name of that shape. */\n  key?: string;\n}\n\nconst iri = (value: unknown): string | undefined =>\n  typeof value === 'string' ? value || undefined : (value as { id?: string } | undefined)?.id || undefined;\nconst text = (value: unknown): string | undefined =>\n  value === undefined || value === null || value === '' ? undefined : String(value);\n/** The flag as stored: a boolean, or the string \"true\" an older writer left. */\nconst isOverridden = (value: unknown): boolean => value === true || value === 'true';\n\n/** The node a key write addresses: `upsertTranslationKey` keys a copy by its app and key name. */\nconst keyIri = (appId: string, key: string): string =>\n  `${appId.replace(/\\/$/, '')}/translation/key/${encodeURIComponent(key)}`;\n\nconst keyWhere = (query: ShapeKeyQuery) => (k: any) => {\n  const shape = query.shapeIri ? k.ofShape.equals({ id: query.shapeIri }) : k.ofShape.isDefined();\n  return query.key === undefined ? shape : shape.and(k.key.equals(query.key));\n};\n\n/**\n * The copies of the shape keys `query` names, one per app. A key that names no app is not a\n * copy and is left out.\n */\nexport async function listShapeKeyCopies(query: ShapeKeyQuery = {}): Promise<ShapeKeyCopyRecord[]> {\n  const [keys, units] = await Promise.all([\n    TranslationKey.select((k) => [\n      k.key,\n      k.ofShape,\n      k.ofApplication,\n      k.sourceText,\n      k.overridden,\n      k.shapeSource,\n      k.ofProperty,\n      k.fromPackage,\n      k.namespace,\n      k.description,\n      k.kind,\n      k.format,\n    ]).where(keyWhere(query) as any),\n    TranslationUnit.select((u) => [u.ofKey, u.language]).where(((u: any) => keyWhere(query)(u.ofKey)) as any),\n  ]);\n  const languagesOf = new Map<string, Set<string>>();\n  for (const unit of (units ?? []) as any[]) {\n    const keyId = iri(unit.ofKey);\n    const language = text(unit.language);\n    if (!keyId || !language) continue;\n    const set = languagesOf.get(keyId) ?? new Set<string>();\n    set.add(language);\n    languagesOf.set(keyId, set);\n  }\n  const copies: ShapeKeyCopyRecord[] = [];\n  for (const row of (keys ?? []) as any[]) {\n    const id = iri(row.id);\n    const key = text(row.key);\n    const shapeIri = iri(row.ofShape);\n    const appId = iri(row.ofApplication);\n    if (!id || !key || !shapeIri || !appId) continue;\n    copies.push({\n      id,\n      key,\n      shapeIri,\n      appId,\n      sourceText: text(row.sourceText),\n      overridden: isOverridden(row.overridden),\n      shapeSource: text(row.shapeSource),\n      ofProperty: iri(row.ofProperty),\n      fromPackage: text(row.fromPackage),\n      namespace: text(row.namespace),\n      description: text(row.description),\n      kind: row.kind === 'content' ? 'content' : row.kind === 'ui' ? 'ui' : undefined,\n      format: row.format === 'icu' ? 'icu' : row.format === 'simple' ? 'simple' : undefined,\n      languages: [...(languagesOf.get(id) ?? [])].sort(),\n    });\n  }\n  return copies;\n}\n\n/** The copy's own declaration, so a text write keeps what the copy declares. */\nfunction asKeyInput(copy: ShapeKeyCopyRecord, sourceText: string): TranslationKeyInput {\n  if (copy.id !== keyIri(copy.appId, copy.key)) {\n    // A key write addresses the app's key node; writing this copy there would create a second key.\n    throw new Error(`Shape key copy ${copy.id} is not at its app's key node; it was not written.`);\n  }\n  return {\n    appId: copy.appId,\n    key: copy.key,\n    sourceText,\n    namespace: copy.namespace,\n    description: copy.description,\n    kind: copy.kind,\n    ofShape: copy.shapeIri,\n    ofProperty: copy.ofProperty,\n    fromPackage: copy.fromPackage,\n    format: copy.format,\n  };\n}\n\nconst appsOf = (copies: readonly ShapeKeyCopyRecord[]): string[] => [...new Set(copies.map((c) => c.appId))].sort();\n\nexport interface ShapeKeyPropagation {\n  /** Apps whose copy now has the new text (or had it already). */\n  updatedApps: string[];\n  /** Apps whose copy is overridden and was left alone. */\n  skippedOverrides: string[];\n}\n\n/**\n * Give one shape key a new source text in every app whose copy follows the shape. Overridden\n * copies keep their text. A copy whose text changes gets a new key version and stale units.\n */\nexport async function propagateShapeKeySource(\n  data: { shapeIri: string; key: string; sourceText: string },\n  authorship: Pick<TranslationKeyWriteContext, 'createdBy'> = {}\n): Promise<ShapeKeyPropagation> {\n  const sourceText = data.sourceText?.trim();\n  if (!sourceText) throw new Error('sourceText is required.');\n  const copies = await listShapeKeyCopies({ shapeIri: data.shapeIri, key: data.key });\n  const following = copies.filter((c) => !c.overridden);\n  for (const copy of following) {\n    // A declaration refresh: it never marks the copy overridden.\n    await upsertTranslationKey(asKeyInput(copy, sourceText), { ...authorship, source: 'declaration-sync' });\n  }\n  return { updatedApps: appsOf(following), skippedOverrides: appsOf(copies.filter((c) => c.overridden)) };\n}\n\n/**\n * Clear the override on one shape key's copies: every overridden copy, or only `appId`'s. Each\n * reverts to the text of a copy that follows the shape, or, when none does, to its own snapshot\n * (`shapeSource`); with neither, it keeps its own text. The flag is reset (`overridden: false`)\n * and the snapshot removed, so the copy follows the shape again. Returns the apps cleared; a copy\n * with no text at all is not written and not counted.\n */\nexport async function clearShapeKeyOverride(\n  data: { shapeIri: string; key: string; appId?: string },\n  authorship: Pick<TranslationKeyWriteContext, 'createdBy'> = {}\n): Promise<{ clearedApps: string[] }> {\n  const copies = await listShapeKeyCopies({ shapeIri: data.shapeIri, key: data.key });\n  const overridden = copies.filter((c) => c.overridden && (data.appId === undefined || c.appId === data.appId));\n  const canonical = copies.find((c) => !c.overridden && c.sourceText !== undefined)?.sourceText;\n  const cleared: ShapeKeyCopyRecord[] = [];\n  for (const copy of overridden) {\n    const next = canonical ?? copy.shapeSource ?? copy.sourceText;\n    if (next === undefined) continue;\n    // An explicit app edit: the only write that may reset the override flag.\n    await upsertTranslationKey({ ...asKeyInput(copy, next), overridden: false }, { ...authorship, source: 'app-edit' });\n    if (copy.shapeSource !== undefined) {\n      // In the mutation DSL an explicit `undefined` removes the value.\n      await TranslationKey.update({ shapeSource: undefined } as any).for({ id: copy.id } as any);\n    }\n    cleared.push(copy);\n  }\n  return { clearedApps: appsOf(cleared) };\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@_linked/translation",
   "description": "LINKED translation management — graph-native i18n keys + units, Tolgee-compatible client, CDN delivery.",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "packageManager": "npm@12.2.0",
   "linked": {
     "kind": "library"