more comments; preview in FAQ; fix #142

Author: mProjectsCode

.eslintrc.cjs

@@ -22,8 +22,14 @@ const config = {
 	rules: {
 		'@typescript-eslint/no-explicit-any': ['warn'],
 
-		'@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', destructuredArrayIgnorePattern: '^_' }],
-		'@typescript-eslint/consistent-type-imports': ['error', { prefer: 'type-imports', fixStyle: 'inline-type-imports' }],
+		'@typescript-eslint/no-unused-vars': [
+			'error',
+			{ argsIgnorePattern: '^_', destructuredArrayIgnorePattern: '^_' },
+		],
+		'@typescript-eslint/consistent-type-imports': [
+			'error',
+			{ prefer: 'type-imports', fixStyle: 'inline-type-imports' },
+		],
 
 		'@typescript-eslint/no-confusing-void-expression': ['error', { ignoreArrowShorthand: true }],
 		'@typescript-eslint/restrict-template-expressions': 'off',

.prettierrc.json

@@ -1,7 +1,7 @@
 {
 	"plugins": ["prettier-plugin-svelte"],
 
-	"printWidth": 160,
+	"printWidth": 120,
 	"useTabs": true,
 	"semi": true,
 	"singleQuote": true,

automation/shellUtils.ts

@@ -11,7 +11,10 @@ function exec(c: string): Subprocess<'ignore', 'pipe', 'inherit'> {
 	return Bun.spawn(stringArgv(c));
 }
 
-export async function $(cmd: string, verboseness: Verboseness = Verboseness.NORMAL): Promise<{ stdout: string; stderr: string; exit: number }> {
+export async function $(
+	cmd: string,
+	verboseness: Verboseness = Verboseness.NORMAL,
+): Promise<{ stdout: string; stderr: string; exit: number }> {
 	if (verboseness === Verboseness.NORMAL || verboseness === Verboseness.VERBOSE) {
 		console.log(`\n${CMD_FMT.Bright}running${CMD_FMT.Reset} - ${cmd}\n`);
 	}

exampleVault/View Fields/View Field.md

@@ -1,5 +1,5 @@
 ---
-number1: 12
+number1: 13
 number2: 200
 unit: km
 distance: 12

extraTypes/JsEngine.d.ts

@@ -1,3 +1,5 @@
+// js engine 0.0.7 types
+
 declare module 'jsEngine/ArgumentManager' {
 	import { type CachedMetadata, type TFile } from 'obsidian';
 	export interface ExecutionContext {
@@ -570,7 +572,12 @@ declare module 'jsEngine/JsMDRC' {
 		content: string;
 		ctx: MarkdownPostProcessorContext;
 		jsExecution: JsExecution | undefined;
-		constructor(containerEl: HTMLElement, plugin: JsEnginePlugin, content: string, ctx: MarkdownPostProcessorContext);
+		constructor(
+			containerEl: HTMLElement,
+			plugin: JsEnginePlugin,
+			content: string,
+			ctx: MarkdownPostProcessorContext,
+		);
 		getExecutionFile(): TFile | undefined;
 		buildExecutionContext(): ExecutionContext;
 		tryRun(context: ExecutionContext): Promise<JsExecution>;

src/api/API.ts

@@ -18,15 +18,18 @@ import { Signal } from '../utils/Signal';
 import { type BindTargetScope } from '../metadata/BindTargetScope';
 import { MetaBindTable } from '../metaBindTable/MetaBindTable';
 import { InputFieldFactory } from '../inputFields/InputFieldFactory';
-import { type JsViewFieldDeclaration, type UnvalidatedViewFieldDeclaration, type ViewFieldDeclaration } from '../parsers/viewFieldParser/ViewFieldDeclaration';
+import {
+	type JsViewFieldDeclaration,
+	type UnvalidatedViewFieldDeclaration,
+	type ViewFieldDeclaration,
+} from '../parsers/viewFieldParser/ViewFieldDeclaration';
 import { ViewFieldFactory } from '../viewFields/ViewFieldFactory';
 import { getUUID } from '../utils/Utils';
 
 export class API implements IAPI {
 	public plugin: MetaBindPlugin;
 	public readonly inputField: InputFieldAPI;
 
-	// public inputFieldParser: InputFieldDeclarationParser;
 	public readonly inputFieldParser: InputFieldDeclarationParser;
 	public readonly viewFieldParser: ViewFieldDeclarationParser;
 	public readonly bindTargetParser: BindTargetParser;
@@ -47,32 +50,54 @@ export class API implements IAPI {
 		this.viewFieldFactory = new ViewFieldFactory(this.plugin);
 	}
 
+	/**
+	 * Creates an input field from an unvalidated declaration.
+	 *
+	 * @param unvalidatedDeclaration the unvalidated declaration
+	 * @param renderType whether to render the input field inline or as a block
+	 * @param filePath the file path that the input field is in or an empty string if it is not in a file
+	 * @param containerEl the container to mount the input field to
+	 * @param component component for lifecycle management
+	 * @param scope optional bind target scope
+	 */
 	public createInputField(
 		unvalidatedDeclaration: UnvalidatedInputFieldDeclaration,
 		renderType: RenderChildType,
 		filePath: string,
 		containerEl: HTMLElement,
 		component: Component | MarkdownPostProcessorContext,
+		scope?: BindTargetScope | undefined,
 	): InputFieldMDRC | ExcludedMDRC {
 		if (this.plugin.isFilePathExcluded(filePath)) {
 			return this.createExcludedField(containerEl, filePath, component);
 		}
 
-		const declaration = this.inputFieldParser.validateDeclaration(unvalidatedDeclaration);
+		const declaration = this.inputFieldParser.validateDeclaration(unvalidatedDeclaration, scope);
 
 		const inputField = new InputFieldMDRC(containerEl, renderType, declaration, this.plugin, filePath, getUUID());
 		component.addChild(inputField);
 
 		return inputField;
 	}
 
+	/**
+	 * Creates an input field from a string.
+	 * This will parse the string and create the input field.
+	 *
+	 * @param fullDeclaration the string
+	 * @param renderType whether to render the input field inline or as a block
+	 * @param filePath the file path that the input field is in or an empty string if it is not in a file
+	 * @param containerEl the container to mount the input field to
+	 * @param component component for lifecycle management
+	 * @param scope optional bind target scope
+	 */
 	public createInputFieldFromString(
 		fullDeclaration: string,
 		renderType: RenderChildType,
 		filePath: string,
 		containerEl: HTMLElement,
 		component: Component | MarkdownPostProcessorContext,
-		scope: BindTargetScope | undefined,
+		scope?: BindTargetScope | undefined,
 	): InputFieldMDRC | ExcludedMDRC {
 		if (this.plugin.isFilePathExcluded(filePath)) {
 			return this.createExcludedField(containerEl, filePath, component);
@@ -86,25 +111,47 @@ export class API implements IAPI {
 		return inputField;
 	}
 
+	/**
+	 * Creates a view field from a string.
+	 * This will parse the string and create the view field.
+	 *
+	 * @param fullDeclaration the string
+	 * @param renderType whether to render the view field inline or as a block
+	 * @param filePath the file path that the view field is in or an empty string if it is not in a file
+	 * @param containerEl the container to mount the view field to
+	 * @param component component for lifecycle management
+	 * @param scope optional bind target scope
+	 */
 	public createViewFieldFromString(
 		fullDeclaration: string,
 		renderType: RenderChildType,
 		filePath: string,
 		containerEl: HTMLElement,
 		component: Component | MarkdownPostProcessorContext,
+		scope?: BindTargetScope | undefined,
 	): ViewFieldMDRC | ExcludedMDRC {
 		if (this.plugin.isFilePathExcluded(filePath)) {
 			return this.createExcludedField(containerEl, filePath, component);
 		}
 
-		const declaration: ViewFieldDeclaration = this.viewFieldParser.parseString(fullDeclaration);
+		const declaration: ViewFieldDeclaration = this.viewFieldParser.parseString(fullDeclaration, scope);
 
 		const viewField = new ViewFieldMDRC(containerEl, renderType, declaration, this.plugin, filePath, getUUID());
 		component.addChild(viewField);
 
 		return viewField;
 	}
 
+	/**
+	 * Creates a js view field from a string.
+	 * This will parse the string and create the js view field.
+	 *
+	 * @param fullDeclaration the string containing the header and the code
+	 * @param renderType whether to render the js view field inline or as a block
+	 * @param filePath the file path that the js view field is in or an empty string if it is not in a file
+	 * @param containerEl the container to mount the js view field to
+	 * @param component component for lifecycle management
+	 */
 	public createJsViewFieldFromString(
 		fullDeclaration: string,
 		renderType: RenderChildType,
@@ -124,7 +171,18 @@ export class API implements IAPI {
 		return viewField;
 	}
 
-	public createExcludedField(containerEl: HTMLElement, filePath: string, component: Component | MarkdownPostProcessorContext): ExcludedMDRC {
+	/**
+	 * An excluded field will render a message that the file was excluded in the plugin settings.
+	 *
+	 * @param containerEl the container to mount the field to
+	 * @param filePath the file path that the field should be in or an empty string if it is not in a file
+	 * @param component component for lifecycle management
+	 */
+	public createExcludedField(
+		containerEl: HTMLElement,
+		filePath: string,
+		component: Component | MarkdownPostProcessorContext,
+	): ExcludedMDRC {
 		const excludedField = new ExcludedMDRC(containerEl, RenderChildType.INLINE, this.plugin, filePath, getUUID());
 		component.addChild(excludedField);
 
@@ -138,26 +196,48 @@ export class API implements IAPI {
 	/**
 	 * Registers a signal to a metadata property and returns a callback to unregister.
 	 *
-	 * @param signal
-	 * @param filePath
-	 * @param metadataPath
-	 * @param listenToChildren
+	 * @param signal a signal that will be updated with new metadata
+	 * @param filePath the file path of the metadata to listen to
+	 * @param metadataPath the object path of the metadata to listen to (e.g. ['task', '0', 'completed'])
+	 * @param listenToChildren whether to listen to updates of the children of the metadata path, useful when listening to arrays or objects
+	 * @param onDelete callback that will be called when the metadata becomes unavailable
 	 */
-	public listenToMetadata(signal: Signal<unknown>, filePath: string, metadataPath: string[], listenToChildren: boolean = false): () => void {
+	public listenToMetadata(
+		signal: Signal<unknown>,
+		filePath: string,
+		metadataPath: string[],
+		listenToChildren: boolean = false,
+		onDelete?: () => void,
+	): () => void {
 		const uuid = getUUID();
 
-		const subscription = this.plugin.metadataManager.subscribe(uuid, signal, {
-			filePath: filePath,
-			metadataPath: metadataPath,
-			listenToChildren: listenToChildren,
-			boundToLocalScope: false,
-		});
+		const subscription = this.plugin.metadataManager.subscribe(
+			uuid,
+			signal,
+			{
+				filePath: filePath,
+				metadataPath: metadataPath,
+				listenToChildren: listenToChildren,
+				boundToLocalScope: false,
+			},
+			onDelete ?? ((): void => {}),
+		);
 
 		return () => {
 			subscription.unsubscribe();
 		};
 	}
 
+	/**
+	 * Creates an editable table.
+	 *
+	 * @param containerEl the container to mount the table to
+	 * @param filePath the file path that the table is in or an empty string if it is not in a file
+	 * @param component component for lifecycle management
+	 * @param bindTarget the bind target of the table, it will be available to all input fields in the columns of the table as local scope
+	 * @param tableHead the head of the table
+	 * @param columns the columns of the table
+	 */
 	public createTable(
 		containerEl: HTMLElement,
 		filePath: string,
@@ -166,7 +246,16 @@ export class API implements IAPI {
 		tableHead: string[],
 		columns: (UnvalidatedInputFieldDeclaration | UnvalidatedViewFieldDeclaration)[],
 	): MetaBindTable {
-		const table = new MetaBindTable(containerEl, RenderChildType.INLINE, this.plugin, filePath, getUUID(), bindTarget, tableHead, columns);
+		const table = new MetaBindTable(
+			containerEl,
+			RenderChildType.INLINE,
+			this.plugin,
+			filePath,
+			getUUID(),
+			bindTarget,
+			tableHead,
+			columns,
+		);
 		component.addChild(table);
 
 		return table;

src/api/IAPI.ts

@@ -6,9 +6,21 @@ import { type InputFieldAPI } from './InputFieldAPI';
 
 export interface IAPI {
 	readonly plugin: IPlugin;
+	/*
+	 * The API for creating and modifying input field declarations.
+	 */
 	readonly inputField: InputFieldAPI;
 
+	/**
+	 * Parser for input field declarations.
+	 */
 	readonly inputFieldParser: InputFieldDeclarationParser;
+	/**
+	 * Parser for view field declarations.
+	 */
 	readonly viewFieldParser: ViewFieldDeclarationParser;
+	/**
+	 * Parser for bind target declarations.
+	 */
 	readonly bindTargetParser: BindTargetParser;
 }