@smartcat/sanity-plugin 1.0.0 → 1.0.1

package/src/tool/useTemplates.ts

@@ -0,0 +1,84 @@
+import {useCallback, useEffect, useRef, useState} from 'react'
+import {useClient} from 'sanity'
+import {API_VERSION, SETTINGS_DOC_ID, SETTINGS_TYPE} from '../lib/constants'
+import type {SmartcatTemplate} from '../smartcat/types'
+
+interface SettingsDoc {
+  templates?: SmartcatTemplate[]
+  templatesRequestedAt?: string
+  templatesSyncedAt?: string
+}
+
+const SETTINGS_QUERY = `*[_id == $id][0]{templates, templatesRequestedAt, templatesSyncedAt}`
+
+/**
+ * A request older than this is treated as failed/abandoned, so a fresh refresh
+ * is allowed — self-heals a sync that never completed (e.g. a function error)
+ * instead of wedging the cache in a perpetual "in flight" state.
+ */
+export const REQUEST_STALE_MS = 30_000
+
+/**
+ * A refresh is in flight when a request is newer than the last sync *and* recent
+ * enough that the function could still be working on it.
+ */
+export function isRefreshInFlight(
+  s: {templatesRequestedAt?: string; templatesSyncedAt?: string} | null,
+): boolean {
+  const requested = s?.templatesRequestedAt
+  if (!requested) return false
+  const pending = !s?.templatesSyncedAt || requested > s.templatesSyncedAt
+  if (!pending) return false
+  return Date.now() - Date.parse(requested) < REQUEST_STALE_MS
+}
+
+/**
+ * Reads the cached Smartcat templates from the settings singleton and keeps them
+ * live via `listen()`. `requestRefresh()` bumps the refresh trigger so the
+ * `smartcat-templates` Function re-fetches — skipped while a request is already
+ * in flight (debounce). Returns templates sorted by name.
+ */
+export function useTemplates(): {
+  templates: SmartcatTemplate[]
+  loaded: boolean
+  requestRefresh: () => void
+} {
+  const client = useClient({apiVersion: API_VERSION})
+  const [settings, setSettings] = useState<SettingsDoc | null>(null)
+  const [loaded, setLoaded] = useState(false)
+  const settingsRef = useRef<SettingsDoc | null>(null)
+  settingsRef.current = settings
+
+  useEffect(() => {
+    let cancelled = false
+    const load = () =>
+      client
+        .fetch<SettingsDoc | null>(SETTINGS_QUERY, {id: SETTINGS_DOC_ID})
+        .then((s) => {
+          if (cancelled) return
+          setSettings(s)
+          setLoaded(true)
+        })
+        .catch(() => {})
+    load()
+    const sub = client
+      .listen(SETTINGS_QUERY, {id: SETTINGS_DOC_ID}, {visibility: 'query'})
+      .subscribe({next: load, error: () => {}})
+    return () => {
+      cancelled = true
+      sub.unsubscribe()
+    }
+  }, [client])
+
+  const requestRefresh = useCallback(() => {
+    if (isRefreshInFlight(settingsRef.current)) return
+    client
+      .transaction()
+      .createIfNotExists({_id: SETTINGS_DOC_ID, _type: SETTINGS_TYPE})
+      .patch(SETTINGS_DOC_ID, (p) => p.set({templatesRequestedAt: new Date().toISOString()}))
+      .commit({visibility: 'async'})
+      .catch(() => {})
+  }, [client])
+
+  return {templates: settings?.templates ?? [], loaded, requestRefresh}
+}

package/src/tool/useWorkflowSelection.ts

@@ -0,0 +1,65 @@
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react'
+import {isWorkflowValid} from '../lib/workflow'
+import type {SmartcatTemplate} from '../smartcat/types'
+
+const STORAGE_KEY = 'smartcat:lastWorkflow'
+
+function readLastWorkflow(): string {
+  try {
+    return localStorage.getItem(STORAGE_KEY) ?? ''
+  } catch {
+    return ''
+  }
+}
+
+function writeLastWorkflow(value: string): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, value)
+  } catch {
+    // Ignore unavailable / full storage; selection just won't persist.
+  }
+}
+
+/**
+ * Workflow selection for a create dialog. Starts with **no selection** so the
+ * user must choose, then remembers the last pick per browser (localStorage).
+ *
+ * When `active` (the dialog is open) and the template cache is `loaded`, it
+ * prefills the saved value — but only if it's still valid: a `template:<id>`
+ * whose template no longer exists resets to no selection. It also clears the
+ * selection live if the chosen template later disappears from the cache.
+ */
+export function useWorkflowSelection(
+  active: boolean,
+  templates: SmartcatTemplate[],
+  loaded: boolean,
+): readonly [string, (value: string) => void] {
+  const [workflow, setWorkflowState] = useState('')
+  const initialized = useRef(false)
+  const templateIds = useMemo(() => templates.map((t) => t.id), [templates])
+
+  // Prefill the saved selection once per open, after the cache has loaded.
+  useEffect(() => {
+    if (!active) {
+      initialized.current = false
+      return
+    }
+    if (initialized.current || !loaded) return
+    initialized.current = true
+    const saved = readLastWorkflow()
+    setWorkflowState(isWorkflowValid(saved, templateIds) ? saved : '')
+  }, [active, loaded, templateIds])
+
+  // If the selected template disappears from the cache, drop back to no selection.
+  useEffect(() => {
+    if (!active || !loaded || !workflow) return
+    if (!isWorkflowValid(workflow, templateIds)) setWorkflowState('')
+  }, [active, loaded, workflow, templateIds])
+
+  const setWorkflow = useCallback((value: string) => {
+    setWorkflowState(value)
+    if (value) writeLastWorkflow(value)
+  }, [])
+
+  return [workflow, setWorkflow] as const
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+/**
+ * A language an installation can translate into.
+ * `id` is the locale tag used in Sanity (and document-internationalization).
+ * `smartcatLanguage` is the code Smartcat expects; set it only when the Sanity
+ * tag differs from Smartcat's (e.g. id "PL-PL" → smartcatLanguage "pl"). Defaults to `id`.
+ *
+ * @public
+ */
+export interface SmartcatLanguage {
+  id: string
+  title: string
+  smartcatLanguage?: string
+}
+
+/**
+ * Plugin configuration, supplied by the consuming Studio.
+ *
+ * @public
+ */
+export interface SmartcatPluginConfig {
+  /**
+   * Document types the "Add to translation project" action and status line
+   * appear on. Omit to allow every document type (except the plugin's own
+   * `smartcat.*` types). This affects the Studio UI only — not which linked
+   * documents get pulled into a project (see `rootTypes`).
+   */
+  translatableTypes?: string[]
+
+  /**
+   * Root/standalone document types — the "include linked documents" crawl stops
+   * when it reaches one (they're translated on their own, as peers). Omit to
+   * inherit the explicitly-configured `translatableTypes`, or `[]` if that is
+   * also omitted (i.e. no boundary: pull in every transitively-linked
+   * translatable document).
+   */
+  rootTypes?: string[]
+
+  /**
+   * Source language tag for new projects. Required.
+   */
+  sourceLanguage: string
+
+  /**
+   * Languages content can be translated into. Used to populate
+   * a project's target languages. Optional at this phase.
+   */
+  languages?: SmartcatLanguage[]
+
+  /**
+   * Field name `@sanity/document-internationalization` stores each document's
+   * locale in. Must match that plugin's `languageField` setting. Defaults to
+   * `'language'`.
+   */
+  documentI18nPluginLanguageField?: string
+
+  /**
+   * How `sanity-plugin-internationalized-array` identifies the locale within an
+   * array field's members. `'language'` (default) for v5+; set to `'_key'` to
+   * support v4.x and lower, which keyed members by the language code.
+   */
+  fieldI18nPluginLanguageField?: string
+}
+
+/**
+ * Lifecycle of a translation project. Drives the export/import Functions.
+ *
+ * @public
+ */
+export type TranslationProjectStatus =
+  | 'draft'
+  | 'queued'
+  | 'sent'
+  | 'translating'
+  | 'importing'
+  | 'downloaded'
+  | 'completed'
+  | 'error'