flint-plugin-api 0.6.0

package/README.md

@@ -0,0 +1,45 @@
+# Writing Flint plugins
+
+A plugin is a folder inside a vault's `.flint/plugins/` directory:
+
+```
+.flint/plugins/my-plugin/
+├─ manifest.json
+├─ main.js
+└─ styles.css   (optional)
+```
+
+`manifest.json`:
+
+```json
+{
+  "id": "my-plugin",
+  "name": "My plugin",
+  "version": "1.0.0",
+  "author": "You",
+  "description": "What it does.",
+  "license": "AGPL-3.0-or-later"
+}
+```
+
+The `license` is an [SPDX expression](https://spdx.org/licenses/). Flint is AGPL-3.0-or-later, so plugins must use a compatible free license; Flint warns before enabling a plugin that doesn't.
+
+`main.js` is an ES module whose default export receives the Flint API:
+
+```js
+export default function activate(flint) {
+  flint.commands.register({
+    id: 'hello',
+    name: 'Say hello',
+    run: () => flint.ui.notice('Hello from my plugin'),
+  })
+}
+```
+
+Everything registered through the API (commands, editor extensions, sidebar tabs, listeners) is removed automatically when the plugin is turned off. `activate` may also return a cleanup function for anything else.
+
+Use `flint.codemirror` instead of bundling your own copy of CodeMirror; two copies in the same editor break it.
+
+For type hints, copy [`index.d.ts`](index.d.ts) next to your plugin and annotate `activate` with `/** @type {import('./index').ActivatePlugin} */`. See it for the full API and [`examples/word-count`](../examples/word-count) for a working plugin. To try it, copy the folder into your vault's `.flint/plugins/` and turn it on in Settings.
+
+Plugins run inside Flint with the same access as the app itself. Only turn on plugins you trust.

package/index.d.ts

@@ -0,0 +1,122 @@
+import type * as autocomplete from '@codemirror/autocomplete'
+import type * as language from '@codemirror/language'
+import type * as state from '@codemirror/state'
+import type * as view from '@codemirror/view'
+
+export type Disposer = () => void
+
+export interface PluginCommand {
+  /** Unique within the plugin; Flint prefixes it with the plugin id. */
+  id: string
+  name: string
+  /** For example `Mod+Shift+K`. `Mod` is Ctrl, or ⌘ on macOS. */
+  hotkey?: string
+  /** Replaces `hotkey` on macOS, where `Ctrl` is the Control key. */
+  macHotkey?: string
+  run: () => unknown
+  isAvailable?: () => boolean
+}
+
+export interface SidebarTab {
+  /** Unique within the plugin. */
+  id: string
+  name: string
+  /** Renders into `element`; the returned function runs when the tab is removed. */
+  render: (element: HTMLElement) => Disposer | undefined
+}
+
+export interface NoteEntry {
+  path: string
+  kind: 'file' | 'folder' | 'attachment'
+}
+
+export interface MarkdownSection {
+  /** First source line of the block, 0-based. */
+  lineStart: number
+  /** Line after the block's last line. */
+  lineEnd: number
+}
+
+/**
+ * Where rendered Markdown came from. Buttons, inputs, links, `summary` and elements with a
+ * `data-interactive` attribute receive clicks in live preview instead of moving the cursor.
+ */
+export interface MarkdownContext {
+  /** The note the content was rendered from. */
+  sourcePath: string
+  /** The source lines of the innermost block containing `element`. */
+  sectionOf(element: HTMLElement): MarkdownSection | null
+  /** Replaces source lines of the note (an empty `text` removes them); open editors update and it is saved. */
+  replaceLines(lineStart: number, lineEnd: number, text: string): Promise<void>
+}
+
+export type PostProcessor = (element: HTMLElement, context: MarkdownContext) => unknown
+
+export type CodeBlockProcessor = (
+  source: string,
+  element: HTMLElement,
+  context: MarkdownContext,
+) => unknown
+
+export interface FlintApi {
+  /** The id from the plugin's manifest. */
+  readonly pluginId: string
+
+  commands: {
+    register(command: PluginCommand): Disposer
+  }
+
+  editor: {
+    /** Adds a CodeMirror extension to every editor. */
+    registerExtension(extension: state.Extension): Disposer
+    /** The editor showing the active note, if any. */
+    activeView(): view.EditorView | null
+    /** Replaces the selection in the active editor, or inserts at the cursor. */
+    replaceSelection(text: string): void
+  }
+
+  vault: {
+    list(): Promise<NoteEntry[]>
+    read(path: string): Promise<string>
+    write(path: string, contents: string): Promise<void>
+    create(path: string): Promise<void>
+    /** Called with vault-relative paths whenever files change. */
+    onChange(listener: (paths: string[]) => void): Disposer
+  }
+
+  workspace: {
+    activeNote(): string | null
+    openNote(path: string): Promise<void>
+    onNoteOpen(listener: (path: string | null) => void): Disposer
+  }
+
+  ui: {
+    notice(message: string): void
+    registerSidebarTab(tab: SidebarTab): Disposer
+  }
+
+  markdown: {
+    /** Runs on every rendered block of Markdown: the reading view and embedded notes. */
+    registerPostProcessor(processor: PostProcessor): Disposer
+    /** Renders fenced code blocks of `language` into `element` instead of showing the code. */
+    registerCodeBlockProcessor(language: string, processor: CodeBlockProcessor): Disposer
+  }
+
+  storage: {
+    load<T = unknown>(): Promise<T | null>
+    save(data: unknown): Promise<void>
+  }
+
+  /** Flint's own CodeMirror modules. Use these instead of bundling CodeMirror. */
+  codemirror: {
+    state: typeof state
+    view: typeof view
+    language: typeof language
+    autocomplete: typeof autocomplete
+  }
+}
+
+/** The default export of a plugin's `main.js`. It may return a cleanup function. */
+export type ActivatePlugin = (
+  flint: FlintApi,
+) => Disposer | undefined | Promise<Disposer | undefined>

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "flint-plugin-api",
+  "version": "0.6.0",
+  "description": "TypeScript types for writing Flint plugins",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cucsijuan/flint.git",
+    "directory": "plugin-api"
+  },
+  "homepage": "https://github.com/cucsijuan/flint/tree/main/plugin-api#readme",
+  "keywords": [
+    "flint",
+    "plugin",
+    "markdown",
+    "notes"
+  ],
+  "types": "index.d.ts",
+  "files": [
+    "index.d.ts"
+  ],
+  "dependencies": {
+    "@codemirror/autocomplete": "^6.20.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.6",
+    "@codemirror/view": "^6.43.13"
+  }
+}