@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/languageHints.ts

@@ -0,0 +1,153 @@
+import { MEDIA } from './caret'
+import { FIELD_ATTR, RICH_ATTR } from './shape'
+
+type HintKind = 'fallback' | 'empty'
+const HINT_ATTR = 'data-u90-language-hint'
+
+/** Own only preview decorations: never insert a placeholder into an editable field. */
+export function createLanguageHints() {
+  let hints = new Map<string, HintKind>()
+  const marked = new Map<HTMLElement, string | null>()
+  const cues = new Map<HTMLElement, HTMLSpanElement>()
+  let style: HTMLStyleElement | null = null
+  let frame = 0
+  let disposed = false
+
+  const remove = (element: HTMLElement) => {
+    const previous = marked.get(element)
+    if (previous == null) element.removeAttribute(HINT_ATTR)
+    else element.setAttribute(HINT_ATTR, previous)
+    marked.delete(element)
+    sizes.unobserve(element)
+    cues.get(element)?.remove()
+    cues.delete(element)
+  }
+
+  const sync = () => {
+    frame = 0
+    if (disposed) return
+    const current = new Set<HTMLElement>()
+    if (hints.size) {
+      for (const element of document.querySelectorAll<HTMLElement>(`[${FIELD_ATTR}]`)) {
+        const kind = hints.get(element.getAttribute(FIELD_ATTR) ?? '')
+        if (!kind || element.matches(MEDIA)) continue
+        current.add(element)
+        if (!marked.has(element)) {
+          marked.set(element, element.getAttribute(HINT_ATTR))
+          sizes.observe(element)
+        }
+        if (element.getAttribute(HINT_ATTR) !== kind) element.setAttribute(HINT_ATTR, kind)
+
+        // A fallback can disappear during local editing before its next content push.
+        // The cue follows the rendered words and lives outside the field's DOM tree.
+        const visibility = getComputedStyle(element).visibility
+        const empty =
+          !element.textContent?.trim() &&
+          !element.querySelector(MEDIA) &&
+          element.getClientRects().length > 0 &&
+          visibility !== 'hidden' &&
+          visibility !== 'collapse'
+        let cue = cues.get(element)
+        if (empty) {
+          if (!cue) {
+            cue = document.createElement('span')
+            cue.setAttribute('data-u90-language-cue', '')
+            cue.setAttribute('aria-hidden', 'true')
+            cue.textContent = 'Translation missing'
+            document.body.append(cue)
+            cues.set(element, cue)
+          }
+          const rect = element.getBoundingClientRect()
+          cue.style.left = `${Math.max(0, rect.left)}px`
+          cue.style.top = `${rect.top}px`
+        } else if (cue) {
+          cue.remove()
+          cues.delete(element)
+        }
+      }
+    }
+    for (const element of marked.keys()) if (!current.has(element)) remove(element)
+    if (current.size && !style) {
+      style = document.createElement('style')
+      style.setAttribute('data-u90-language-hints', '')
+      style.textContent = `
+        [${HINT_ATTR}] {
+          text-decoration-line: underline !important;
+          text-decoration-style: dotted !important;
+          text-decoration-color: #d97706 !important;
+          text-underline-offset: .2em !important;
+          background-color: rgb(245 158 11 / .08) !important;
+        }
+        [data-u90-language-cue] {
+          position: fixed !important;
+          z-index: 2147483646 !important;
+          pointer-events: none !important;
+          user-select: none !important;
+          display: inline-block !important;
+          font: 500 11px/1.4 system-ui, sans-serif !important;
+          color: #92400e !important;
+          background: #fffbeb !important;
+          border: 1px dotted #d97706 !important;
+          border-radius: 3px !important;
+          padding: 1px 4px !important;
+          max-width: calc(100vw - 8px) !important;
+        }
+      `
+      document.head.append(style)
+    } else if (!current.size && style) {
+      style.remove()
+      style = null
+    }
+  }
+  const schedule = () => {
+    if (!disposed && !frame) frame = requestAnimationFrame(sync)
+  }
+  const sizes = new ResizeObserver(schedule)
+  const mutations = new MutationObserver((records) => {
+    // Positioning the overlay must not schedule another position update indefinitely.
+    if (
+      records.some(
+        (record) =>
+          !(record.target instanceof Element) ||
+          !record.target.closest('[data-u90-language-cue], style[data-u90-language-hints]'),
+      )
+    )
+      schedule()
+  })
+  mutations.observe(document.documentElement, {
+    subtree: true,
+    childList: true,
+    characterData: true,
+    attributes: true,
+    attributeFilter: [FIELD_ATTR, RICH_ATTR, 'hidden', 'class', 'style'],
+  })
+  window.addEventListener('resize', schedule)
+  document.addEventListener('scroll', schedule, true)
+
+  return {
+    update(value: unknown) {
+      hints = new Map(
+        (Array.isArray(value) ? value : []).flatMap((item) =>
+          item &&
+          typeof item.field === 'string' &&
+          (item.kind === 'fallback' || item.kind === 'empty')
+            ? [[item.field, item.kind as HintKind]]
+            : [],
+        ),
+      )
+      // Clear obsolete hints immediately; the observer handles the following React commit.
+      if (frame) cancelAnimationFrame(frame)
+      sync()
+    },
+    dispose() {
+      disposed = true
+      mutations.disconnect()
+      sizes.disconnect()
+      window.removeEventListener('resize', schedule)
+      document.removeEventListener('scroll', schedule, true)
+      if (frame) cancelAnimationFrame(frame)
+      for (const element of marked.keys()) remove(element)
+      style?.remove()
+    },
+  }
+}

package/src/legacy/languages/fields.ts

@@ -0,0 +1,131 @@
+import type { EditorBlock, EditorField } from '../contract'
+import { sourceFingerprint } from './hash'
+import { STABLE_ID_KEY, type ContentNode, type LocalizableField } from './types'
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const childrenOf = (field: EditorField, blocks: EditorBlock[]): EditorBlock[] => {
+  if (field.blocks) return field.blocks
+  const bySlug = new Map(blocks.map((block) => [block.slug, block]))
+  return (field.childBlocks ?? []).flatMap((slug) => {
+    const block = bySlug.get(slug)
+    return block ? [block] : []
+  })
+}
+
+const eligible = (field: EditorField, parent?: EditorField): boolean => {
+  if (field.localized === false) return false
+  if (field.type !== 'text' && field.type !== 'textarea' && field.type !== 'richText') return false
+  if (parent?.element === 'button') return field.name === 'label'
+  if (parent?.element === 'sentence') return field.name === 'label' || field.name === 'text'
+  return true
+}
+
+const requireIdentity = (value: ContentNode, path: string): string => {
+  const identity = value[STABLE_ID_KEY]
+  if (typeof identity !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(identity)) {
+    throw new Error(`${path} has no valid ${STABLE_ID_KEY}; run ensureStableIdentities first`)
+  }
+  return identity
+}
+
+const segment = (kind: 'field' | 'item' | 'section', value: string): string =>
+  `${kind}:${encodeURIComponent(value)}`
+
+type Walk = {
+  address: string[]
+  fields: EditorField[]
+  parent?: EditorField
+  positional: string[]
+  value: ContentNode
+}
+
+const collect = (walk: Walk, blocks: EditorBlock[], output: LocalizableField[]): void => {
+  for (const field of walk.fields) {
+    const value = walk.value[field.name]
+    const address = [...walk.address, segment('field', field.name)]
+    const positional = [...walk.positional, field.name]
+    if (eligible(field, walk.parent)) {
+      output.push({
+        address: address.join('/'),
+        field,
+        positionalPath: positional.join('.'),
+        sourceHash: sourceFingerprint(value),
+        value,
+      })
+      continue
+    }
+    if (field.type === 'group' && isRecord(value)) {
+      collect(
+        { address, fields: field.fields ?? [], parent: field, positional, value: value as ContentNode },
+        blocks,
+        output,
+      )
+      continue
+    }
+    if ((field.type === 'array' || field.type === 'blocks') && Array.isArray(value)) {
+      const childBlocks = field.type === 'blocks' ? childrenOf(field, blocks) : []
+      value.forEach((item, index) => {
+        if (!isRecord(item)) return
+        const identity = requireIdentity(item as ContentNode, positional.concat(String(index)).join('.'))
+        const fields =
+          field.type === 'array'
+            ? field.fields ?? []
+            : childBlocks.find((block) => block.slug === item.blockType)?.fields ?? []
+        collect(
+          {
+            address: [...address, segment('item', identity)],
+            fields,
+            positional: [...positional, String(index)],
+            value: item as ContentNode,
+          },
+          blocks,
+          output,
+        )
+      })
+    }
+  }
+}
+
+/** Enumerate source values using stable addresses; fallbacks are never materialized here. */
+export const localizableFields = ({
+  blocks,
+  content,
+}: {
+  blocks: EditorBlock[]
+  content: unknown[]
+}): LocalizableField[] => {
+  const output: LocalizableField[] = []
+  content.forEach((section, index) => {
+    if (!isRecord(section)) return
+    const node = section as ContentNode
+    const identity = requireIdentity(node, String(index))
+    const block = blocks.find((candidate) => candidate.slug === node.blockType)
+    if (!block) return
+    collect(
+      {
+        address: [segment('section', identity)],
+        fields: block.fields,
+        positional: [String(index)],
+        value: node,
+      },
+      blocks,
+      output,
+    )
+  })
+  return output
+}
+
+/** Map a transient Canvas positional path to its durable translation address. */
+export const stableAddressFor = ({
+  blocks,
+  content,
+  positionalPath,
+}: {
+  blocks: EditorBlock[]
+  content: unknown[]
+  positionalPath: string
+}): null | string =>
+  localizableFields({ blocks, content }).find((field) => field.positionalPath === positionalPath)
+    ?.address ?? null

package/src/legacy/languages/hash.ts

@@ -0,0 +1,98 @@
+const canonicalValue = (value: unknown, seen: Set<object>): string => {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : JSON.stringify(String(value))
+  if (typeof value !== 'object') return JSON.stringify(String(value))
+  if (seen.has(value)) throw new TypeError('Cannot fingerprint a cyclic source value')
+  seen.add(value)
+  const result = Array.isArray(value)
+    ? `[${value.map((item) => canonicalValue(item, seen)).join(',')}]`
+    : `{${Object.keys(value as Record<string, unknown>)
+        .sort()
+        .map(
+          (key) =>
+            `${JSON.stringify(key)}:${canonicalValue((value as Record<string, unknown>)[key], seen)}`,
+        )
+        .join(',')}}`
+  seen.delete(value)
+  return result
+}
+
+const CONSTANTS = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4,
+  0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe,
+  0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f,
+  0x4a7484aa, 0x5cb0a9dc, 0x76f988da, 0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
+  0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc,
+  0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070, 0x19a4c116,
+  0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7,
+  0xc67178f2,
+] as const
+
+const rotateRight = (value: number, bits: number): number =>
+  (value >>> bits) | (value << (32 - bits))
+
+/** A small runtime-neutral SHA-256 implementation keeps this shared domain browser-safe. */
+const sha256 = (input: string): string => {
+  const bytes = [...new TextEncoder().encode(input)]
+  const bitLength = bytes.length * 8
+  bytes.push(0x80)
+  while (bytes.length % 64 !== 56) bytes.push(0)
+  const high = Math.floor(bitLength / 0x1_0000_0000)
+  const low = bitLength >>> 0
+  for (let shift = 24; shift >= 0; shift -= 8) bytes.push((high >>> shift) & 0xff)
+  for (let shift = 24; shift >= 0; shift -= 8) bytes.push((low >>> shift) & 0xff)
+
+  const hash = [
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
+    0x5be0cd19,
+  ]
+  const words = new Array<number>(64)
+  for (let offset = 0; offset < bytes.length; offset += 64) {
+    for (let index = 0; index < 16; index += 1) {
+      const at = offset + index * 4
+      words[index] =
+        ((bytes[at]! << 24) | (bytes[at + 1]! << 16) | (bytes[at + 2]! << 8) | bytes[at + 3]!) >>> 0
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const before = words[index - 15]!
+      const far = words[index - 2]!
+      const s0 = rotateRight(before, 7) ^ rotateRight(before, 18) ^ (before >>> 3)
+      const s1 = rotateRight(far, 17) ^ rotateRight(far, 19) ^ (far >>> 10)
+      words[index] = (words[index - 16]! + s0 + words[index - 7]! + s1) >>> 0
+    }
+    let [a, b, c, d, e, f, g, h] = hash
+    for (let index = 0; index < 64; index += 1) {
+      const upper = rotateRight(e!, 6) ^ rotateRight(e!, 11) ^ rotateRight(e!, 25)
+      const choose = (e! & f!) ^ (~e! & g!)
+      const t1 = (h! + upper + choose + CONSTANTS[index]! + words[index]!) >>> 0
+      const lower = rotateRight(a!, 2) ^ rotateRight(a!, 13) ^ rotateRight(a!, 22)
+      const majority = (a! & b!) ^ (a! & c!) ^ (b! & c!)
+      const t2 = (lower + majority) >>> 0
+      h = g
+      g = f
+      f = e
+      e = (d! + t1) >>> 0
+      d = c
+      c = b
+      b = a
+      a = (t1 + t2) >>> 0
+    }
+    hash[0] = (hash[0]! + a!) >>> 0
+    hash[1] = (hash[1]! + b!) >>> 0
+    hash[2] = (hash[2]! + c!) >>> 0
+    hash[3] = (hash[3]! + d!) >>> 0
+    hash[4] = (hash[4]! + e!) >>> 0
+    hash[5] = (hash[5]! + f!) >>> 0
+    hash[6] = (hash[6]! + g!) >>> 0
+    hash[7] = (hash[7]! + h!) >>> 0
+  }
+  return hash.map((word) => word.toString(16).padStart(8, '0')).join('')
+}
+
+export const sourceFingerprint = (value: unknown): string =>
+  sha256(canonicalValue(value, new Set()))

package/src/legacy/languages/health.ts

@@ -0,0 +1,97 @@
+import { isSemanticallyEmpty } from './resolution'
+import type {
+  LanguageFieldHealth,
+  LanguageHealth,
+  LocalizableField,
+  TranslationDocument,
+  TranslationPatch,
+  TranslationPatchResult,
+} from './types'
+
+/** Evaluate stored target values only. Rendering fallbacks never count as translations. */
+export const evaluateLanguageHealth = ({
+  fields,
+  translation,
+}: {
+  fields: LocalizableField[]
+  translation: Pick<TranslationDocument, 'fields'>
+}): LanguageHealth => {
+  const health: LanguageHealth = {
+    fields: [],
+    keptOriginal: 0,
+    missingOptional: 0,
+    missingRequired: 0,
+    missingSource: 0,
+    needsReview: 0,
+    ready: true,
+    sourceChanged: 0,
+    total: 0,
+    translated: 0,
+  }
+  for (const source of fields) {
+    const sourceEmpty = isSemanticallyEmpty(source.value, source.field.type)
+    if (sourceEmpty && !source.field.required) continue
+    health.total += 1
+    const target = translation.fields[source.address]
+    const targetEmpty = !target || isSemanticallyEmpty(target.value, source.field.type)
+    const sourceChanged = Boolean(target && target.sourceHash !== source.sourceHash)
+    const kept = Boolean(target?.keepOriginal && !sourceChanged)
+    const missingTranslation = targetEmpty && !kept
+    const missingRequired = Boolean(source.field.required && missingTranslation)
+    const missingSource = Boolean(source.field.required && sourceEmpty)
+    const needsReview = target?.needsReview === true
+
+    if (!targetEmpty) health.translated += 1
+    if (kept) health.keptOriginal += 1
+    if (missingRequired) health.missingRequired += 1
+    if (missingTranslation && !source.field.required) health.missingOptional += 1
+    if (missingSource) health.missingSource += 1
+    if (needsReview) health.needsReview += 1
+    if (sourceChanged) health.sourceChanged += 1
+
+    const fieldHealth: LanguageFieldHealth = {
+      address: source.address,
+      missingRequired,
+      missingSource,
+      missingTranslation,
+      needsReview,
+      sourceChanged,
+    }
+    health.fields.push(fieldHealth)
+    if (Object.values(fieldHealth).some((flag) => flag === true)) health.ready = false
+  }
+  return health
+}
+
+/** Apply one field write only when the caller's structure/translation revision is current. */
+export const applyTranslationPatch = (
+  translation: TranslationDocument,
+  patch: TranslationPatch,
+): TranslationPatchResult => {
+  if (!Number.isSafeInteger(patch.expectedFieldRevision) || patch.expectedFieldRevision < 0) {
+    return { ok: false, problem: 'Expected field revision must be a non-negative safe integer' }
+  }
+  if (
+    !Number.isSafeInteger(patch.expectedStructureRevision) ||
+    patch.expectedStructureRevision < 0
+  ) {
+    return { ok: false, problem: 'Expected structure revision must be a non-negative safe integer' }
+  }
+  if (translation.structureRevision !== patch.expectedStructureRevision) {
+    return {
+      ok: false,
+      problem: `Stale structure revision: expected ${patch.expectedStructureRevision}, current ${translation.structureRevision}`,
+    }
+  }
+  if (patch.address.trim().length === 0) return { ok: false, problem: 'Translation address is required' }
+  const currentRevision = translation.fields[patch.address]?.revision ?? 0
+  if (currentRevision !== patch.expectedFieldRevision) {
+    return {
+      ok: false,
+      problem: `Stale field revision: expected ${patch.expectedFieldRevision}, current ${currentRevision}`,
+    }
+  }
+  const fields = { ...translation.fields }
+  fields[patch.address] = { ...patch.field, revision: currentRevision + 1 }
+  return { ok: true, translation: { fields, structureRevision: translation.structureRevision } }
+}