ref: better feature info types

Author: Sv443

src/features/index.ts

@@ -2,6 +2,7 @@ import { t, tp } from "../translations";
 import { getPreferredLocale } from "../utils";
 import langMapping from "../../assets/locales.json" assert { type: "json" };
 import { remSongMinPlayTime } from "./behavior";
+import { FeatureInfo } from "../types";
 
 export * from "./layout";
 export * from "./behavior";
@@ -10,14 +11,6 @@ export * from "./lyrics";
 export * from "./songLists";
 export * from "./versionCheck";
 
-//#MARKER types
-
-/** Union of all feature keys */
-export type FeatInfoKey = keyof typeof featInfo;
-
-/** Union of all feature categories */
-export type FeatureCategory = typeof featInfo[FeatInfoKey]["category"];
-
 type SelectOption = { value: number | string, label: string };
 
 //#MARKER feature dependencies
@@ -38,9 +31,9 @@ const localeOptions = Object.entries(langMapping).reduce((a, [locale, { name }])
  * **Required props:**
  * | Property | Description |
  * | :-- | :-- |
- * | `type` | type of the feature - see below for possible values |
- * | `category` | category of the feature - see what `FeatureCategory` above expands to for possible values |
- * | `default` | default value of the feature - type of the value depends on the `type` property |
+ * | `type` | type of the feature configuration element - use autocomplete or check `FeatureTypeProps` in `src/types.ts` |
+ * | `category` | category of the feature - use autocomplete or check `FeatureCategory` in `src/types.ts` |
+ * | `default` | default value of the feature - type of the value depends on the given `type` |
  * | `enable(value: any)` | function that will be called when the feature is enabled / initialized for the first time |
  *   
  * **Optional props:**
@@ -53,7 +46,7 @@ const localeOptions = Object.entries(langMapping).reduce((a, [locale, { name }])
  * | `min` | Only if type is `number` or `slider` - Overwrites the default of the `min` property of the HTML input element |
  * | `max` | Only if type is `number` or `slider` - Overwrites the default of the `max` property of the HTML input element |
  * | `step` | Only if type is `number` or `slider` - Overwrites the default of the `step` property of the HTML input element |
- * | `unit` | Only if type is `number` or `slider` - The unit text that is displayed next to the input element |
+ * | `unit` | Only if type is `number` or `slider` - The unit text that is displayed next to the input element, i.e. "px" |
  *   
  * **Notes:**
  * - If no `disable()` or `change()` function is present, the page needs to be reloaded for the changes to take effect
@@ -285,4 +278,4 @@ export const featInfo = {
     default: 1,
     enable: () => void "TODO",
   },
-} as const;
+} as const satisfies FeatureInfo;

src/menu/menu_old.ts

@@ -1,12 +1,12 @@
 import { compress, decompress, debounce, isScrollable } from "@sv443-network/userutils";
 import { defaultConfig, getFeatures, migrations, saveFeatures, setDefaultFeatures } from "../config";
 import { host, scriptInfo } from "../constants";
-import { FeatureCategory, FeatInfoKey, featInfo, disableBeforeUnload } from "../features/index";
+import { featInfo, disableBeforeUnload } from "../features/index";
 import { error, getResourceUrl, info, log, resourceToHTMLString, warn } from "../utils";
 import { formatVersion } from "../config";
 import { emitSiteEvent, siteEvents } from "../siteEvents";
 import { getLocale, hasKey, initTranslations, setLocale, t } from "../translations";
-import { FeatureConfig, HotkeyObj } from "../types";
+import { FeatureCategory, FeatureKey, FeatureConfig, HotkeyObj } from "../types";
 import changelog from "../../changelog.md";
 import "./menu_old.css";
 import { createHotkeyInput } from "./hotkeyInput";
@@ -245,11 +245,11 @@ export async function addCfgMenu() {
     .reduce(
       (acc, [key, { category }]) => {
         if(!acc[category])
-          acc[category] = {} as Record<FeatInfoKey, unknown>;
-        acc[category][key as FeatInfoKey] = featureCfg[key as FeatInfoKey];
+          acc[category] = {} as Record<FeatureKey, unknown>;
+        acc[category][key as FeatureKey] = featureCfg[key as FeatureKey];
         return acc;
       },
-    {} as Record<FeatureCategory, Record<FeatInfoKey, unknown>>,
+    {} as Record<FeatureCategory, Record<FeatureKey, unknown>>,
     );
 
   const fmtVal = (v: unknown) => String(v).trim();
@@ -310,7 +310,7 @@ export async function addCfgMenu() {
               e.preventDefault();
               e.stopPropagation();
 
-              openHelpDialog(featKey as FeatInfoKey);
+              openHelpDialog(featKey as FeatureKey);
             });
           }
           else {
@@ -632,10 +632,10 @@ function checkToggleScrollIndicator() {
 
 let isHelpDialogOpen = false;
 /** Key of the feature currently loaded in the help dialog */
-let helpDialogCurFeature: FeatInfoKey | undefined;
+let helpDialogCurFeature: FeatureKey | undefined;
 
 /** Opens the feature help dialog for the given feature */
-async function openHelpDialog(featureKey: FeatInfoKey) {
+async function openHelpDialog(featureKey: FeatureKey) {
   if(isHelpDialogOpen)
     return;
   isHelpDialogOpen = true;

src/types.ts

@@ -98,6 +98,78 @@ declare global {
   }
 }
 
+export type FeatureKey = keyof FeatureConfig;
+
+export type FeatureCategory =
+  | "layout"
+  | "songLists"
+  | "behavior"
+  | "input"
+  | "lyrics"
+  | "general";
+
+type SelectOption = {
+  value: string | number,
+  label: string,
+};
+
+type FeatureTypeProps = 
+  | {
+    type: "toggle",
+    default: boolean,
+  }
+  | {
+    type: "number",
+    default: number,
+    min: number,
+    max: number,
+    step?: number,
+    unit?: string,
+  }
+  | {
+    type: "select",
+    default: string | number,
+    options: SelectOption[] | (() => SelectOption[]),
+  }
+  | {
+    type: "slider",
+    default: number,
+    min: number,
+    max: number,
+    step?: number,
+    unit?: string,
+  }
+  | {
+    type: "hotkey",
+    default: HotkeyObj,
+  };
+
+type FeatureFuncProps = {
+  enable: () => void,
+} & (
+  {
+    disable?: () => void,
+  }
+  | {
+    change?: () => void,
+  }
+)
+
+/**
+ * The feature info object that contains all properties necessary to construct the config menu and the feature config object.  
+ * Values are loosely typed so try to only use this with the `satisfies` keyword.  
+ * Use `typeof featInfo` (from `src/features/index.ts`) instead for full type safety.
+ */
+export type FeatureInfo = Record<
+  keyof FeatureConfig,
+  {
+    category: FeatureCategory;
+    helpText?: string | (() => string);
+  }
+    & FeatureTypeProps
+    & FeatureFuncProps
+>;
+
 /** Feature configuration */
 export interface FeatureConfig {
   //#SECTION layout