@elite-dangerous-plugin-framework/react 0.0.1-pre1

package/README.md

@@ -0,0 +1,7 @@
+# @elite-dangerous-plugin-framework/react
+
+This contains helpers for creating React-based EDPF plugins.
+
+## Getting Started
+
+TODO

package/dist/_virtual/rolldown_runtime.js

@@ -0,0 +1,18 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { index_d_exports } from "./v1alpha/index.js";
+export { index_d_exports as V1Alpha };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { v1alpha_exports } from "./v1alpha/index.js";
+
+export { v1alpha_exports as V1Alpha };

package/dist/v1alpha/context.d.ts

@@ -0,0 +1,35 @@
+import { PluginContextV1Alpha, PluginSettingsContextV1Alpha } from "@elite-dangerous-plugin-framework/core/v1alpha";
+import * as react0 from "react";
+
+//#region src/v1alpha/context.d.ts
+/**
+ * Context that exposes a `PluginContext` instance passed from EDPF. This is only present on the main Plugin Element (→ not on settings, overlay, etc).
+ *
+ * This specific context shall only be used for Plugins that use the `v1alpha` manifest version.
+ *
+ * Use `useContext(PluginContext)` to get the instance. The instance is guaranteed to never be null if used within `makePluginV1Alpha`.
+ *
+ *
+ */
+declare const PluginContext: react0.Context<PluginContextV1Alpha>;
+/**
+ * Helper for getting the plugin context via a hook
+ */
+declare function usePluginContext(): PluginContextV1Alpha;
+/**
+ * Context that exposes a `SettingsContext` instance passed from EDPF. This is only present on the settings Element.
+ *
+ * This specific context shall only be used for Plugins that use the `v1alpha` manifest version.
+ *
+ * Use `useContext(SettingsContext)` to get the instance. The instance is guaranteed to never be null if used within `makePluginV1Alpha`.
+ *
+ *
+ */
+declare const SettingsContext: react0.Context<PluginSettingsContextV1Alpha>;
+/**
+ * Helper for getting the settings context via a hook
+ */
+declare function useSettingsContext(): PluginSettingsContextV1Alpha;
+//#endregion
+export { PluginContext, SettingsContext, usePluginContext, useSettingsContext };
+//# sourceMappingURL=context.d.ts.map

package/dist/v1alpha/context.js

@@ -0,0 +1,39 @@
+import { createContext, useContext } from "react";
+
+//#region src/v1alpha/context.ts
+/**
+* Context that exposes a `PluginContext` instance passed from EDPF. This is only present on the main Plugin Element (→ not on settings, overlay, etc).
+*
+* This specific context shall only be used for Plugins that use the `v1alpha` manifest version.
+*
+* Use `useContext(PluginContext)` to get the instance. The instance is guaranteed to never be null if used within `makePluginV1Alpha`.
+*
+*
+*/
+const PluginContext = createContext(null);
+/**
+* Helper for getting the plugin context via a hook
+*/
+function usePluginContext() {
+	return useContext(PluginContext);
+}
+/**
+* Context that exposes a `SettingsContext` instance passed from EDPF. This is only present on the settings Element.
+*
+* This specific context shall only be used for Plugins that use the `v1alpha` manifest version.
+*
+* Use `useContext(SettingsContext)` to get the instance. The instance is guaranteed to never be null if used within `makePluginV1Alpha`.
+*
+*
+*/
+const SettingsContext = createContext(null);
+/**
+* Helper for getting the settings context via a hook
+*/
+function useSettingsContext() {
+	return useContext(SettingsContext);
+}
+
+//#endregion
+export { PluginContext, SettingsContext, usePluginContext, useSettingsContext };
+//# sourceMappingURL=context.js.map

package/dist/v1alpha/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":[],"sources":["../../src/v1alpha/context.ts"],"sourcesContent":["import {\n  PluginSettingsContextV1Alpha,\n  type PluginContextV1Alpha,\n} from \"@elite-dangerous-plugin-framework/core/v1alpha\";\nimport { createContext, useContext } from \"react\";\n\n/**\n * Context that exposes a `PluginContext` instance passed from EDPF. This is only present on the main Plugin Element (→ not on settings, overlay, etc).\n *\n * This specific context shall only be used for Plugins that use the `v1alpha` manifest version.\n *\n * Use `useContext(PluginContext)` to get the instance. The instance is guaranteed to never be null if used within `makePluginV1Alpha`.\n *\n *\n */\nexport const PluginContext = createContext<PluginContextV1Alpha>(null!);\n\n/**\n * Helper for getting the plugin context via a hook\n */\nexport function usePluginContext() {\n  return useContext(PluginContext);\n}\n\n/**\n * Context that exposes a `SettingsContext` instance passed from EDPF. This is only present on the settings Element.\n *\n * This specific context shall only be used for Plugins that use the `v1alpha` manifest version.\n *\n * Use `useContext(SettingsContext)` to get the instance. The instance is guaranteed to never be null if used within `makePluginV1Alpha`.\n *\n *\n */\nexport const SettingsContext = createContext<PluginSettingsContextV1Alpha>(\n  null!,\n);\n\n/**\n * Helper for getting the settings context via a hook\n */\nexport function useSettingsContext() {\n  return useContext(SettingsContext);\n}\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,gBAAgB,cAAoC,KAAM;;;;AAKvE,SAAgB,mBAAmB;AACjC,QAAO,WAAW,cAAc;;;;;;;;;;;AAYlC,MAAa,kBAAkB,cAC7B,KACD;;;;AAKD,SAAgB,qBAAqB;AACnC,QAAO,WAAW,gBAAgB"}

package/dist/v1alpha/hooks/index.d.ts

@@ -0,0 +1,3 @@
+import { useBundledResource } from "./useBundledResource.js";
+import { useJournalEvents } from "./useJournalEvents.js";
+import { usePluginSetting, useTranslation } from "./usePluginSetting.js";

package/dist/v1alpha/hooks/index.js

@@ -0,0 +1,3 @@
+import { useBundledResource } from "./useBundledResource.js";
+import { useJournalEvents } from "./useJournalEvents.js";
+import { usePluginSetting, useTranslation } from "./usePluginSetting.js";

package/dist/v1alpha/hooks/useBundledResource.d.ts

@@ -0,0 +1,9 @@
+//#region src/v1alpha/hooks/useBundledResource.d.ts
+/**
+ * This is a simple hook that will give you the asset name to use. It essentially just prepends the path to the asset server
+ * @param pathInFrontendDir the relative path to your plugin's `frontend` folder.
+ */
+declare function useBundledResource(pathInFrontendDir: string): string;
+//#endregion
+export { useBundledResource };
+//# sourceMappingURL=useBundledResource.d.ts.map

package/dist/v1alpha/hooks/useBundledResource.js

@@ -0,0 +1,17 @@
+import { PluginContext } from "../context.js";
+import { useContext } from "react";
+
+//#region src/v1alpha/hooks/useBundledResource.ts
+/**
+* This is a simple hook that will give you the asset name to use. It essentially just prepends the path to the asset server
+* @param pathInFrontendDir the relative path to your plugin's `frontend` folder.
+*/
+function useBundledResource(pathInFrontendDir) {
+	const ctx = useContext(PluginContext);
+	if (pathInFrontendDir.startsWith("/")) pathInFrontendDir = pathInFrontendDir.substring(1);
+	return ctx.assetsBase + pathInFrontendDir;
+}
+
+//#endregion
+export { useBundledResource };
+//# sourceMappingURL=useBundledResource.js.map

package/dist/v1alpha/hooks/useBundledResource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBundledResource.js","names":[],"sources":["../../../src/v1alpha/hooks/useBundledResource.ts"],"sourcesContent":["import { useContext } from \"react\";\nimport { PluginContext } from \"../context.js\";\n\n/**\n * This is a simple hook that will give you the asset name to use. It essentially just prepends the path to the asset server\n * @param pathInFrontendDir the relative path to your plugin's `frontend` folder.\n */\nexport function useBundledResource(pathInFrontendDir: string): string {\n  const ctx = useContext(PluginContext);\n  if (pathInFrontendDir.startsWith(\"/\")) {\n    pathInFrontendDir = pathInFrontendDir.substring(1);\n  }\n  return ctx.assetsBase + pathInFrontendDir;\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,mBAAmB,mBAAmC;CACpE,MAAM,MAAM,WAAW,cAAc;AACrC,KAAI,kBAAkB,WAAW,IAAI,CACnC,qBAAoB,kBAAkB,UAAU,EAAE;AAEpD,QAAO,IAAI,aAAa"}

package/dist/v1alpha/hooks/useJournalEvents.d.ts

@@ -0,0 +1,46 @@
+import { JournalEvent, JournalEvent_BI } from "@elite-dangerous-plugin-framework/journal";
+
+//#region src/v1alpha/hooks/useJournalEvents.d.ts
+type Mode = "raw" | "jsonBigint" | "jsonSimple";
+type ResponseTypeByMode = {
+  raw: string;
+  jsonBigint: JournalEvent_BI;
+  jsonSimple: JournalEvent;
+};
+/**
+ * This hook accepts a callback that is invoked whenever the plugin receives a batch of new journal items.
+ * Do note multiple CMDR's files are send in separate batches.
+ *
+ * Note that you must provide a `mode`. The mode will determine how the journal items are transformed before being passed to the callback.
+ * - `raw` - events are not altered at all and not parsed at all. Each event is a `string`.
+ * - `jsonBigint` - events are converted and get strong typing. Integer numbers are parsed as BigInt's
+ * - `jsonSimple` - events are converted and get strong typing. Parsing is done using the regular `JSON.parse`
+ *
+ * If you need help choosing:
+ * - do you rely on IDs in your plugin? → pick `jsonBigint`
+ * - else, pick `jsonSimple`
+ * - if you have some very odd use case where you need to event as string, do pick `raw`
+ *
+ * @example
+ * ```tsx
+ * function Example() {
+ *  const [lastEventName, setLastEventName] = useState("");
+ *  useJournalEvents("jsonSimple", ({ events }) =>
+ *    setLastEventName(events[events.length - 1].event),
+ *  );
+ *
+ *  return <div>Last event name: {lastEventName ?? "(awaiting first event)"}</div>
+ * }
+ * ```
+ *
+ * @param mode one of `raw` | `jsonBigint` | `jsonSimple`. See function-block comment for more info
+ * @param cb The callback invoked whenever a new batch of journals is received. Do note that you get different typings based on the mode you pick!
+ */
+declare function useJournalEvents<T extends Mode>(mode: T, cb: (payload: {
+  events: ResponseTypeByMode[T][];
+  cmdr: string;
+  file: string;
+}) => void): undefined;
+//#endregion
+export { useJournalEvents };
+//# sourceMappingURL=useJournalEvents.d.ts.map

package/dist/v1alpha/hooks/useJournalEvents.js

@@ -0,0 +1,69 @@
+import { PluginContext } from "../context.js";
+import { useContext, useEffect, useRef } from "react";
+import { parseWithBigInt, parseWithLossyIntegers } from "@elite-dangerous-plugin-framework/journal";
+
+//#region src/v1alpha/hooks/useJournalEvents.ts
+/**
+* This hook accepts a callback that is invoked whenever the plugin receives a batch of new journal items.
+* Do note multiple CMDR's files are send in separate batches.
+*
+* Note that you must provide a `mode`. The mode will determine how the journal items are transformed before being passed to the callback.
+* - `raw` - events are not altered at all and not parsed at all. Each event is a `string`.
+* - `jsonBigint` - events are converted and get strong typing. Integer numbers are parsed as BigInt's
+* - `jsonSimple` - events are converted and get strong typing. Parsing is done using the regular `JSON.parse`
+*
+* If you need help choosing:
+* - do you rely on IDs in your plugin? → pick `jsonBigint`
+* - else, pick `jsonSimple`
+* - if you have some very odd use case where you need to event as string, do pick `raw`
+*
+* @example
+* ```tsx
+* function Example() {
+*  const [lastEventName, setLastEventName] = useState("");
+*  useJournalEvents("jsonSimple", ({ events }) =>
+*    setLastEventName(events[events.length - 1].event),
+*  );
+*
+*  return <div>Last event name: {lastEventName ?? "(awaiting first event)"}</div>
+* }
+* ```
+*
+* @param mode one of `raw` | `jsonBigint` | `jsonSimple`. See function-block comment for more info
+* @param cb The callback invoked whenever a new batch of journals is received. Do note that you get different typings based on the mode you pick!
+*/
+function useJournalEvents(mode, cb) {
+	const ctx = useContext(PluginContext);
+	const cbRef = useRef(cb);
+	useEffect(() => {
+		cbRef.current = cb;
+	}, [cb]);
+	useEffect(() => {
+		if (!ctx) return;
+		return ctx.registerEventListener((evs) => {
+			if (evs.length === 0) return;
+			const { cmdr, file } = evs[0];
+			let events;
+			switch (mode) {
+				case "raw":
+					events = evs.map((e) => e.event);
+					break;
+				case "jsonBigint":
+					events = evs.map((e) => parseWithBigInt(e.event));
+					break;
+				case "jsonSimple":
+					events = evs.map((e) => parseWithLossyIntegers(e.event));
+					break;
+			}
+			cbRef.current({
+				events,
+				cmdr,
+				file
+			});
+		});
+	}, [ctx, mode]);
+}
+
+//#endregion
+export { useJournalEvents };
+//# sourceMappingURL=useJournalEvents.js.map

package/dist/v1alpha/hooks/useJournalEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useJournalEvents.js","names":[],"sources":["../../../src/v1alpha/hooks/useJournalEvents.ts"],"sourcesContent":["import { useContext, useEffect, useRef } from \"react\";\nimport { PluginContext } from \"../context.js\";\nimport {\n  JournalEvent,\n  JournalEvent_BI,\n  parseWithBigInt,\n  parseWithLossyIntegers,\n} from \"@elite-dangerous-plugin-framework/journal\";\n\ntype Mode = \"raw\" | \"jsonBigint\" | \"jsonSimple\";\ntype ResponseTypeByMode = {\n  raw: string;\n  jsonBigint: JournalEvent_BI;\n  jsonSimple: JournalEvent;\n};\n\n/**\n * This hook accepts a callback that is invoked whenever the plugin receives a batch of new journal items.\n * Do note multiple CMDR's files are send in separate batches.\n *\n * Note that you must provide a `mode`. The mode will determine how the journal items are transformed before being passed to the callback.\n * - `raw` - events are not altered at all and not parsed at all. Each event is a `string`.\n * - `jsonBigint` - events are converted and get strong typing. Integer numbers are parsed as BigInt's\n * - `jsonSimple` - events are converted and get strong typing. Parsing is done using the regular `JSON.parse`\n *\n * If you need help choosing:\n * - do you rely on IDs in your plugin? → pick `jsonBigint`\n * - else, pick `jsonSimple`\n * - if you have some very odd use case where you need to event as string, do pick `raw`\n *\n * @example\n * ```tsx\n * function Example() {\n *  const [lastEventName, setLastEventName] = useState(\"\");\n *  useJournalEvents(\"jsonSimple\", ({ events }) =>\n *    setLastEventName(events[events.length - 1].event),\n *  );\n *\n *  return <div>Last event name: {lastEventName ?? \"(awaiting first event)\"}</div>\n * }\n * ```\n *\n * @param mode one of `raw` | `jsonBigint` | `jsonSimple`. See function-block comment for more info\n * @param cb The callback invoked whenever a new batch of journals is received. Do note that you get different typings based on the mode you pick!\n */\nexport function useJournalEvents<T extends Mode>(\n  mode: T,\n  cb: (payload: {\n    events: ResponseTypeByMode[T][];\n    cmdr: string;\n    file: string;\n  }) => void,\n): undefined {\n  const ctx = useContext(PluginContext);\n\n  // Keep latest callback without re-subscribing\n  const cbRef = useRef(cb);\n  useEffect(() => {\n    cbRef.current = cb;\n  }, [cb]);\n\n  useEffect(() => {\n    if (!ctx) return;\n\n    const unsubscribe = ctx.registerEventListener((evs) => {\n      if (evs.length === 0) return;\n\n      const { cmdr, file } = evs[0];\n\n      let events: JournalEvent[] | JournalEvent_BI[] | string[];\n      switch (mode) {\n        case \"raw\":\n          events = evs.map((e) => e.event);\n          break;\n        case \"jsonBigint\":\n          events = evs.map((e) => parseWithBigInt(e.event));\n          break;\n        case \"jsonSimple\":\n          events = evs.map((e) => parseWithLossyIntegers(e.event));\n          break;\n      }\n\n      cbRef.current({ events: events as any, cmdr, file });\n    });\n\n    return unsubscribe;\n  }, [ctx, mode]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,iBACd,MACA,IAKW;CACX,MAAM,MAAM,WAAW,cAAc;CAGrC,MAAM,QAAQ,OAAO,GAAG;AACxB,iBAAgB;AACd,QAAM,UAAU;IACf,CAAC,GAAG,CAAC;AAER,iBAAgB;AACd,MAAI,CAAC,IAAK;AAuBV,SArBoB,IAAI,uBAAuB,QAAQ;AACrD,OAAI,IAAI,WAAW,EAAG;GAEtB,MAAM,EAAE,MAAM,SAAS,IAAI;GAE3B,IAAI;AACJ,WAAQ,MAAR;IACE,KAAK;AACH,cAAS,IAAI,KAAK,MAAM,EAAE,MAAM;AAChC;IACF,KAAK;AACH,cAAS,IAAI,KAAK,MAAM,gBAAgB,EAAE,MAAM,CAAC;AACjD;IACF,KAAK;AACH,cAAS,IAAI,KAAK,MAAM,uBAAuB,EAAE,MAAM,CAAC;AACxD;;AAGJ,SAAM,QAAQ;IAAU;IAAe;IAAM;IAAM,CAAC;IACpD;IAGD,CAAC,KAAK,KAAK,CAAC"}

package/dist/v1alpha/hooks/usePluginSetting.d.ts

@@ -0,0 +1,47 @@
+//#region src/v1alpha/hooks/usePluginSetting.d.ts
+/**
+ * Fetch and listen for updates on a specific setting. Also exposes a callback to write a setting, which is only possible if the first segment is identical to the plugin ID (=it's the plugin's own setting)
+ * @param pluginKey a setting key. You can omit the plugin ID. So `pluginname.some.key` and `.some.key` are identical. You can also listen to other plugin's settings, **if** they are public (identified by the last segment being Uppercase).
+ *
+ * @example
+ * ```tsx
+ *  interface SettingValues {
+ *    preferredShipSite: "coriolis" | "edsy";
+ *    preferredSystemSite: "inara" | "spansh" | "edsm";
+ *  }
+ *
+ *  function Example() {
+ *    // we dont write in this example
+ *    const [settings, _, isLoaded] =
+ *      usePluginSetting<SettingValues>(".preferredTooling");
+ *
+ *    if (!isLoaded) {
+ *      return <div>Loading…</div>;
+ *    }
+ *    if (!settings) {
+ *      return <div>No setting set…</div>;
+ *    }
+ *
+ *    return (
+ *      <div>
+ *        Preferred Ship Site: {settings.preferredShipSite}, System Site:{" "}
+ *        {settings.preferredSystemSite}
+ *      </div>
+ *    );
+ *  }
+ * ```
+ *
+ * @returns a tuple containing the setting, the write callback to invoke, and a bool if it has finished the initial load (to differentiate between fetching and fetched but missing).
+ */
+declare function usePluginSetting<T = any>(pluginKey: string): readonly [T | undefined, (val: T | undefined) => void, boolean];
+type Locale = "en" | "es" | "fr" | "de" | "pt" | "it" | "ja" | "ko" | "zh" | "ru";
+/**
+ * Wrapper that gets you the currently selected language. Use this if you are providing translations.
+ * You cannot change the locale from the plugin as the setting belongs to the bundled `core` plugin. Instead, users must change it in the settings pane.
+ *
+ * @returns a tuple of `[currentLocale, initialLoadComplete]`
+ */
+declare function useTranslation(): [Locale | undefined, boolean];
+//#endregion
+export { usePluginSetting, useTranslation };
+//# sourceMappingURL=usePluginSetting.d.ts.map

package/dist/v1alpha/hooks/usePluginSetting.js

@@ -0,0 +1,93 @@
+import { PluginContext } from "../context.js";
+import { useContext, useEffect, useState } from "react";
+
+//#region src/v1alpha/hooks/usePluginSetting.tsx
+/**
+* Fetch and listen for updates on a specific setting. Also exposes a callback to write a setting, which is only possible if the first segment is identical to the plugin ID (=it's the plugin's own setting)
+* @param pluginKey a setting key. You can omit the plugin ID. So `pluginname.some.key` and `.some.key` are identical. You can also listen to other plugin's settings, **if** they are public (identified by the last segment being Uppercase).
+*
+* @example
+* ```tsx
+*  interface SettingValues {
+*    preferredShipSite: "coriolis" | "edsy";
+*    preferredSystemSite: "inara" | "spansh" | "edsm";
+*  }
+*
+*  function Example() {
+*    // we dont write in this example
+*    const [settings, _, isLoaded] =
+*      usePluginSetting<SettingValues>(".preferredTooling");
+*
+*    if (!isLoaded) {
+*      return <div>Loading…</div>;
+*    }
+*    if (!settings) {
+*      return <div>No setting set…</div>;
+*    }
+*
+*    return (
+*      <div>
+*        Preferred Ship Site: {settings.preferredShipSite}, System Site:{" "}
+*        {settings.preferredSystemSite}
+*      </div>
+*    );
+*  }
+* ```
+*
+* @returns a tuple containing the setting, the write callback to invoke, and a bool if it has finished the initial load (to differentiate between fetching and fetched but missing).
+*/
+function usePluginSetting(pluginKey) {
+	const [state, setState] = useState(void 0);
+	const [finishedLoading, setFinishedLoading] = useState(false);
+	const ctx = useContext(PluginContext);
+	const normalizedPluginKey = pluginKey.startsWith(".") ? ctx.pluginMeta.id + pluginKey : pluginKey;
+	useEffect(() => {
+		ctx.Capabilities.Settings.getSetting(normalizedPluginKey).then((e) => {
+			setState(e);
+			setFinishedLoading(true);
+		}).catch((err) => {
+			console.error(`Your Hook to get the setting ${normalizedPluginKey} has failed. This is likely because it is invalid. Please make sure you either access a public setting from a different plugin, or, when accessing an internal setting, make sure the format is correct. Do note you can omit the plugin id and just start with a dot`, {
+				err,
+				normalizedPluginKey,
+				pluginKey
+			});
+			throw err;
+		});
+		return ctx.Capabilities.Settings.registerSettingsChangedListener((k, v) => {
+			if (k !== normalizedPluginKey) return;
+			setState(v);
+		});
+	});
+	const writeSetting = (val) => {
+		ctx.Capabilities.Settings.writeSetting(normalizedPluginKey, val).then((e) => {
+			setState(e);
+		}).catch((err) => {
+			console.error(`Your Hook tried to write ${normalizedPluginKey} and failed. This is likely because you are trying to write another plugin's settings, which is not permitted.`, {
+				err,
+				normalizedPluginKey,
+				pluginKey,
+				ownPluginId: ctx.pluginMeta.id
+			});
+			throw err;
+		});
+	};
+	return [
+		state,
+		writeSetting,
+		finishedLoading
+	];
+}
+/**
+* Wrapper that gets you the currently selected language. Use this if you are providing translations.
+* You cannot change the locale from the plugin as the setting belongs to the bundled `core` plugin. Instead, users must change it in the settings pane.
+*
+* @returns a tuple of `[currentLocale, initialLoadComplete]`
+*/
+function useTranslation() {
+	const [lang, _, loaded] = usePluginSetting("core.Locale");
+	return [lang, loaded];
+}
+
+//#endregion
+export { usePluginSetting, useTranslation };
+//# sourceMappingURL=usePluginSetting.js.map

package/dist/v1alpha/hooks/usePluginSetting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePluginSetting.js","names":[],"sources":["../../../src/v1alpha/hooks/usePluginSetting.tsx"],"sourcesContent":["import { memo, useContext, useEffect, useState } from \"react\";\nimport { PluginContext } from \"../context.js\";\n\n/**\n * Fetch and listen for updates on a specific setting. Also exposes a callback to write a setting, which is only possible if the first segment is identical to the plugin ID (=it's the plugin's own setting)\n * @param pluginKey a setting key. You can omit the plugin ID. So `pluginname.some.key` and `.some.key` are identical. You can also listen to other plugin's settings, **if** they are public (identified by the last segment being Uppercase).\n *\n * @example\n * ```tsx\n *  interface SettingValues {\n *    preferredShipSite: \"coriolis\" | \"edsy\";\n *    preferredSystemSite: \"inara\" | \"spansh\" | \"edsm\";\n *  }\n *\n *  function Example() {\n *    // we dont write in this example\n *    const [settings, _, isLoaded] =\n *      usePluginSetting<SettingValues>(\".preferredTooling\");\n *\n *    if (!isLoaded) {\n *      return <div>Loading…</div>;\n *    }\n *    if (!settings) {\n *      return <div>No setting set…</div>;\n *    }\n *\n *    return (\n *      <div>\n *        Preferred Ship Site: {settings.preferredShipSite}, System Site:{\" \"}\n *        {settings.preferredSystemSite}\n *      </div>\n *    );\n *  }\n * ```\n *\n * @returns a tuple containing the setting, the write callback to invoke, and a bool if it has finished the initial load (to differentiate between fetching and fetched but missing).\n */\nexport function usePluginSetting<T = any>(pluginKey: string) {\n  const [state, setState] = useState<T | undefined>(undefined);\n  const [finishedLoading, setFinishedLoading] = useState(false);\n  const ctx = useContext(PluginContext);\n\n  const normalizedPluginKey = pluginKey.startsWith(\".\")\n    ? ctx.pluginMeta.id + pluginKey\n    : pluginKey;\n\n  useEffect(() => {\n    // fetch initial state immediately\n    ctx.Capabilities.Settings.getSetting(normalizedPluginKey)\n      .then((e) => {\n        setState(e as any);\n        setFinishedLoading(true);\n      })\n      .catch((err) => {\n        console.error(\n          `Your Hook to get the setting ${normalizedPluginKey} has failed. This is likely because it is invalid. Please make sure you either access a public setting from a different plugin, or, when accessing an internal setting, make sure the format is correct. Do note you can omit the plugin id and just start with a dot`,\n          { err, normalizedPluginKey, pluginKey },\n        );\n        throw err;\n      });\n\n    return ctx.Capabilities.Settings.registerSettingsChangedListener((k, v) => {\n      if (k !== normalizedPluginKey) {\n        // this is a setting update not captured by this hook\n        return;\n      }\n      setState(v as any);\n    });\n  });\n\n  const writeSetting = (val: T | undefined) => {\n    ctx.Capabilities.Settings.writeSetting(normalizedPluginKey, val)\n      .then((e) => {\n        setState(e);\n      })\n      .catch((err) => {\n        console.error(\n          `Your Hook tried to write ${normalizedPluginKey} and failed. This is likely because you are trying to write another plugin's settings, which is not permitted.`,\n          {\n            err,\n            normalizedPluginKey,\n            pluginKey,\n            ownPluginId: ctx.pluginMeta.id,\n          },\n        );\n        throw err;\n      });\n  };\n\n  return [state, writeSetting, finishedLoading] as const;\n}\n\ntype Locale =\n  | \"en\"\n  | \"es\"\n  | \"fr\"\n  | \"de\"\n  | \"pt\"\n  | \"it\"\n  | \"ja\"\n  | \"ko\"\n  | \"zh\"\n  | \"ru\";\n/**\n * Wrapper that gets you the currently selected language. Use this if you are providing translations.\n * You cannot change the locale from the plugin as the setting belongs to the bundled `core` plugin. Instead, users must change it in the settings pane.\n *\n * @returns a tuple of `[currentLocale, initialLoadComplete]`\n */\nexport function useTranslation(): [Locale | undefined, boolean] {\n  const [lang, _, loaded] = usePluginSetting<Locale>(\"core.Locale\");\n  return [lang, loaded];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,SAAgB,iBAA0B,WAAmB;CAC3D,MAAM,CAAC,OAAO,YAAY,SAAwB,OAAU;CAC5D,MAAM,CAAC,iBAAiB,sBAAsB,SAAS,MAAM;CAC7D,MAAM,MAAM,WAAW,cAAc;CAErC,MAAM,sBAAsB,UAAU,WAAW,IAAI,GACjD,IAAI,WAAW,KAAK,YACpB;AAEJ,iBAAgB;AAEd,MAAI,aAAa,SAAS,WAAW,oBAAoB,CACtD,MAAM,MAAM;AACX,YAAS,EAAS;AAClB,sBAAmB,KAAK;IACxB,CACD,OAAO,QAAQ;AACd,WAAQ,MACN,gCAAgC,oBAAoB,wQACpD;IAAE;IAAK;IAAqB;IAAW,CACxC;AACD,SAAM;IACN;AAEJ,SAAO,IAAI,aAAa,SAAS,iCAAiC,GAAG,MAAM;AACzE,OAAI,MAAM,oBAER;AAEF,YAAS,EAAS;IAClB;GACF;CAEF,MAAM,gBAAgB,QAAuB;AAC3C,MAAI,aAAa,SAAS,aAAa,qBAAqB,IAAI,CAC7D,MAAM,MAAM;AACX,YAAS,EAAE;IACX,CACD,OAAO,QAAQ;AACd,WAAQ,MACN,4BAA4B,oBAAoB,iHAChD;IACE;IACA;IACA;IACA,aAAa,IAAI,WAAW;IAC7B,CACF;AACD,SAAM;IACN;;AAGN,QAAO;EAAC;EAAO;EAAc;EAAgB;;;;;;;;AAoB/C,SAAgB,iBAAgD;CAC9D,MAAM,CAAC,MAAM,GAAG,UAAU,iBAAyB,cAAc;AACjE,QAAO,CAAC,MAAM,OAAO"}

package/dist/v1alpha/index.d.ts

@@ -0,0 +1,25 @@
+import { PluginContext, SettingsContext, usePluginContext, useSettingsContext } from "./context.js";
+import { useBundledResource } from "./hooks/useBundledResource.js";
+import { useJournalEvents } from "./hooks/useJournalEvents.js";
+import { usePluginSetting, useTranslation } from "./hooks/usePluginSetting.js";
+import "./hooks/index.js";
+import { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha } from "@elite-dangerous-plugin-framework/core/v1alpha";
+import { ReactNode } from "react";
+
+//#region src/v1alpha/index.d.ts
+declare namespace index_d_exports {
+  export { PluginContext, SettingsContext, makePluginV1Alpha, makeSettingsV1Alpha, useBundledResource, useJournalEvents, usePluginContext, usePluginSetting, useSettingsContext, useTranslation };
+}
+/**
+ * This creates a Plugin class definition, as expected by EDPF. You should export the response from your index.tsx as the `default` export.
+ * This Helper already registers a shutdown listener and correctly unmounts the React root element.
+ */
+declare function makePluginV1Alpha(inner: ReactNode): new () => EDPFPluginElementV1Alpha;
+/**
+ * This creates a Settings class definition, as expected by EDPF. You should export the response from your index.tsx as the `settings` export.
+ * This Helper already registers a shutdown listener and correctly unmounts the React root element.
+ */
+declare function makeSettingsV1Alpha(inner: ReactNode): new () => EDPFPluginSettingsElementV1Alpha;
+//#endregion
+export { PluginContext, SettingsContext, index_d_exports, makePluginV1Alpha, makeSettingsV1Alpha, useBundledResource, useJournalEvents, usePluginContext, usePluginSetting, useSettingsContext, useTranslation };
+//# sourceMappingURL=index.d.ts.map

package/dist/v1alpha/index.js

@@ -0,0 +1,63 @@
+import { __exportAll } from "../_virtual/rolldown_runtime.js";
+import { PluginContext, SettingsContext, usePluginContext, useSettingsContext } from "./context.js";
+import { useBundledResource } from "./hooks/useBundledResource.js";
+import { useJournalEvents } from "./hooks/useJournalEvents.js";
+import { usePluginSetting, useTranslation } from "./hooks/usePluginSetting.js";
+import "./hooks/index.js";
+import { EDPFPluginElementV1Alpha, EDPFPluginSettingsElementV1Alpha } from "@elite-dangerous-plugin-framework/core/v1alpha";
+import ReactDOM from "react-dom/client";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/v1alpha/index.tsx
+var v1alpha_exports = /* @__PURE__ */ __exportAll({
+	PluginContext: () => PluginContext,
+	SettingsContext: () => SettingsContext,
+	makePluginV1Alpha: () => makePluginV1Alpha,
+	makeSettingsV1Alpha: () => makeSettingsV1Alpha,
+	useBundledResource: () => useBundledResource,
+	useJournalEvents: () => useJournalEvents,
+	usePluginContext: () => usePluginContext,
+	usePluginSetting: () => usePluginSetting,
+	useSettingsContext: () => useSettingsContext,
+	useTranslation: () => useTranslation
+});
+/**
+* This creates a Plugin class definition, as expected by EDPF. You should export the response from your index.tsx as the `default` export.
+* This Helper already registers a shutdown listener and correctly unmounts the React root element.
+*/
+function makePluginV1Alpha(inner) {
+	return class extends EDPFPluginElementV1Alpha {
+		initPlugin(ctx) {
+			const root = ReactDOM.createRoot(this);
+			ctx.registerShutdownListener(async () => {
+				root.unmount();
+			});
+			root.render(/* @__PURE__ */ jsx(PluginContext.Provider, {
+				value: ctx,
+				children: inner
+			}));
+		}
+	};
+}
+/**
+* This creates a Settings class definition, as expected by EDPF. You should export the response from your index.tsx as the `settings` export.
+* This Helper already registers a shutdown listener and correctly unmounts the React root element.
+*/
+function makeSettingsV1Alpha(inner) {
+	return class extends EDPFPluginSettingsElementV1Alpha {
+		initSettings(ctx) {
+			const root = ReactDOM.createRoot(this);
+			ctx.registerShutdownListener(async () => {
+				root.unmount();
+			});
+			root.render(/* @__PURE__ */ jsx(SettingsContext.Provider, {
+				value: ctx,
+				children: inner
+			}));
+		}
+	};
+}
+
+//#endregion
+export { PluginContext, SettingsContext, makePluginV1Alpha, makeSettingsV1Alpha, useBundledResource, useJournalEvents, usePluginContext, usePluginSetting, useSettingsContext, useTranslation, v1alpha_exports };
+//# sourceMappingURL=index.js.map

package/dist/v1alpha/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/v1alpha/index.tsx"],"sourcesContent":["import {\n  PluginContextV1Alpha,\n  EDPFPluginElementV1Alpha,\n  EDPFPluginSettingsElementV1Alpha,\n  PluginSettingsContextV1Alpha,\n} from \"@elite-dangerous-plugin-framework/core/v1alpha\";\n\nimport { type ReactNode } from \"react\";\nimport ReactDOM from \"react-dom/client\";\nimport { PluginContext, SettingsContext } from \"./context.js\";\n\n/**\n * This creates a Plugin class definition, as expected by EDPF. You should export the response from your index.tsx as the `default` export.\n * This Helper already registers a shutdown listener and correctly unmounts the React root element.\n */\nexport function makePluginV1Alpha(\n  inner: ReactNode,\n): new () => EDPFPluginElementV1Alpha {\n  return class extends EDPFPluginElementV1Alpha {\n    initPlugin(ctx: PluginContextV1Alpha): void {\n      const root = ReactDOM.createRoot(this);\n      ctx.registerShutdownListener(async () => {\n        root.unmount();\n      });\n      root.render(\n        <PluginContext.Provider value={ctx}>{inner}</PluginContext.Provider>,\n      );\n    }\n  };\n}\n\n/**\n * This creates a Settings class definition, as expected by EDPF. You should export the response from your index.tsx as the `settings` export.\n * This Helper already registers a shutdown listener and correctly unmounts the React root element.\n */\nexport function makeSettingsV1Alpha(\n  inner: ReactNode,\n): new () => EDPFPluginSettingsElementV1Alpha {\n  return class extends EDPFPluginSettingsElementV1Alpha {\n    initSettings(ctx: PluginSettingsContextV1Alpha): void {\n      const root = ReactDOM.createRoot(this);\n      ctx.registerShutdownListener(async () => {\n        root.unmount();\n      });\n      root.render(\n        <SettingsContext.Provider value={ctx}>\n          {inner}\n        </SettingsContext.Provider>,\n      );\n    }\n  };\n}\n\nexport * from \"./context.js\";\nexport * from \"./hooks/index.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAeA,SAAgB,kBACd,OACoC;AACpC,QAAO,cAAc,yBAAyB;EAC5C,WAAW,KAAiC;GAC1C,MAAM,OAAO,SAAS,WAAW,KAAK;AACtC,OAAI,yBAAyB,YAAY;AACvC,SAAK,SAAS;KACd;AACF,QAAK,OACH,oBAAC,cAAc;IAAS,OAAO;cAAM;KAA+B,CACrE;;;;;;;;AASP,SAAgB,oBACd,OAC4C;AAC5C,QAAO,cAAc,iCAAiC;EACpD,aAAa,KAAyC;GACpD,MAAM,OAAO,SAAS,WAAW,KAAK;AACtC,OAAI,yBAAyB,YAAY;AACvC,SAAK,SAAS;KACd;AACF,QAAK,OACH,oBAAC,gBAAgB;IAAS,OAAO;cAC9B;KACwB,CAC5B"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "devDependencies": {
+    "@elite-dangerous-plugin-framework/journal": "^0.20260201.2",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "private": false,
+  "name": "@elite-dangerous-plugin-framework/react",
+  "description": "Abstractions and Helpers that make writing React-based EDPF Plugins a breeze",
+  "workspaces": [
+    "packages/*"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "pretty": "prettier src -w"
+  },
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./v1alpha": "./dist/v1alpha/index.js",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@elite-dangerous-plugin-framework/journal": ">=0.20260201.2",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "publishConfig": {
+    "provenance": false,
+    "access": "public"
+  },
+  "version": "0.0.1-pre1",
+  "dependencies": {
+    "@elite-dangerous-plugin-framework/core": "^0.0.1-pre1"
+  },
+  "gitHead": "c7919bb37e1b55eadd413bd0e8ceda64adabdf23"
+}