From 84c5c1e9a349bd75a400e9b6f88378ee4bb0f2cb Mon Sep 17 00:00:00 2001 From: koerismo <56563658+koerismo@users.noreply.github.com> Date: Tue, 3 Dec 2024 21:18:25 -0500 Subject: [PATCH 1/4] feat: Update custom css and layout to improve typedoc output. --- docs.css | 61 +++++++++++++++++++++++++++++++++++++++--- p2ce/achievements.d.ts | 2 +- p2ce/events.d.ts | 8 +++++- p2ce/index.d.ts | 1 - p2ce/weapons.d.ts | 2 -- p2ce/workshop.d.ts | 2 -- shared/apis.d.ts | 1 + shared/index.d.ts | 8 +++--- tsconfig.json | 8 ++++++ typedoc.json | 4 +++ 10 files changed, 82 insertions(+), 15 deletions(-) create mode 100644 tsconfig.json diff --git a/docs.css b/docs.css index 06e0980..4368391 100644 --- a/docs.css +++ b/docs.css @@ -1,5 +1,58 @@ -:root { - --dark-color-background: #222; - --dark-color-background-secondary: #191919; - --color-accent: #444; +@layer typedoc, custom; + +@layer custom { + :root { + --dark-color-background: #222; + --dark-color-background-secondary: #191919; + --color-accent: #444; + /* --color-link: #ff6861; */ + --color-active-menu-item: #fff2; + + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; + text-rendering: optimizeLegibility; + } + + .tsd-breadcrumb li { + line-height: 1.95; + font-size: 10pt; + } + + .tsd-breadcrumb a { + color: #ff5b56; + text-decoration: none; + padding: 2px 5px; + border-radius: 3px; + background-color: #f0423c30; + } + + .tsd-breadcrumb li::after { + content: "/"; + padding: 0 4px; + + color: #ff5b56; + } + + g.tsd-no-select rect { + rx: 4px; + } + + g.tsd-no-select text { + transform: translate(-1%, -3%); + font-weight: bold; + fill: #ccc; + font-size: 10pt; + } + + .tsd-navigation .tsd-kind-icon ~ span { + --color-text: #ccc; + } + + .tsd-navigation .current { + border-radius: 5px; + } + + .tsd-navigation .current .tsd-kind-icon ~ span { + --color-text: #fff; + } } diff --git a/p2ce/achievements.d.ts b/p2ce/achievements.d.ts index 4d3a7c2..8b76c03 100644 --- a/p2ce/achievements.d.ts +++ b/p2ce/achievements.d.ts @@ -1,4 +1,4 @@ - +/** Defines the structure of a single achievement. */ interface Achievement { name: string; // Name of the achievement index: number; // Index of the achievement (for use with the API) diff --git a/p2ce/events.d.ts b/p2ce/events.d.ts index de26bfe..8b0e1d2 100644 --- a/p2ce/events.d.ts +++ b/p2ce/events.d.ts @@ -1,5 +1,11 @@ /** - * @file P2:CE-specific event definitions. + * @example Declaring new events + * You can define new event types by redeclaring the GlobalEventNameMap interface with your new events. This is required when using Typescript and `ALLOW_MISSING_EVENTS` is `false`. + * ```js + * interface GlobalEventNameMap { + * MyCustomEvent: (yippee: boolean) => void; + * } + * ``` */ interface GlobalEventNameMap { diff --git a/p2ce/index.d.ts b/p2ce/index.d.ts index 2f9f560..02d3192 100644 --- a/p2ce/index.d.ts +++ b/p2ce/index.d.ts @@ -1,5 +1,4 @@ /** - * @packageDocumentation * P2:CE-specific types. */ diff --git a/p2ce/weapons.d.ts b/p2ce/weapons.d.ts index e3a888c..4b94625 100644 --- a/p2ce/weapons.d.ts +++ b/p2ce/weapons.d.ts @@ -1,6 +1,4 @@ /** - * @packageDocumentation - * P2:CE Weapons API. * @example Select the crowbar if the player has it. * ``` * const crowbar = WeaponsAPI.GetWeaponIndexFromClass("weapon_crowbar"); diff --git a/p2ce/workshop.d.ts b/p2ce/workshop.d.ts index c011f60..7c91db9 100644 --- a/p2ce/workshop.d.ts +++ b/p2ce/workshop.d.ts @@ -1,6 +1,4 @@ /** - * @packageDocumentation - * P2:CE Workshop API. * @example List all subscribed addons' names. * ``` * const addon_count = WorkshopAPI.GetAddonCount(); diff --git a/shared/apis.d.ts b/shared/apis.d.ts index 3ff0637..7003d12 100644 --- a/shared/apis.d.ts +++ b/shared/apis.d.ts @@ -633,6 +633,7 @@ declare namespace UiToolkitAPI { /** Show a popup on 'global popups top level window' that lets you specify a layout and parameters. */ function ShowGlobalCustomLayoutPopupParameters(popupID: string, layoutFile: string, parameters: string): T; + /** Defines a context menu item. Used by various UIToolkitAPI methods. */ interface SimpleContextMenuItem { label: string; jsCallback: () => void; diff --git a/shared/index.d.ts b/shared/index.d.ts index 52c2b93..5b257be 100644 --- a/shared/index.d.ts +++ b/shared/index.d.ts @@ -1,5 +1,5 @@ /** - * @packageDocumentation + * @module shared/primitives * Shared types. */ @@ -85,11 +85,11 @@ declare type JsonObject = { [Key in string]: JsonValue } & { [Key in string]?: J declare type JsonArray = JsonValue[] | readonly JsonValue[]; declare type JsonValue = JsonPrimitive | JsonObject | JsonArray; -/** Encourages IDEs to flatten types when displaying. */ +/** @internal Encourages IDEs to flatten types when displaying. */ declare type Simplify = { [Key in keyof T]: T[Key] } & {}; -/** Make a type incompatible with types that'd otherwise be compatible. */ +/** @internal Make a type incompatible with types that'd otherwise be compatible. */ declare type Brand = Type & { __brand: Brand }; -/** Type to signify flags/bitfield of some enum, ultimately just a `number`. */ +/** @internal Type to signify flags/bitfield of some enum, ultimately just a `number`. */ declare type Flags<_Enum, Underlying = number> = Underlying; diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..1786ffc --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,8 @@ +{ + "compilerOptions": { + "lib": ["ESNext"], + "rootDir": "./", + "noEmit": true + }, + "include": ["p2ce", "shared"] +} \ No newline at end of file diff --git a/typedoc.json b/typedoc.json index a9eb62e..439d287 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,8 +1,10 @@ { "basePath": "./", + "name": "Strata Panorama Types", "entryPoints": ["shared/**/*.d.ts", "p2ce/**/*.d.ts"], "customCss": "docs.css", "searchInComments": true, + "excludeInternal": true, "kindSortOrder": [ "Module", "Namespace", @@ -10,6 +12,8 @@ "Class", "Interface", "Property", + "TypeAlias", + "TypeLiteral" ], "searchGroupBoosts": { "api": 30, From 2db296abb90a28b0905659440de5ceb0e782494a Mon Sep 17 00:00:00 2001 From: koerismo <56563658+koerismo@users.noreply.github.com> Date: Tue, 3 Dec 2024 21:38:36 -0500 Subject: [PATCH 2/4] feat: Fix css for light mode --- docs.css | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs.css b/docs.css index 4368391..fd3e759 100644 --- a/docs.css +++ b/docs.css @@ -5,8 +5,8 @@ --dark-color-background: #222; --dark-color-background-secondary: #191919; --color-accent: #444; - /* --color-link: #ff6861; */ - --color-active-menu-item: #fff2; + --color-link: #ff5b56; + --color-active-menu-item: #aaa3; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; @@ -16,21 +16,24 @@ .tsd-breadcrumb li { line-height: 1.95; font-size: 10pt; + font-weight: medium; } .tsd-breadcrumb a { - color: #ff5b56; + color: light-dark(#444, #bbb); text-decoration: none; - padding: 2px 5px; + padding: 2px 6px; border-radius: 3px; - background-color: #f0423c30; + background-color: light-dark(#6662, #bbb2); } .tsd-breadcrumb li::after { content: "/"; padding: 0 4px; + position: relative; + top: -1px; - color: #ff5b56; + color: #888; } g.tsd-no-select rect { @@ -40,12 +43,13 @@ g.tsd-no-select text { transform: translate(-1%, -3%); font-weight: bold; - fill: #ccc; + /* fill: #ccc; */ font-size: 10pt; } .tsd-navigation .tsd-kind-icon ~ span { - --color-text: #ccc; + /* --color-text: #ccc; */ + opacity: 0.7; } .tsd-navigation .current { @@ -53,6 +57,7 @@ } .tsd-navigation .current .tsd-kind-icon ~ span { - --color-text: #fff; + /* --color-text: #fff; */ + opacity: 1.0; } } From 599d2a5308058e640d1f7e032a278e59ac7fc3a2 Mon Sep 17 00:00:00 2001 From: koerismo <56563658+koerismo@users.noreply.github.com> Date: Tue, 3 Dec 2024 22:15:22 -0500 Subject: [PATCH 3/4] feat: Separate primitives --- docs.css | 10 ++--- p2ce/index.d.ts | 1 + shared/events.d.ts | 2 +- shared/index.d.ts | 6 +-- shared/primitives.d.ts | 85 ++++++++++++++++++++++++++++++++++++++++++ shared/style.d.ts | 2 +- 6 files changed, 95 insertions(+), 11 deletions(-) create mode 100644 shared/primitives.d.ts diff --git a/docs.css b/docs.css index fd3e759..2f3c79f 100644 --- a/docs.css +++ b/docs.css @@ -2,11 +2,11 @@ @layer custom { :root { - --dark-color-background: #222; - --dark-color-background-secondary: #191919; - --color-accent: #444; - --color-link: #ff5b56; - --color-active-menu-item: #aaa3; + --dark-color-background: #222 !important; + --dark-color-background-secondary: #191919 !important; + --color-accent: #444 !important; + --color-link: #ff5b56 !important; + --color-active-menu-item: #aaa3 !important; -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; diff --git a/p2ce/index.d.ts b/p2ce/index.d.ts index 02d3192..2f9f560 100644 --- a/p2ce/index.d.ts +++ b/p2ce/index.d.ts @@ -1,4 +1,5 @@ /** + * @packageDocumentation * P2:CE-specific types. */ diff --git a/shared/events.d.ts b/shared/events.d.ts index a25dbf4..6cef3dc 100644 --- a/shared/events.d.ts +++ b/shared/events.d.ts @@ -1,5 +1,5 @@ /** - * @file Defines built-in events from Panorama's events system + * @packageDocumentation Defines built-in events from Panorama's events system * @see https://github.com/StrataSource/pano-typed/ */ diff --git a/shared/index.d.ts b/shared/index.d.ts index 5b257be..2d2942a 100644 --- a/shared/index.d.ts +++ b/shared/index.d.ts @@ -1,8 +1,6 @@ -/** - * @module shared/primitives - * Shared types. - */ +/** @packageDocumentation Shared types. */ +/// /// /// /// diff --git a/shared/primitives.d.ts b/shared/primitives.d.ts new file mode 100644 index 0000000..0c021bc --- /dev/null +++ b/shared/primitives.d.ts @@ -0,0 +1,85 @@ +/** @packageDocumentation Simple primitive types, separated to keep documentation clean. */ + +declare type float = number; +declare type double = number; + +declare type uint8 = number; +declare type uint16 = number; +declare type uint32 = number; + +declare type int8 = number; +declare type int16 = number; +declare type int32 = number; + +/** + * A STRING representing an int64. + * + * JavaScript `number`s are IEEE floats and lose precision when used for values greater than 2^53. Most of Panorama was + * implemented before native JS BigInts were a thing, and not worth the refactoring work to use them. + * + * In C++, when a C++ method/events exposed to JS have a int64/uint64 param, either a number or string can be passed + * from JS, and both will be converted to the corresponding 64-bit integer. If precision is a concern (e.g. SteamIDs), + * use a string. + * + * For methods/events that *return* a int64/uint64, Panorama will return a JS string! + * + * To be super explicit this, we have separate type aliases for both numbers and strings. When typing C++ methods, + * those taking int64 params in C++ should have TS params with type `int64_str | int64_num`, whilst methods returning + * `int64`s from C++ should return only `int64_str` in TS. + */ +declare type int64_str = string; + +/** @see {int64_str} */ +declare type int64_num = number; + +/** @see {int64_str} */ +declare type uint64_str = string; + +/** @see {int64_str} */ +declare type uint64_num = number; + +/** + * String of a SteamID64. Might look like a uint64 in C++ but it's always a string in JS! + * @see {int64_str} + */ +declare type steamID = string; + +declare type vec2 = { x: number; y: number }; +declare type vec3 = { x: number; y: number; z: number }; + +/** A duration in seconds. */ +declare type duration = number; + +/** Represents a unique id return. */ +declare type uuid = int32; + +/** Represents a keyframes animation return. */ +declare type Keyframes = unknown; + +/** rgba, hex etc. color string */ +declare type color = string; + +/** rgba color string */ +declare type rgbaColor = string; + +// ======== Utility Types ======== +// Many of these are from https://github.com/sindresorhus/type-fest +// We'd rather avoid the dependency, but feel free to pinch stuff from there. + +declare type Func = (...args: Args) => Return; +declare type ValueOf = T[keyof T]; +declare type Primitive = null | undefined | string | number | boolean | symbol | bigint; + +declare type JsonPrimitive = string | number | boolean | null; +declare type JsonObject = { [Key in string]: JsonValue } & { [Key in string]?: JsonValue | undefined }; +declare type JsonArray = JsonValue[] | readonly JsonValue[]; +declare type JsonValue = JsonPrimitive | JsonObject | JsonArray; + +/** @internal Encourages IDEs to flatten types when displaying. */ +declare type Simplify = { [Key in keyof T]: T[Key] } & {}; + +/** @internal Make a type incompatible with types that'd otherwise be compatible. */ +declare type Brand = Type & { __brand: Brand }; + +/** @internal Type to signify flags/bitfield of some enum, ultimately just a `number`. */ +declare type Flags<_Enum, Underlying = number> = Underlying; diff --git a/shared/style.d.ts b/shared/style.d.ts index 716a74b..0ba7c92 100644 --- a/shared/style.d.ts +++ b/shared/style.d.ts @@ -1,5 +1,5 @@ /** - * @file Defines style properties accessible through scripting + * @packageDocumentation Defines style properties accessible through scripting * @see https://github.com/StrataSource/pano-typed/ */ From 53faf23cf8af89bc9138fa9a83edc206a4e06df2 Mon Sep 17 00:00:00 2001 From: koerismo <56563658+koerismo@users.noreply.github.com> Date: Tue, 3 Dec 2024 22:33:24 -0500 Subject: [PATCH 4/4] feat: Fix package.json, shared module headers --- package.json | 5 ++++- shared/events.d.ts | 1 - shared/index.d.ts | 7 ++++++- shared/panels.d.ts | 20 ++++++++++++++++---- shared/primitives.d.ts | 4 +++- shared/style.d.ts | 1 - 6 files changed, 29 insertions(+), 9 deletions(-) diff --git a/package.json b/package.json index 02f88de..10439f0 100644 --- a/package.json +++ b/package.json @@ -3,5 +3,8 @@ "version": "1.0.0", "description": "Near-full coverage of Panorama's APIs and data structures with Typescript definitions.", "author": "Koerismo", - "license": "MIT" + "license": "MIT", + "devDependencies": { + "typedoc": "^0.26.11" + } } diff --git a/shared/events.d.ts b/shared/events.d.ts index 6cef3dc..13ef527 100644 --- a/shared/events.d.ts +++ b/shared/events.d.ts @@ -1,6 +1,5 @@ /** * @packageDocumentation Defines built-in events from Panorama's events system - * @see https://github.com/StrataSource/pano-typed/ */ /** Defines built-in panel events from Panorama's events system. */ diff --git a/shared/index.d.ts b/shared/index.d.ts index 2d2942a..8aec882 100644 --- a/shared/index.d.ts +++ b/shared/index.d.ts @@ -1,4 +1,9 @@ -/** @packageDocumentation Shared types. */ +/** + * @packageDocumentation Shared types, present in all Strata games. + * See the {@link shared/apis | APIs module} for a full list of APIs. + * + * For more information, see the [official documentation](https://wiki.stratasource.org/shared/panorama/overview). + */ /// /// diff --git a/shared/panels.d.ts b/shared/panels.d.ts index 5c808c4..01953fc 100644 --- a/shared/panels.d.ts +++ b/shared/panels.d.ts @@ -245,13 +245,25 @@ declare interface AbstractPanel { SetAttributeUInt32(attribute: string, value: uint32): void; - SetDialogVariable(arg0: string, arg1: string): void; + /** Sets a dialog variable for the Panel. + * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables) + */ + SetDialogVariable(variable: string, value: string): void; - SetDialogVariableFloat(arg0: string, arg1: float): void; + /** Sets a float dialog variable for the Panel. + * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables) + */ + SetDialogVariableFloat(variable: string, value: float): void; - SetDialogVariableInt(arg0: string, arg1: int32): void; + /** Sets an integer dialog variable for the Panel. + * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables) + */ + SetDialogVariableInt(variable: string, value: int32): void; - SetDialogVariableTime(arg0: string, arg1: int64_num | int64_str): void; + /** Sets a time dialog variable for the Panel. + * @see [Dialog variables documentation](https://wiki.stratasource.org/shared/panorama/overview/dialog-variables) + */ + SetDialogVariableTime(variable: string, value: int64_num | int64_str): void; SetDisableFocusOnMouseDown(istrue: boolean): void; diff --git a/shared/primitives.d.ts b/shared/primitives.d.ts index 0c021bc..98af739 100644 --- a/shared/primitives.d.ts +++ b/shared/primitives.d.ts @@ -1,4 +1,6 @@ -/** @packageDocumentation Simple primitive types, separated to keep documentation clean. */ +/** + * @packageDocumentation Simple primitive types, separated to keep documentation clean. + */ declare type float = number; declare type double = number; diff --git a/shared/style.d.ts b/shared/style.d.ts index 0ba7c92..2f8fd36 100644 --- a/shared/style.d.ts +++ b/shared/style.d.ts @@ -1,6 +1,5 @@ /** * @packageDocumentation Defines style properties accessible through scripting - * @see https://github.com/StrataSource/pano-typed/ */ /** Generic panel styling properties. */