From 5c0a248b16b8b587884c602c028cf2d50889b58f Mon Sep 17 00:00:00 2001 From: thepaperpilot Date: Sun, 10 Jul 2022 01:44:45 -0500 Subject: [PATCH] Documented /data --- src/data/common.tsx | 65 ++++++++++++++++++++++++++++++++++++++++++ src/data/projEntry.tsx | 12 ++++++++ src/data/themes.ts | 9 ++++++ 3 files changed, 86 insertions(+) diff --git a/src/data/common.tsx b/src/data/common.tsx index 9630d9f..27cf420 100644 --- a/src/data/common.tsx +++ b/src/data/common.tsx @@ -25,18 +25,44 @@ import type { Ref } from "vue"; import { computed, unref } from "vue"; import "./common.css"; +/** An object that configures a {@link ResetButton} */ export interface ResetButtonOptions extends ClickableOptions { + /** The conversion the button uses to calculate how much resources will be gained on click */ conversion: GenericConversion; + /** The tree this reset button is apart of */ tree: GenericTree; + /** The specific tree node associated with this reset button */ treeNode: GenericTreeNode; + /** + * Text to display on low conversion amounts, describing what "resetting" is in this context. + * Defaults to "Reset for ". + */ resetDescription?: Computable; + /** Whether or not to show how much currency would be required to make the gain amount increase. */ showNextAt?: Computable; + /** + * The content to display on the button. + * By default, this includes the reset description, and amount of currency to be gained. + */ display?: Computable; + /** + * Whether or not this button can currently be clicked. + * Defaults to checking the current gain amount is greater than {@link minimumGain} + */ canClick?: Computable; + /** + * When {@link canClick} is left to its default, minimumGain is used to only enable the reset button when a sufficient amount of currency to gain is available. + */ minimumGain?: Computable; + /** A persistent ref to track how much time has passed since the last time this tree node was reset. */ resetTime?: Persistent; } +/** + * A button that is used to control a conversion. + * It will show how much can be converted currently, and can show when that amount will go up, as well as handle only being clickable when a sufficient amount of currency can be gained. + * Assumes this button is associated with a specific node on a tree, and triggers that tree's reset propagation. + */ export type ResetButton = Replace< Clickable, { @@ -49,6 +75,7 @@ export type ResetButton = Replace< } >; +/** A type that matches any valid {@link ResetButton} object. */ export type GenericResetButton = Replace< GenericClickable & ResetButton, { @@ -60,6 +87,10 @@ export type GenericResetButton = Replace< } >; +/** + * Lazily creates a reset button with the given options. + * @param optionsFunc A function that returns the options object for this reset button. + */ export function createResetButton( optionsFunc: OptionsFunc ): ResetButton { @@ -136,12 +167,24 @@ export function createResetButton; } +/** An object that configures a {@link LayerTreeNode} */ export interface LayerTreeNodeOptions extends TreeNodeOptions { + /** The ID of the layer this tree node is associated with */ layerID: string; + /** The color to display this tree node as */ color: Computable; // marking as required + /** + * The content to display in the tree node. + * Defaults to the layer's ID + */ display?: Computable; + /** Whether or not to append the layer to the tabs list. + * If set to false, then the tree node will instead always remove all tabs to its right and then add the layer tab. + * Defaults to true. + */ append?: Computable; } +/** A tree node that is associated with a given layer, and which opens the layer when clicked. */ export type LayerTreeNode = Replace< TreeNode, { @@ -149,6 +192,7 @@ export type LayerTreeNode = Replace< append: GetComputableType; } >; +/** A type that matches any valid {@link LayerTreeNode} object. */ export type GenericLayerTreeNode = Replace< LayerTreeNode, { @@ -157,6 +201,10 @@ export type GenericLayerTreeNode = Replace< } >; +/** + * Lazily creates a tree node that's associated with a specific layer, with the given options. + * @param optionsFunc A function that returns the options object for this tree node. + */ export function createLayerTreeNode( optionsFunc: OptionsFunc ): LayerTreeNode { @@ -184,6 +232,18 @@ export function createLayerTreeNode( }) as unknown as LayerTreeNode; } +/** + * Takes an array of modifier "sections", and creates a JSXFunction that can render all those sections, and allow each section to be collapsed. + * Also returns a list of persistent refs that are used to control which sections are currently collapsed. + * @param sections An array of options objects for each section to display. + * @param sections.title The header for this modifier. + * @param sections.subtitle A subtitle for this modifier, e.g. to explain the context for the modifier. + * @param sections.modifier The modifier to be displaying in this section. + * @param sections.base The base value being modified. + * @param sections.unit The unit of measurement for the base. + * @param sections.baseText The label to call the base amount. + * @param sections.visible Whether or not this section should be currently visible to the player. + */ export function createCollapsibleModifierSections( sections: { title: string; @@ -249,6 +309,11 @@ export function createCollapsibleModifierSections( return [jsxFunc, collapsed]; } +/** + * Creates an HTML string for a span that writes some given text in a given color. + * @param textToColor The content to change the color of + * @param color The color to change the content to look like. Defaults to the current theme's accent 2 variable. + */ export function colorText(textToColor: string, color = "var(--accent2)"): string { return `${textToColor}`; } diff --git a/src/data/projEntry.tsx b/src/data/projEntry.tsx index 8ad9113..34a67a0 100644 --- a/src/data/projEntry.tsx +++ b/src/data/projEntry.tsx @@ -73,15 +73,27 @@ export const main = createLayer("main", () => { }; }); +/** + * Given a player save data object being loaded, return a list of layers that should currently be enabled. + * If your project does not use dynamic layers, this should just return all layers. + */ export const getInitialLayers = ( /* eslint-disable-next-line @typescript-eslint/no-unused-vars */ player: Partial ): Array => [main, prestige]; +/** + * A computed ref whose value is true whenever the game is over. + */ export const hasWon = computed(() => { return false; }); +/** + * Given a player save data object being loaded with a different version, update the save data object to match the structure of the current version. + * @param oldVersion The version of the save being loaded in + * @param player The save data being loaded in + */ /* eslint-disable @typescript-eslint/no-unused-vars */ export function fixOldSave( oldVersion: string | undefined, diff --git a/src/data/themes.ts b/src/data/themes.ts index ae7e55a..7a24e1b 100644 --- a/src/data/themes.ts +++ b/src/data/themes.ts @@ -1,3 +1,4 @@ +/** A object of all CSS variables determined by the current theme. */ export interface ThemeVars { "--foreground": string; "--background": string; @@ -19,14 +20,20 @@ export interface ThemeVars { "--feature-margin": string; } +/** An object representing a theme the player can use to change the look of the game. */ export interface Theme { + /** The values of the theme's CSS variables. */ variables: ThemeVars; + /** Whether or not tabs should "float" in the center of their container. */ floatingTabs: boolean; + /** Whether or not adjacent features should merge together - removing the margin between them, and only applying the border radius to the first and last elements in the row or column. */ mergeAdjacent: boolean; + /** Whether or not to show a pin icon on pinned tooltips. */ showPin: boolean; } declare module "@vue/runtime-dom" { + /** Make CSS properties accept any CSS variables usually controlled by a theme. */ // eslint-disable-next-line @typescript-eslint/no-empty-interface interface CSSProperties extends Partial {} @@ -62,6 +69,7 @@ const defaultTheme: Theme = { showPin: true }; +/** An enum of all available themes and their internal IDs. The keys are their display names. */ export enum Themes { Classic = "classic", Paper = "paper", @@ -69,6 +77,7 @@ export enum Themes { Aqua = "aqua" } +/** A dictionary of all available themes. */ export default { classic: defaultTheme, paper: {