@witchcraft/spellcraft 0.0.1

package/src/core/ShortcutManagerManager.ts

@@ -0,0 +1,380 @@
+import type { DeepPartial } from "@alanscodelog/utils"
+import { debounce } from "@alanscodelog/utils/debounce"
+import { isArray } from "@alanscodelog/utils/isArray"
+import { keys } from "@alanscodelog/utils/keys"
+import { Err, Ok, type Result } from "@alanscodelog/utils/Result"
+import { setReadOnly } from "@alanscodelog/utils/setReadOnly"
+
+import { managerToStorableClone } from "../helpers/managerToStorableClone.js"
+import type { Manager, PickManager } from "../types/index.js"
+
+export class ShortcutManagerManager {
+	storageKeys: {
+		/** Prefix for all keys. */
+		prefix: string
+		/** @default "shortcut-manager:names" */
+		managerNames: string
+		/** @default "shortcut-manager:manager." */
+		managerPrefix: string
+		/** @default "shortcut-manager:active" */
+		activeManager: string
+	}
+
+	readonly managerNames: string[] = []
+
+	readonly managers: Readonly<Record<string, Manager>> = {}
+
+	readonly activeManagerName: string = "default"
+
+	/** A debounced version of the save function. Is already bound to the instance. */
+	debouncedSave: (name: string) => void
+
+	storage: {
+		setItem: (key: string, value: string) => void
+		getItem: (key: string) => string | null
+		removeItem: (key: string) => void
+	}
+
+	/**
+	 * All new managers will be created using this function. It should be capable of taking as little information as `{name}` (when a new manager is created) and returining a full manger.
+	 *
+	 * It's suggested you not do validation here, use the `onParse` hook instead.
+	 *
+	 * If you return an error, `onError` will be called, and no manager will be created.
+	 */
+	createManager: (
+		raw: Partial<Omit<Manager, "options" | "hooks" | "listener" | "state">> & {
+			options: PickManager<"options", "enableShortcuts" | "enableListeners" | "updateStateOnAllEvents">
+		},
+		isNew: boolean
+	) => Manager | Error
+
+	hooks: {
+		/**
+		 * Called on any errors loading/saving/etc, should be used to notify the user.
+		 */
+		onError: (err: Error) => void
+		/**
+		 * Called when a manager is parsed from storage after being sucessfully JSON.parsed.
+		 *
+		 * You can validate the parsed object here so it's in the correct shape to pass to `createManager`.
+		 *
+		 * If you return an error, `onError` will be called and `createManager` will be skipped.
+		 */
+		onParse?: (parsed: object) => undefined | Error
+		/**
+		 * Called when a manager is saved or exported. It's called with the cloned version of the manager that has been stripped of properties that should not be saved (see {@link managerToStorableClone}).
+		 *
+		 * You can delete/add properties here (it will not modify the original manager).
+		 */
+		onSave?: (clone: DeepPartial<Manager>) => void
+		/**
+		 * Called when a manager is exported. Can be used to actually do the export.
+		 */
+		onExport?: (res: object) => void
+		/**
+		 * Called when a manager is set. Can be used to update your state.
+		 */
+		onSetManager?: (name: string, clone: Manager) => void
+		/**
+		 * Called when the manager names are set. Can be used to update your state.
+		 */
+		onSetManagerNames?: (names: string[]) => void
+		/**
+		 * Called when the active manager is set. Can be used to update your state.
+		 */
+		onSetActiveManager?: (name: string) => void
+	}
+
+	constructor(
+		createManager: ShortcutManagerManager["createManager"],
+		hooks: ShortcutManagerManager["hooks"],
+		{
+			storageKeys = {} as any,
+			storage = localStorage
+		}:
+		{
+			storageKeys?: Partial<ShortcutManagerManager["storageKeys"]>
+			storage?: ShortcutManagerManager["storage"]
+		} = {}
+	) {
+		this.createManager = createManager
+		this.hooks = hooks
+		storageKeys.prefix ??= ""
+		storageKeys.managerNames ??= "shortcut-manager:names"
+		storageKeys.managerPrefix ??= "shortcut-manager:manager."
+		storageKeys.activeManager ??= "shortcut-manager:active"
+		if (storageKeys.prefix) {
+			for (const key of keys(storageKeys)) {
+				if (key === "prefix") continue
+				storageKeys[key] = `${storageKeys.prefix}${storageKeys[key]}`
+			}
+		}
+		this.storageKeys = storageKeys as ShortcutManagerManager["storageKeys"]
+		this.storage = storage
+
+		this.debouncedSave = debounce(this.save.bind(this), 500)
+	}
+
+	init(): void {
+		const list = this.storage.getItem(this.storageKeys.managerNames)
+		const active = this.storage.getItem(this.storageKeys.activeManager)
+		this.setManagerNames(list ? JSON.parse(list) : [])
+
+		if (this.managerNames.length > 0) {
+			const res = this.managerNames
+				.map(m => {
+					const r = this.storageReadManager(m, { force: true })
+					this.notifyIfError(r)
+					if (r.isOk) {
+						this.load(r.value)
+					}
+					return r
+				})
+			const ok = res.filter(r => r.isOk)
+			if (ok.length > 0) {
+				this.loadOrCreateDefault()
+			}
+			if (active && this.managerNames.includes(active)) {
+				this.setActiveManager(active)
+			} else {
+				this.setActiveManager(this.managerNames[0]!)
+			}
+		} else {
+			this.loadOrCreateDefault()
+		}
+	}
+
+	setManager(name: string, clone?: any): void {
+		if (clone === undefined) {
+			// @ts-expect-error setting readonly
+			delete this.managers[name]
+		} else {
+			setReadOnly(this.managers, name, clone)
+		}
+		this.hooks.onSetManager?.(name, clone)
+	}
+
+	setManagerNames(names: string[]): void {
+		setReadOnly(this, "managerNames", names)
+		this.hooks.onSetManagerNames?.(names)
+	}
+
+	setActiveManager(name: string): void {
+		setReadOnly(this, "activeManagerName", name)
+		this.storage.setItem(this.storageKeys.activeManager, name)
+		this.hooks.onSetActiveManager?.(name)
+	}
+
+	protected addManager(name: string, clone: any): void {
+		this.setManager(name, clone)
+		if (!this.managerNames.includes(name)) {
+			this.setManagerNames([...this.managerNames, name])
+		}
+	}
+
+	protected removeManager(name: string): void {
+		this.setManager(name, undefined)
+		const index = this.managerNames.indexOf(name)
+		if (index === -1) return
+		this.setManagerNames(this.managerNames.toSpliced(index, 1))
+	}
+
+
+	protected storageSaveManager(name: string, clone: any): void {
+		this.storage.setItem(`${this.storageKeys.managerPrefix}${name}`, JSON.stringify(clone))
+		if (!this.managerNames.includes(name)) {
+			this.managerNames.push(name)
+			this.storage.setItem(
+				this.storageKeys.managerNames,
+				JSON.stringify(this.managerNames)
+			)
+		}
+	}
+
+	protected storageRemoveManager(name: string): void {
+		this.storage.removeItem(`${this.storageKeys.managerPrefix}${name}`)
+		const index = this.managerNames.indexOf(name)
+		if (index > -1) {
+			this.managerNames.splice(index, 1)
+			this.storage.setItem(
+				this.storageKeys.managerNames,
+				JSON.stringify(this.managerNames)
+			)
+		}
+	}
+
+	protected storageReadManager(
+		name: string,
+		{ force = false }: { force?: boolean } = {}
+	): Result<Manager, Error> {
+		const raw = this.storage.getItem(`${this.storageKeys.managerPrefix}${name}`)
+		if (!raw && !force) {
+			const res = Err(new Error(`No manager found by the name of ${name}.`))
+			return this.notifyIfError(res)
+		}
+		const r = this.createManager(
+			!raw && force ? { name } : this.parseJsonManager(raw!).unwrap(),
+			force
+		)
+		if (r instanceof Error) return Err(r)
+		return Ok(r)
+	}
+
+	parseJsonManager(
+		raw: string
+	): Result<any, Error> {
+		if (!raw) {
+			return Err(new Error(`Nothing to parse.`))
+		}
+		try {
+			const parsed = JSON.parse(raw)
+			const res = this.hooks.onParse?.(parsed)
+			if (res instanceof Error) {
+				return this.notifyIfError(Err(res))
+			}
+			if (res === undefined) throw new Error(`onParse must return a value.`)
+			return Ok(res ?? parsed)
+		} catch (e) {
+			return Err(e as Error)
+		}
+	}
+
+	load(
+		manager: Manager,
+		{
+			doActivate = true
+		}: {
+			doActivate?: boolean
+		} = {}
+	): void {
+		this.setManager(manager.name, manager)
+		if (doActivate) {
+			this.setActiveManager(manager.name)
+		}
+		this.save(manager.name)
+	}
+
+	protected loadOrCreateDefault(): void {
+		const r = this.storageReadManager("default", { force: true })
+		this.notifyIfError(r)
+		if (r.isOk) {
+			this.load(r.value)
+		}
+	}
+
+	save(name: string): void {
+		if (!this.managers[name]) {
+			this.notifyIfError(Err(new Error(`Manager ${name} not found`)))
+		}
+		const clone = managerToStorableClone(this.managers[name])
+		this.hooks.onSave?.(clone)
+		this.storageSaveManager(name, clone)
+	}
+
+	protected notifyIfError<T extends Result<any, Error>>(res: T): T {
+		if (!res.isOk) {
+			this.hooks.onError?.(res.error)
+		}
+		return res
+	}
+
+	changeManager(name: string, opts: { force?: boolean } = {}): Result<void, Error> {
+		if (this.managerNames.includes(name)) {
+			this.setActiveManager(name)
+			return Ok()
+		} else {
+			const m = this.storageReadManager(name, opts)
+			if (m.isOk) {
+				this.load(m.value)
+				this.setActiveManager(name)
+			}
+			return Ok()
+		}
+	}
+
+	deleteManager(name: string): Result<void, Error> {
+		const index = this.managerNames.indexOf(name)
+		let nextName = this.managerNames[index - 1] ?? this.managerNames[index + 1] ?? "default"
+		this.storageRemoveManager(name)
+		this.setManager(name, undefined)
+
+		if (nextName === name) nextName = "default"
+		const res = this.changeManager(nextName, { force: true })
+		this.notifyIfError(res)
+		return res
+	}
+
+	renameManager(name: string): void {
+		this.storageRemoveManager(this.activeManagerName)
+		this.setManager(name, this.managers[this.activeManagerName])
+		this.setManager(this.activeManagerName, undefined)
+		this.setActiveManager(name)
+		this.save(name)
+	}
+
+	duplicateManager(oldName: string, newName: string): Result<Manager, Error> {
+		const m = this.managers[oldName]
+		if (!m) {
+			const res = Err(new Error(`No manager found by the name of ${oldName}.`))
+			return this.notifyIfError(res)
+		}
+		const clone = managerToStorableClone(m)
+		clone.name = newName
+		const instance = this.createManager(clone as any, false)
+		if (instance instanceof Error) return this.notifyIfError(Err(instance))
+		else if (instance) this.load(instance)
+
+		return Ok(instance)
+	}
+
+	exportManagers(names: string[]): Result<object, Error> {
+		const obj = { managers: [] as any[] }
+		for (const name of names) {
+			const m = this.managers[name]
+			if (!m) {
+				const res = Err(new Error(`No manager found by the name of ${name}.`))
+				return this.notifyIfError(res)
+			}
+			const clone = managerToStorableClone(m)
+			this.hooks.onSave?.(clone)
+			obj.managers.push(clone)
+		}
+		this.hooks.onExport?.(obj)
+		return Ok(obj)
+	}
+
+	importManagers(content: string): Result<void, Error> {
+		const p = JSON.parse(content)
+		if (!p.managers || !isArray(p.manager)) {
+			return Err(new Error(`Not a valid manager file.`))
+		}
+		const ok: Manager[] = []
+		for (const parsedM of p.managers) {
+			const m = this.parseJsonManager(JSON.stringify(parsedM))
+			this.notifyIfError(m)
+
+			if (m.isOk) {
+				const instance = this.createManager(m.value as any, false)
+				if (instance instanceof Error) return this.notifyIfError(Err(instance))
+				ok.push(instance)
+			}
+		}
+		for (const instance of ok) {
+			this.load(instance)
+		}
+		return Ok()
+	}
+
+	/** Clears all managers and resets the state. `init` must be called again if you want to use the class instance again. */
+	clearAll(): void {
+		// todo, check we can init again after this
+		this.storage.removeItem(this.storageKeys.managerNames)
+		this.storage.removeItem(this.storageKeys.activeManager)
+		for (const name of this.managerNames) {
+			this.storageRemoveManager(name)
+		}
+		this.setManagerNames([])
+		this.setActiveManager("default")
+	}
+}

package/src/core/addCommand.ts

@@ -0,0 +1,24 @@
+import { Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { setCommandsProp } from "./setCommandsProp.js"
+
+import type { CanHookErrors, Command, CommandsSetEntries, Manager, MultipleErrors } from "../types/index.js"
+
+
+export function addCommand<
+	THooks extends Manager["hooks"],
+	TCheck extends boolean | "only" = true
+>(
+	command: Command,
+	manager: CommandsSetEntries["entries@add"]["manager"] & { hooks?: THooks },
+	opts: { check?: TCheck } = {}
+): Result<
+	TCheck extends "only" ? true : Command,
+	MultipleErrors<
+		CommandsSetEntries["entries@add"]["error"]
+	> | CanHookErrors<THooks extends never ? never : THooks, "canSetCommandsProp">
+> {
+	const res = setCommandsProp("entries@add", command, manager, opts)
+	if (res.isError) return res
+	return Ok(command) satisfies Result<Command, never> as any
+}

package/src/core/addKey.ts

@@ -0,0 +1,25 @@
+import { Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { setKeysProp } from "./setKeysProp.js"
+
+import type { CanHookErrors, Key, KeysSetEntries, Manager, MultipleErrors } from "../types/index.js"
+
+
+export function addKey<
+	THooks extends Manager["hooks"],
+	TCheck extends boolean | "only" = true
+>(
+	key: Key,
+	manager: KeysSetEntries["entries@add"]["manager"] & { hooks?: THooks },
+	opts: { check?: TCheck } = {}
+): Result<
+	TCheck extends "only" ? true : Key,
+	MultipleErrors<
+		KeysSetEntries["entries@add"]["error"]
+	> | CanHookErrors<THooks extends never ? never : THooks, "canSetKeysProp">
+> {
+	const res = setKeysProp("entries@add", key, manager, opts)
+	if (res.isError) return res
+	return Ok(key) satisfies Result<Key, never> as any
+}
+

package/src/core/addShortcut.ts

@@ -0,0 +1,24 @@
+import { Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { setShortcutsProp } from "./setShortcutsProp.js"
+
+import type { CanHookErrors, Manager, MultipleErrors, Shortcut, ShortcutsSetEntries } from "../types/index.js"
+
+
+export function addShortcut<
+	THooks extends Manager["hooks"],
+	TCheck extends boolean | "only" = true
+>(
+	shortcut: Shortcut,
+	manager: ShortcutsSetEntries["entries@add"]["manager"] & { hooks?: THooks },
+	opts: { check?: TCheck } = {}
+): Result<
+	TCheck extends "only" ? true : Shortcut,
+	MultipleErrors<
+		ShortcutsSetEntries["entries@add"]["error"]
+	> | CanHookErrors<THooks extends never ? never : THooks, "canSetShortcutsProp">
+> {
+	const res = setShortcutsProp("entries@add", shortcut, manager, opts)
+	if (res.isError) return res
+	return Ok(shortcut) satisfies Result<Shortcut, never> as any
+}

package/src/core/attach.ts

@@ -0,0 +1,27 @@
+import { keys } from "@alanscodelog/utils/keys"
+import type { AnyFunction } from "@alanscodelog/utils/types"
+
+import type { AttachTarget, EventTypes } from "../types/index.js"
+/**
+ * Attach the event listeners created by {@link createManagerEventListeners} to an element or {@link Emulator} so the manager can listen to the needed event hooks.
+ *
+ * They can be removed with {@link detach} or by aborting the controller returned by the function.
+ */
+export function attach(
+	el: AttachTarget,
+	listeners: Record<EventTypes, AnyFunction>,
+	/** Add options to some listeners. An abort controller is added by default. You can use the `*` key to set a default for all. */
+	opts: Partial<Record<EventTypes | "*", AddEventListenerOptions>> = { wheel: { passive: true } }
+): AbortController {
+	const controller = new AbortController()
+	const defaultOpts = opts["*"] ?? {}
+	for (const listenerName of keys(listeners)) {
+		el.addEventListener(listenerName, listeners[listenerName], {
+			signal: controller.signal,
+			...defaultOpts,
+			...opts[listenerName]
+		})
+	}
+	return controller
+}
+

package/src/core/createCommand.ts

@@ -0,0 +1,24 @@
+import type { Command, CommandExecute, RawCommand } from "../types/index.js"
+
+
+export function createCommand<
+	TName extends string = string,
+	TCommand extends RawCommand<TName> = RawCommand<TName>
+>(
+	name: TName,
+	// we only type the execute here so the user gets type safety but doesn't
+	// pay the price of Command being too strictly typed
+	rawCommand: Omit<TCommand, "name" | "execute"> & { execute: CommandExecute<TName> } = {} as any
+// TName is not passed on purpose! making the command so strictly types is annoying
+// since typescript will complain the command returned does not satisfy the base command (due to execute)
+): Command {
+	const command: Command = {
+		...rawCommand as any,
+		type: "command",
+		name,
+		execute: rawCommand.execute as any,
+		description: rawCommand.description ?? "",
+		condition: rawCommand.condition ?? { type: "condition", text: "" }
+	}
+	return command as any
+}

package/src/core/createCommands.ts

@@ -0,0 +1,45 @@
+import { Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { addCommand } from "./addCommand.js"
+
+import { defaultStringifier } from "../defaults/Stringifier.js"
+import type { CanHookErrors, Command, Commands, CommandsSetEntries, Manager, MultipleErrors, PickManager } from "../types/index.js"
+
+/**
+ * # Commands
+ * Creates a set of commands.
+ */
+export function createCommands<
+	THooks extends Manager["hooks"],
+	TEntries extends Record<string, Command>,
+	TCheck extends boolean | "only" = true
+
+>(
+	commandsList: Command[],
+	manager: PickManager<"options", "stringifier"> & { hooks?: THooks } = {
+		options: { stringifier: defaultStringifier }
+	},
+	{ check = true as TCheck }: { check?: TCheck } = {}
+): Result<
+	TCheck extends "only" ? true : Commands<TEntries>,
+	MultipleErrors<
+		CommandsSetEntries["entries@add"]["error"]
+	> | CanHookErrors<THooks extends never ? never : THooks, "canSetCommandsProp">
+> {
+	const commands: Commands = {
+		type: "commands",
+		entries: {}
+	}
+	const managerClone = { ...manager, commands }
+	if (check) {
+		for (const command of commandsList) {
+			// we check all first to avoid erroring mid-way through
+			const res = addCommand(command, managerClone)
+			if (res.isError) return res
+		}
+	}
+	if (check === "only") return Ok(true) satisfies Result<true, never> as any
+
+	return Ok(commands) satisfies Result<Commands, never> as any
+}
+

package/src/core/createCondition.ts

@@ -0,0 +1,21 @@
+import type { Condition } from "../types/index.js"
+
+
+export function createCondition<TTextCondition extends string, TReturn extends Condition>(
+	rawCondition: TTextCondition,
+	/**
+	 * Optionally modify the shape of the condition and add your own properties.
+	 * For example, you can append a parsed AST like representation of the condition.
+	 */
+	parse?: (raw: TTextCondition, condition: Condition) => TReturn
+): TReturn {
+	let condition: Condition = {
+		...rawCondition as any,
+		type: "condition",
+		text: rawCondition ?? ""
+	}
+	if (parse) {
+		condition = parse(rawCondition, condition)
+	}
+	return condition as any
+}

package/src/core/createContext.ts

@@ -0,0 +1,14 @@
+import type { Context, RawContext } from "../types/index.js"
+
+
+export function createContext<TContext extends RawContext>(
+	value: TContext["value"],
+	rawContext: Omit<TContext, "value"> = {} as any
+): Context<TContext["value"]> {
+	const context: Context = {
+		type: "context",
+		...rawContext,
+		value
+	}
+	return context
+}

package/src/core/createKey.ts

@@ -0,0 +1,59 @@
+import { Err, Ok, type Result } from "@alanscodelog/utils/Result"
+
+import { KnownError } from "../helpers/KnownError.js"
+import { type Key, type MultipleErrors, type RawKey, SHORTCUT_ERROR } from "../types/index.js"
+
+
+/**
+ * Creates a key.
+ *
+ * @template TId **@internal** See {@link ./README.md Collection Entries}
+ * @param id See {@link Key.id}
+ * @param opts Set {@link Key}.
+ */
+
+export function createKey<
+	TId extends string = string,
+	TKey extends RawKey<TId> = RawKey<TId>
+>(
+	id: TId,
+	rawKey: Omit<TKey, "id"> = {} as any
+): Result<
+	Key<TId>,
+	MultipleErrors<
+		| typeof SHORTCUT_ERROR.INVALID_VARIANT
+	>
+> {
+	const k = rawKey
+	const key: Key<TId> = {
+		type: "key",
+		id,
+		label: k.label ?? id,
+		classes: [...(k.classes as any ?? [])],
+		x: k.x ?? 0,
+		y: k.y ?? 0,
+		width: k.width ?? 0,
+		height: k.height ?? 0,
+		enabled: k.enabled ?? true,
+		pressed: false,
+		isModifier: k.isModifier ?? false,
+		isToggle: (k.isToggle ?? false) satisfies Key["isToggle"] as false,
+		...(k.isToggle
+			? {
+				toggleOnId: `${id}On`,
+				toggleOffId: `${id}Off`,
+				toggleOnPressed: false,
+				toggleOffPressed: false
+			} satisfies Partial<Key<string>>
+			: {}) as any,
+		variants: k.variants ?? [],
+		render: k.render ?? true,
+		updateStateOnAllEvents: k.updateStateOnAllEvents ?? true
+	}
+	if (key.variants?.includes(key.id)) {
+		return Err(
+			new KnownError(SHORTCUT_ERROR.INVALID_VARIANT, `A key variant cannot be the key id itself. Attempted to use "${key.id}" in variants:[ ${key.variants.join(",")} ]`, { variants: key.variants as any /* todo */, id: key.id })
+		)
+	}
+	return Ok(key)
+}