@codingfactory/socialkit-vue 0.1.0

package/src/plugins/terminology/index.ts

@@ -0,0 +1,114 @@
+import type { App, Plugin } from 'vue'
+import type { TerminologyOptions, TermsBundle } from './types.js'
+import { makeTermHelpers } from './terms.js'
+import { inject, ref } from 'vue'
+
+const termsBundle: TermsBundle = {}
+let termHelpers: ReturnType<typeof makeTermHelpers> | null = null
+const termsVersion = ref(0)
+
+function ensureTermHelpers(): ReturnType<typeof makeTermHelpers> {
+  if (termHelpers !== null) {
+    return termHelpers
+  }
+
+  termHelpers = makeTermHelpers(termsBundle)
+  return termHelpers
+}
+
+function applyTermsBundle(bundle: TermsBundle): void {
+  const existingKeys = Object.keys(termsBundle)
+  for (const key of existingKeys) {
+    delete termsBundle[key]
+  }
+
+  Object.assign(termsBundle, bundle)
+  termHelpers = makeTermHelpers(termsBundle)
+  termsVersion.value += 1
+}
+
+function touchTermsVersion(): void {
+  void termsVersion.value
+}
+
+function installTerminologyProviders(app: App): void {
+  const termProxy: ReturnType<typeof makeTermHelpers>['term'] = (key, opts) => {
+    touchTermsVersion()
+    return ensureTermHelpers().term(key, opts)
+  }
+
+  const segmentProxy: ReturnType<typeof makeTermHelpers>['segment'] = (key) => {
+    touchTermsVersion()
+    return ensureTermHelpers().segment(key)
+  }
+
+  app.config.globalProperties.$term = termProxy
+  app.config.globalProperties.$segment = segmentProxy
+  app.provide('terms:term', termProxy)
+  app.provide('terms:segment', segmentProxy)
+  app.provide('terms:bundle', termsBundle)
+}
+
+export const TerminologyPlugin: Plugin = {
+  async install(app: App, opts?: Partial<TerminologyOptions>) {
+    const brand = opts?.brand ?? 'default'
+    const locale = opts?.locale ?? 'en'
+    let url = opts?.bundleUrl ?? `/brands/${brand}.${locale}.json`
+    installTerminologyProviders(app)
+
+    const runtimeOrigin = typeof window !== 'undefined' ? window.location.origin : ''
+    const apiBase = (opts?.apiBaseUrl ?? runtimeOrigin).replace(/\/$/, '')
+    const canUseApiFallback = apiBase.length > 0 && url.startsWith('/')
+
+    try {
+      let response = await fetch(url, { cache: 'no-cache' })
+
+      if (canUseApiFallback && (!response.ok || response.headers.get('content-type')?.includes('text/html'))) {
+        // Fall back to the backend origin when the frontend dev server does not serve the brand bundle.
+        url = `${apiBase}${url}`
+        response = await fetch(url, {
+          credentials: 'include',
+          headers: { Accept: 'application/json' }
+        })
+      }
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: Failed to load terminology bundle from ${url}`)
+      }
+
+      const contentType = response.headers.get('content-type')
+      if (!contentType?.includes('application/json')) {
+        throw new Error(`Invalid content-type: ${contentType ?? 'unknown'}. Expected JSON from ${url}`)
+      }
+
+      const data = await response.json()
+      applyTermsBundle(data.terms ?? data)
+    } catch {
+      applyTermsBundle({})
+    }
+  }
+}
+
+/** Composition API helper to access terminology in setup(). */
+export function useTerms(): {
+  term: ReturnType<typeof makeTermHelpers>['term']
+  segment: ReturnType<typeof makeTermHelpers>['segment']
+} {
+  const term = inject<ReturnType<typeof makeTermHelpers>['term']>('terms:term')
+  const segment = inject<ReturnType<typeof makeTermHelpers>['segment']>('terms:segment')
+
+  if (!term || !segment) {
+    const fallback = makeTermHelpers({})
+    return { term: fallback.term, segment: fallback.segment }
+  }
+
+  return { term, segment }
+}
+
+/** Get term helpers outside of a Vue component context (e.g. router). */
+export function getTermHelpers(): ReturnType<typeof makeTermHelpers> {
+  if (!termHelpers) {
+    return makeTermHelpers({})
+  }
+  return termHelpers
+}

package/src/plugins/terminology/terms.ts

@@ -0,0 +1,104 @@
+import type { TermForms, TermsBundle } from './types.js'
+
+type TermCase = 'title' | 'upper' | 'lower'
+type TermForm = 'noun' | 'relation_noun' | 'verb' | 'verb_past' | 'verb_ing'
+type NonNounTermForm = Exclude<TermForm, 'noun' | 'relation_noun'>
+
+export interface TermOptions {
+  form?: TermForm
+  count?: number
+  ui?: string
+  case?: TermCase
+}
+
+export function makeTermHelpers(bundle: TermsBundle): {
+  term: (key: string, opts?: TermOptions) => string
+  segment: (key: string) => string
+} {
+  const emptyNode: TermForms = {}
+
+  const fallbackLabel = (key: string): string => {
+    const lastSegment = key.split('.').pop()
+    return (lastSegment ?? key).replace(/[_-]/g, ' ')
+  }
+
+  const getNode = (key: string): TermForms => bundle[key] ?? emptyNode
+
+  const plural = (one?: string, other?: string, count?: number): string | undefined => {
+    const fallback = one ?? other
+    if (fallback === undefined) {
+      return undefined
+    }
+
+    if (count == null) {
+      return fallback
+    }
+
+    return count === 1 ? (one ?? fallback) : (other ?? fallback)
+  }
+
+  const applyCase = (value: string, casing?: TermCase): string => {
+    if (!value) {
+      return value
+    }
+
+    switch (casing) {
+      case 'upper':
+        return value.toUpperCase()
+      case 'lower':
+        return value.toLowerCase()
+      case 'title':
+        return value.replace(/\b\w/g, (match) => match.toUpperCase())
+      default:
+        return value
+    }
+  }
+
+  const getFormValue = (node: TermForms, form: NonNounTermForm): string | undefined => {
+    switch (form) {
+      case 'verb':
+        return node.verb
+      case 'verb_past':
+        return node.verb_past
+      case 'verb_ing':
+        return node.verb_ing
+      default:
+        return undefined
+    }
+  }
+
+  const term = (key: string, opts: TermOptions = {}): string => {
+    const node = getNode(key)
+
+    if (opts.ui) {
+      return applyCase(node.ui?.[opts.ui] ?? fallbackLabel(key), opts.case)
+    }
+
+    const form: TermForm = opts.form ?? 'noun'
+    if (form === 'noun') {
+      const out = plural(node.noun?.one, node.noun?.other, opts.count) ?? fallbackLabel(key)
+      return applyCase(out, opts.case)
+    }
+
+    if (form === 'relation_noun') {
+      const out = plural(node.relation_noun?.one, node.relation_noun?.other, opts.count) ?? fallbackLabel(key)
+      return applyCase(out, opts.case)
+    }
+
+    const raw = getFormValue(node, form) ?? fallbackLabel(key)
+    return applyCase(raw, opts.case)
+  }
+
+  const segment = (key: string): string => {
+    const node = getNode(key)
+
+    if (node.url_segment) {
+      return node.url_segment
+    }
+
+    const base = node.noun?.other ?? node.noun?.one ?? fallbackLabel(key)
+    return base.toLowerCase().replace(/\s+/g, '-')
+  }
+
+  return { term, segment }
+}

package/src/plugins/terminology/types.ts

@@ -0,0 +1,28 @@
+export interface TermForms {
+  noun?: { one?: string; other?: string }
+  relation_noun?: { one?: string; other?: string }
+  verb?: string
+  verb_past?: string
+  verb_ing?: string
+  url_segment?: string
+  ui?: Record<string, string>
+}
+
+export type TermsBundle = Record<string, TermForms>
+
+export interface TerminologyOptions {
+  brand: string
+  locale: string
+  /** Override the bundle URL (default: `/brands/${brand}.${locale}.json`). */
+  bundleUrl?: string
+  /** API base URL for fallback fetching in development. */
+  apiBaseUrl?: string
+  onVersionMismatch?: (serverVersion: string) => void
+}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $term: (key: string, opts?: Record<string, unknown>) => string
+    $segment: (key: string) => string
+  }
+}