SPB Git

Repository Public

FEATURES.md 11.9 KB

# SPNotesFeatures — hosting the feature screens

SPNotesFeatures is the SwiftUI library of the SP Note Next Generation screens shared by SP Notes macOS (15+) and iOS / iPadOS (18+). It depends on SPNotesDesign, SPNotesSync (repositories), SPNotesStore, SPNotesAPI, SPNotesDocument; it uses SwiftUI, Swift Charts, PDFKit, AVFoundation and CryptoKit — no WebKit, no JavaScriptCore (a test greps the sources). It is not re-exported by the SPNotesCore umbrella.

Product Link it in Contains
SPNotesFeatures the app targets every screen, view model and block view below
SPNotesFeaturesCatalog debug / test targets only (it links the fake backend) FeatureCatalogView, FeatureWorld, FeatureSamples
swift
import SPNotesFeatures

TasksScreen(repositories: repos, router: router)          // the screen creates and owns its model
TasksScreen(model: tasksModel)                            // or the app owns the model (state restoration, tests)

# 1. The contract with the host

# 1.1 FeatureRouter

swift
@MainActor public protocol FeatureRouter: AnyObject {
    func openPage(id: String, blockId: String?)   // scroll to and flash the node whose `id` attr is blockId
    func openDatabase(id: String)                 // database id or host page id
    func openCanvas(pageId: String)
    func openURL(_ url: URL)
    func presentError(_ error: Error)             // rare: the screens show their own banners
}

The models hold the router weakly: the app keeps it alive (one per window / scene). FeatureRouterRecorder is a recording implementation for previews and tests. A screen never navigates outside its own surface by itself.

# 1.2 Layout

Every screen has two real designs. iOS follows the horizontal size class; macOS switches to compact under 560 pt of width. Force one with .featureSizeClass(.compact | .regular). On compact, details open as sheets: host the screen where a sheet can be presented. On regular they are side inspectors. Screens draw their own title row; put them in your navigation container without a second large title.

# 1.3 Loading, offline, errors

Each model exposes phase: LoadPhase, freshness: Freshness? and actionFailure: FeatureFailure?, and starts loading in .task when phase == .idle. A cached read model is shown with « Copie de l'appareil · Mis à jour … »; offline is a calm banner, never an endless spinner; an online-only write that fails changes nothing locally and nothing is queued (as the repositories do). Tasks and canvases are editable offline.

# 1.4 AI

Anything produced by a model is inside FeatureAICard / next to NVAIBadge. Nothing paid is requested without a user action (ask, brief summary, synopsis, Smart Inbox suggestions, AI insights, semantic search, transcription), and nothing is applied without one.

# 1.5 Strings

French is the source (L("…"), the key is the text). English: Localization/en/*.json, compiled into Sources/SPNotesFeatures/Resources/Localizable.xcstrings by python3 Scripts/build-string-catalog.py (--check in the tests). SPN_FEATURES_LANG=fr|en forces a language; test runners default to French.

# 2. Screens

Screen Entry point Host supplies / notes
TasksScreen (repositories:router:pageId:) pageId = tasks of one page. Public TaskDetailView. Offline-first.
InboxScreen (repositories:router:) Public InboxDetailView. Smart Inbox suggestions are an explicit, paid request.
DatabaseScreen (repositories:databaseId:router:) Database id or host page id. Public DatabaseRowEditor, DatabaseBuilderView.
UnifiedSearchScreen (repositories:router:) Semantic search only on the explicit toggle + submit.
GraphScreen (repositories:router:view:pageId:) view = a GraphView constant; local / project need pageId. iOS: the relation form is a sheet.
ConstellationScreen (repositories:router:) Server projection when /api/meta lists constellation, else a labelled local layout.
TimelineScreen (repositories:router:scope:) `scope: .workspace
KnowledgeHealthScreen (repositories:router:)
DailyBriefScreen (repositories:router:) A summary the server already stored is shown (AI card); a new one only on tap.
SemanticZoomControl + PageOutlineView SemanticZoomControl(level:onChange:), PageOutlineView(model:) { editor } Level 3 is the host's editor view; the host keeps the scroll anchor.
AskScreen (repositories:router:context:) AskContext(pageId:pageTitle:projectId:projectTitle:selection:selectionBlockId:) enables the page / project / selection scopes.
ModelPickerView (repositories:selectedId:onSelect:) Write onSelect: explicitly (the init ends with defaulted closures). "Auto" = nil.
ResearchScreen (repositories:router:scope:) `.library
CanvasScreen (repositories:pageId:router:attachments:drawingEditor:) See §3 for the loader and the PencilKit hook.
CommandCenterView (registry:onDismiss:) See §4.

Block detail views (atom sheets / inspectors of both editors). Each takes the typed block of SPNotesDocument and returns the edited block through a callback; the editor writes the node and saves the page — the views never do.

View Entry point Notes
MermaidBlockView (block:imageLoader:onChange:) Preview shown only when previewHash == sha256(code); otherwise the source and « rendu à mettre à jour depuis le Web ».
DrawingBlockViewer, InkEditorView see MediaBlocks/InkViews.swift Mouse / trackpad / touch editor producing spn-ink-1; InkDrawingExport.store uploads ink + preview and clears pk. iOS apps plug PencilKit instead.
ChartBlockView (block:repositories:onChange:) Live data when source is set and repositories is given; the node's snapshot is rewritten only on « Mettre à jour l'instantané ».
QueryViewBlockView (repositories:router:block:hostPageId:) Resolved through POST /api/query; cached result offline.
BlockRefView (repositories:router:block:) Rendered from the local copy of the source page; « Référence introuvable » when missing.
CitationPickerView (repositories:pageId:current:onPick:) Returns CitationChoice(refId, label, locator) → attrs of the citation node.
BibliographyView (repositories:router:citedIds:style:title:) Pass document.citedReferences(). APA only; another style is shown in APA with a notice.
PDFBlockView see MediaBlocks/PDFBlockView.swift PDFKit. Annotations ⇄ normalised rects (PDFPageGeometry, tested on rotated pages). page is committed on disappear.
RunCodeBlockView (block:onChange:) Code + last output; says that execution happens on the web.
AudioBlockView AudioBlockView(model: AudioBlockModel(repositories:block:pageId:files:…)) See §5.

# 3. Attachments and the PencilKit hook

Files belong to the host (sync engine + file locator). Give the views a loader:

swift
let loader = FeatureAttachmentLoader.standard(repositories: repos, files: appFileLocator)
CanvasScreen(repositories: repos, pageId: id, router: router, attachments: loader, drawingEditor: pencilEditor)
PDFBlockView(…).featureAttachmentLoader(loader)        // also DrawingBlockViewer

MermaidBlockView takes a BlockImageLoader closure (attachment id → Data) and the audio view an AudioFileProvider (attachment id → local file URL): wrap the same locator. Uploads are online-only.

drawingEditor: CanvasDrawingEditorProvider? — a closure receiving a CanvasDrawingEditRequest (node, ink attachment, current InkDocument, size) and returning a CanvasDrawingEditResult?. The iOS app presents its PencilKit editor there and returns the new ink; without it the built-in InkEditorView opens.

# 4. Command center

swift
let registry = CommandRegistry()                                   // one per app
let token = registry.register(owner: "editor", [FeatureCommand(id: "page.new", title: "Nouvelle page", section: "Pages", action: { … })])
registry.unregister(token)                                         // or unregister(owner:)
CommandCenterView(registry: registry, onDismiss: { showPalette = false })

The app owns the shortcut (⌘K) and the presentation (overlay / sheet / panel). The matcher is a port of the web palette's scoring, diacritic-insensitive. FeatureCommands.standard(router:…) registers only what Features can do by itself; recents persist through UserDefaultsCommandRecents.

# 5. Info.plist usage strings and entitlements

Needed by Key Platforms
AudioBlockView recording NSMicrophoneUsageDescription iOS, macOS
AudioBlockView recording entitlement com.apple.security.device.audio-input (App Sandbox / Hardened Runtime) macOS

Nothing else: the Speech framework is not used (transcription is the server's, through AudioRepository), no background-audio mode is requested (recording stops with the view), PDFKit / Charts need no key. The audio view shows an explained state when the permission is denied.

  • swift test --filter SPNotesFeaturesTests — view-model tests of every screen over FakeBackend (FeatureWorld), geometry tests, and hosted renders written to /tmp/spnote-next/shots-native/<screen>-<light|dark>-<compact|regular>.png (SPN_SHOTS_DIR overrides). The renders use an off-screen NSHostingView (never a visible window); Scripts/features-contact-sheet.py builds contact sheets.
  • Live smoke (integration server only, never production): SPN_LIVE_URL=http://localhost:8486 SPN_LIVE_TOKEN=… swift test --filter LiveFeatures.
  • FeatureCatalogView() (product SPNotesFeaturesCatalog) lists every screen over the fake backend with switches for offline, compact and dark. Host it in a DEBUG-only window / route; do not ship it.
  • Scripts/generate-model-logos.sh regenerates Resources/ModelLogos.xcassets from the web public/model-logos/ (simple-icons, CC0; marks remain trademarks of their owners).

# 7. Known limits (2.0.0)

Verified by model tests, hosted renders and an iOS Simulator compile only: no screen was driven by real pointer, touch or keyboard input, and nothing was run on a device.

  • Graph: no concept create / rename / delete UI; no scroll-wheel zoom on macOS (buttons, pinch, drag).
  • Database: board cards move through a menu (no drag and drop); gallery has no cover images; relation / file / AI cells are read-only; no column resize / reorder, no property rename / delete; a draft filter preview queries the API directly without viewId.
  • Search: tag and folder filters exist in the model, not in the UI.
  • Ask: stopping mid-stream is implemented but not covered by a test; citations of stored conversations are numbered only when the server stored n.
  • Research: experiments and papers are read-only; no reference extracts, PDF attachment or LaTeX zip.
  • Canvas: math cards show the LaTeX source; no snap guides, align / distribute or copy / paste; a viewport change alone is not saved (as on the web).
  • PDF: the interactive PDFView (live selection, ink) has not been exercised on screen; the renders use a static page picture.
  • Bibliography: APA only. Constellation: the server route exists only on servers that list the feature.
  • Time machine: page and project scopes only (the API has no workspace scope).
Files main
Menu

Theme