Repository Public
1// SP Notes Core2// File: Sources/SPNotesFeatures/Research/ResearchModel.swift3// Description: View model of the research screen: the references of the library, of a page or of a project (the device's4// copy offline), their detail and editing, adding by DOI (lookup preview, then add), BibTeX import (dry-run5// preview, then confirm), BibTeX and LaTeX exports as files to share, experiments and the papers overview6// (read-only, cached with their date). Every write is online only: offline it fails calmly, nothing is queued.7//8// Author: Simon-Pierre Boucher9// Contact: contact@spboucher.ai10import Foundation11import Observation12import SPNotesAPI13import SPNotesSync1415/// Which references the screen shows.16public enum ResearchScope: Sendable, Equatable {17 /// Everything in the workspace.18 case library19 /// The references attached to a page.20 case page(String)21 /// The references attached to any page of a project or cited in its text (the server's rule; offline only the ones22 /// attached to the project's root page are known).23 case project(String)2425 public var id: String? {26 switch self {27 case .library: return nil28 case .page(let id), .project(let id): return id29 }30 }31}3233/// The editable fields of a reference.34public struct ReferenceForm: Sendable, Equatable {35 public var title = ""36 /// One author per line, "First Last".37 public var authors = ""38 public var year = ""39 public var journal = ""40 public var doi = ""41 public var url = ""42 public var citeKey = ""43 public var entryType = "article"4445 public init() {}4647 public init(_ reference: ResearchReference) {48 title = reference.title49 authors = (reference.authors ?? []).joined(separator: "\n")50 year = reference.year.map(String.init) ?? ""51 journal = reference.journal ?? ""52 doi = reference.doi ?? ""53 url = reference.url ?? ""54 citeKey = reference.citeKey55 entryType = reference.entryType ?? "article"56 }5758 public var authorList: [String] {59 authors.split(whereSeparator: { $0 == "\n" || $0 == ";" }).map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }60 }6162 /// nil when valid; else what to fix.63 public var problem: String? {64 if title.trimmingCharacters(in: .whitespaces).isEmpty { return L("Le titre est obligatoire.") }65 let year = year.trimmingCharacters(in: .whitespaces)66 if !year.isEmpty, Int(year).map({ !(1000...2200).contains($0) }) ?? true { return L("L'année doit être un nombre à quatre chiffres.") }67 return nil68 }6970 static func nonEmpty(_ text: String) -> String? {71 let trimmed = text.trimmingCharacters(in: .whitespaces)72 return trimmed.isEmpty ? nil : trimmed73 }74}7576/// A text export written to a temporary file, ready for `ShareLink`.77public struct ResearchExport: Sendable, Equatable, Identifiable {78 public enum Kind: String, Sendable { case bibtex, latex }79 public var kind: Kind80 public var filename: String81 public var text: String82 public var fileURL: URL83 /// Number of references (BibTeX).84 public var count: Int?85 /// What the LaTeX export found (missing keys, unknown nodes…).86 public var report: LaTeXExportReport?87 public var id: String { fileURL.path }88}8990/// What the side panel (regular) or the sheet (compact) shows.91public enum ResearchPanel: Sendable, Equatable {92 case detail(String)93 case newReference94 case edit(String)95 case doi96 case bibtex97 case export98}99100public enum ResearchTab: String, Sendable, CaseIterable, Identifiable {101 case references, experiments, papers102 public var id: String { rawValue }103 public var title: String {104 switch self {105 case .references: return L("Références")106 case .experiments: return L("Expériences")107 case .papers: return L("Articles")108 }109 }110}111112@Observable @MainActor113public final class ResearchModel {114 public let scope: ResearchScope115 public private(set) var references: [ResearchReference] = []116 public private(set) var experiments: [ResearchExperiment] = []117 public private(set) var papers: [ResearchPaperOverview] = []118 public private(set) var phase: LoadPhase = .idle119 /// Date of the experiments / overview copy (server-computed lists); the references are the synced local copy.120 public private(set) var freshness: Freshness?121 /// True when the last load could not reach the server (writes will fail: controls are disabled).122 public private(set) var isOffline = false123 /// Project scope offline: only the references attached to the root page are known.124 public private(set) var projectListIsPartial = false125 public var actionFailure: FeatureFailure?126 /// Something the server did differently from what was asked (a taken cite key was de-duplicated).127 public private(set) var notice: String?128 public private(set) var isWorking = false129130 public var tab: ResearchTab = .references131 public var searchText = ""132 public var panel: ResearchPanel?133 public var form = ReferenceForm()134135 // DOI136 public var doiText = ""137 public private(set) var doiPreview: DOILookup?138 // BibTeX139 public var bibtexText = ""140 public private(set) var importPreview: BibTeXImportResult?141 public private(set) var importResult: BibTeXImportResult?142 // Exports143 public private(set) var exports: [ResearchExport] = []144 /// The reference just deleted (offer « Annuler »).145 public private(set) var lastDeleted: ResearchReference?146147 private let repositories: NotesRepositories148 private let repository: ResearchRepository149 private weak var router: (any FeatureRouter)?150151 public init(repositories: NotesRepositories, router: (any FeatureRouter)? = nil, scope: ResearchScope = .library, now: @escaping @Sendable () -> Date = { Date() }) {152 self.repositories = repositories153 repository = repositories.research154 self.router = router155 self.scope = scope156 }157158 // MARK: loading159160 public func load() async {161 phase = .loading162 isOffline = false163 projectListIsPartial = false164 do {165 references = try await loadReferences()166 } catch {167 phase = .failed(FeatureFailure(error))168 return169 }170 // Server-computed lists: cached with their date; their failure never hides the references.171 var failure: FeatureFailure?172 do {173 let cached = try await repository.experiments(pageId: scope.id)174 experiments = cached.value175 freshness = Freshness(cached)176 if cached.source == .cache { isOffline = true }177 } catch { failure = FeatureFailure(error) }178 do {179 let cached = try await repository.overview()180 papers = cached.value181 if freshness == nil || cached.source == .cache { freshness = Freshness(cached) }182 if cached.source == .cache { isOffline = true }183 } catch { failure = failure ?? FeatureFailure(error) }184 if let failure, failure.isOffline { isOffline = true }185 if let failure, !failure.isOffline, failure.kind != .unsupported { phase = .failed(failure) } else { phase = .loaded }186 if case .detail(let id) = panel, reference(id: id) == nil { panel = nil }187 }188189 private func loadReferences() async throws -> [ResearchReference] {190 if case .project(let id) = scope {191 do {192 let api = repositories.context.api193 let list = try await repositories.context.online { try await api.references(projectID: id) }194 return list.filter { $0.deletedAt == nil }.sorted { $0.citeKey.localizedCaseInsensitiveCompare($1.citeKey) == .orderedAscending }195 } catch {196 guard RepositoryError.from(error) == .offline else { throw error }197 isOffline = true198 projectListIsPartial = true199 }200 }201 return try await repository.localReferences(pageId: scope.id)202 }203204 public var filtered: [ResearchReference] { references.filter { ReferenceFormatter.matches($0, searchText) } }205 public func reference(id: String) -> ResearchReference? { references.first { $0.id == id } }206 public var selected: ResearchReference? {207 switch panel {208 case .detail(let id), .edit(let id): return reference(id: id)209 default: return nil210 }211 }212213 /// Writes need the server.214 public var canWrite: Bool { !isOffline && !isWorking }215 public var projectId: String? { if case .project(let id) = scope { return id }; return nil }216217 // MARK: detail / edit218219 public func select(_ reference: ResearchReference) { panel = .detail(reference.id) }220221 public func startNew() {222 form = ReferenceForm()223 panel = .newReference224 }225226 public func startEdit(_ reference: ResearchReference) {227 form = ReferenceForm(reference)228 panel = .edit(reference.id)229 }230231 /// Creates or updates from `form`. Returns true when saved.232 @discardableResult233 public func saveForm() async -> Bool {234 if let problem = form.problem {235 actionFailure = FeatureFailure(kind: .other, message: problem)236 return false237 }238 let form = form239 let year = Int(form.year.trimmingCharacters(in: .whitespaces))240 switch panel {241 case .newReference:242 return await perform {243 let draft = ReferenceDraft(pageId: self.scope.id, citeKey: ReferenceForm.nonEmpty(form.citeKey), entryType: form.entryType, title: form.title.trimmingCharacters(in: .whitespaces),244 authors: form.authorList, year: year, journal: ReferenceForm.nonEmpty(form.journal), doi: ReferenceForm.nonEmpty(form.doi), url: ReferenceForm.nonEmpty(form.url))245 let created = try await self.repository.create(draft)246 self.noteKey(asked: draft.citeKey, got: created.citeKey)247 self.upsert(created)248 self.panel = .detail(created.id)249 }250 case .edit(let id):251 return await perform {252 let changes = ReferenceChanges(citeKey: ReferenceForm.nonEmpty(form.citeKey), entryType: form.entryType, title: form.title.trimmingCharacters(in: .whitespaces), authors: form.authorList,253 year: PatchValue(year), journal: PatchValue(ReferenceForm.nonEmpty(form.journal)), doi: PatchValue(ReferenceForm.nonEmpty(form.doi)),254 url: PatchValue(ReferenceForm.nonEmpty(form.url)))255 let updated = try await self.repository.update(id: id, changes)256 self.noteKey(asked: changes.citeKey, got: updated.citeKey)257 self.upsert(updated)258 self.panel = .detail(id)259 }260 default:261 return false262 }263 }264265 /// The server keeps cite keys unique by adding a suffix: say so instead of silently showing another key.266 private func noteKey(asked: String?, got: String) {267 if let asked, asked != got { notice = LF("La clé « %@ » était déjà prise : le serveur a attribué « %@ ».", asked, got) }268 }269270 public func cancelForm() {271 if case .edit(let id) = panel { panel = .detail(id) } else { panel = nil }272 actionFailure = nil273 }274275 @discardableResult276 public func delete(_ reference: ResearchReference) async -> Bool {277 await perform {278 try await self.repository.delete(id: reference.id)279 self.references.removeAll { $0.id == reference.id }280 self.lastDeleted = reference281 if self.selected?.id == reference.id || self.panel == .detail(reference.id) { self.panel = nil }282 }283 }284285 @discardableResult286 public func undoDelete() async -> Bool {287 guard let reference = lastDeleted else { return false }288 return await perform {289 let restored = try await self.repository.restore(id: reference.id)290 self.upsert(restored)291 self.lastDeleted = nil292 }293 }294295 private func upsert(_ reference: ResearchReference) {296 if let index = references.firstIndex(where: { $0.id == reference.id }) { references[index] = reference } else { references.append(reference) }297 references.sort { $0.citeKey.localizedCaseInsensitiveCompare($1.citeKey) == .orderedAscending }298 }299300 // MARK: DOI301302 public func startDOI() {303 doiPreview = nil304 actionFailure = nil305 panel = .doi306 }307308 /// Step 1: asks the registry what the DOI is. Nothing is added.309 @discardableResult310 public func lookupDOI() async -> Bool {311 let doi = Self.normalized(doi: doiText)312 guard !doi.isEmpty else {313 actionFailure = FeatureFailure(kind: .other, message: L("Saisissez un DOI (par exemple 10.2307/2325486)."))314 return false315 }316 doiPreview = nil317 let found = await perform { self.doiPreview = try await self.repository.lookupDOI(doi) }318 if !found, actionFailure?.kind == .notFound { actionFailure?.message = L("Ce DOI est inconnu du registre.") }319 return found320 }321322 /// Step 2: adds the previewed reference.323 @discardableResult324 public func addPreviewedDOI() async -> Bool {325 guard let preview = doiPreview else { return false }326 return await perform {327 let result = try await self.repository.addByDOI(preview.doi, pageId: self.scope.id)328 self.upsert(result.reference)329 self.doiPreview = nil330 self.doiText = ""331 self.panel = .detail(result.reference.id)332 }333 }334335 /// `https://doi.org/10.x/y`, `doi:10.x/y`, spaces → `10.x/y`.336 public nonisolated static func normalized(doi text: String) -> String {337 var doi = text.trimmingCharacters(in: .whitespacesAndNewlines)338 for prefix in ["https://doi.org/", "http://doi.org/", "https://dx.doi.org/", "http://dx.doi.org/", "doi:", "DOI:"] where doi.lowercased().hasPrefix(prefix.lowercased()) {339 doi = String(doi.dropFirst(prefix.count)).trimmingCharacters(in: .whitespaces)340 }341 return doi342 }343344 // MARK: BibTeX import345346 public func startBibTeX() {347 importPreview = nil348 importResult = nil349 actionFailure = nil350 panel = .bibtex351 }352353 /// Step 1: dry run — what would be created, skipped, refused. Nothing is written.354 @discardableResult355 public func previewImport() async -> Bool {356 let text = bibtexText357 guard !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {358 actionFailure = FeatureFailure(kind: .other, message: L("Collez des entrées BibTeX."))359 return false360 }361 importPreview = nil362 importResult = nil363 return await perform { self.importPreview = try await self.repository.importBibTeX(text, pageId: self.scope.id, dryRun: true) }364 }365366 /// Step 2: the real import of the text that was previewed.367 @discardableResult368 public func confirmImport() async -> Bool {369 guard importPreview != nil else { return false }370 let text = bibtexText371 let done = await perform {372 self.importResult = try await self.repository.importBibTeX(text, pageId: self.scope.id, dryRun: false)373 self.importPreview = nil374 self.bibtexText = ""375 }376 if done {377 _ = await repositories.context.engine?.sync() // the created rows arrive by the entity feed378 if let list = try? await loadReferences() { references = list }379 }380 return done381 }382383 /// The preview must be asked again when the text changes.384 public func bibtexTextChanged() {385 importPreview = nil386 }387388 // MARK: exports389390 @discardableResult391 public func exportBibTeX() async -> Bool {392 await perform {393 let export: BibTeXExport394 switch self.scope {395 case .library: export = try await self.repository.exportBibTeX()396 case .page(let id): export = try await self.repository.exportBibTeX(pageId: id)397 case .project(let id): export = try await self.repository.exportBibTeX(projectId: id)398 }399 let name = export.suggestedFilename ?? "references.bib"400 self.add(ResearchExport(kind: .bibtex, filename: name, text: export.text, fileURL: try Self.write(export.text, name: name), count: export.count, report: nil))401 }402 }403404 /// LaTeX of a project (the scope must be a project).405 @discardableResult406 public func exportLaTeX() async -> Bool {407 guard let projectId else {408 actionFailure = FeatureFailure(kind: .other, message: L("L'export LaTeX porte sur un projet."))409 return false410 }411 return await perform {412 let export = try await self.repository.exportLaTeX(projectId: projectId)413 let name = export.suggestedFilename ?? "main.tex"414 self.add(ResearchExport(kind: .latex, filename: name, text: export.tex, fileURL: try Self.write(export.tex, name: name), count: nil, report: export.report))415 }416 }417418 private func add(_ export: ResearchExport) {419 exports.removeAll { $0.kind == export.kind }420 exports.append(export)421 panel = .export422 }423424 /// Writes the text in its own temporary directory under the suggested name (path separators removed).425 nonisolated static func write(_ text: String, name: String) throws -> URL {426 let safe = name.replacingOccurrences(of: "/", with: "-").replacingOccurrences(of: "\\", with: "-")427 let directory = FileManager.default.temporaryDirectory.appendingPathComponent("spn-export-" + UUID().uuidString)428 try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)429 let url = directory.appendingPathComponent(safe.isEmpty || safe.hasPrefix(".") ? "export.txt" : safe)430 try Data(text.utf8).write(to: url, options: .atomic)431 return url432 }433434 // MARK: routing435436 public func openPage(of reference: ResearchReference) {437 guard let pageId = reference.pageId else { return }438 router?.openPage(id: pageId, blockId: nil)439 }440441 public func openLink(of reference: ResearchReference) {442 guard let url = Self.link(reference) else { return }443 router?.openURL(url)444 }445446 public nonisolated static func link(_ reference: ResearchReference) -> URL? {447 if let doi = reference.doi, !doi.isEmpty { return URL(string: doi.lowercased().hasPrefix("http") ? doi : "https://doi.org/" + doi) }448 return reference.url.flatMap(URL.init(string:))449 }450451 public func open(paper: ResearchPaperOverview) { router?.openPage(id: paper.id, blockId: nil) }452 public func open(experiment: ResearchExperiment) {453 guard let pageId = experiment.pageId else { return }454 router?.openPage(id: pageId, blockId: nil)455 }456457 // MARK: plumbing458459 @discardableResult460 private func perform(_ work: @MainActor () async throws -> Void) async -> Bool {461 guard !isWorking else { return false }462 isWorking = true463 actionFailure = nil464 notice = nil465 defer { isWorking = false }466 do {467 try await work()468 isOffline = false469 return true470 } catch {471 let failure = Self.explain(error)472 if failure.kind == .offline { isOffline = true }473 actionFailure = failure474 return false475 }476 }477478 /// The research routes' stable codes in the user's words.479 nonisolated static func explain(_ error: Error) -> FeatureFailure {480 var failure = FeatureFailure(error)481 switch failure.code {482 case "doi_not_found": failure.message = L("Ce DOI est inconnu du registre.")483 case "bad_doi", "invalid_doi": failure.message = L("Ce DOI n'a pas une forme valide.")484 default: break485 }486 return failure487 }488489 // MARK: presentation (pure)490491 public nonisolated static func verification(_ reference: ResearchReference) -> (label: String, isAI: Bool)? {492 switch reference.verified {493 case ReferenceVerification.doiVerified: return (L("Vérifiée par DOI"), false)494 case ReferenceVerification.aiSuggested: return (L("Suggérée par l'IA, à vérifier"), true)495 case ReferenceVerification.user: return (L("Saisie par vous"), false)496 default: return nil497 }498 }499500 public nonisolated static func status(experiment: ResearchExperiment) -> String {501 switch experiment.status {502 case ExperimentStatus.planned: return L("Planifiée")503 case ExperimentStatus.running: return L("En cours")504 case ExperimentStatus.done: return L("Terminée")505 case ExperimentStatus.failed: return L("Échouée")506 default: return experiment.status ?? L("Inconnu")507 }508 }509510 public nonisolated static func status(paper: ResearchPaperOverview) -> String {511 switch paper.status {512 case PaperStatus.planning: return L("Planification")513 case PaperStatus.research: return L("Recherche")514 case PaperStatus.development: return L("Développement")515 case PaperStatus.writing: return L("Rédaction")516 case PaperStatus.submitted: return L("Soumis")517 case PaperStatus.published: return L("Publié")518 default: return paper.status ?? L("Inconnu")519 }520 }521522 /// `p = 1 · q = 1` from a free-form JSON object (params, metrics), keys sorted.523 public nonisolated static func keyValues(_ json: RawJSON?) -> String? {524 guard let json, let object = try? json.decode([String: ReferenceFormatter.Loose].self), !object.isEmpty else { return nil }525 return object.keys.sorted().compactMap { key in object[key]?.text.map { key + " = " + $0 } }.joined(separator: " · ")526 }527}528