diff --git a/docs.css b/docs.css index 06e0980..2f3c79f 100644 --- a/docs.css +++ b/docs.css @@ -1,5 +1,63 @@ -:root { - --dark-color-background: #222; - --dark-color-background-secondary: #191919; - --color-accent: #444; +@layer typedoc, custom; + +@layer custom { + :root { + --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; + text-rendering: optimizeLegibility; + } + + .tsd-breadcrumb li { + line-height: 1.95; + font-size: 10pt; + font-weight: medium; + } + + .tsd-breadcrumb a { + color: light-dark(#444, #bbb); + text-decoration: none; + padding: 2px 6px; + border-radius: 3px; + background-color: light-dark(#6662, #bbb2); + } + + .tsd-breadcrumb li::after { + content: "/"; + padding: 0 4px; + position: relative; + top: -1px; + + color: #888; + } + + 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; */ + opacity: 0.7; + } + + .tsd-navigation .current { + border-radius: 5px; + } + + .tsd-navigation .current .tsd-kind-icon ~ span { + /* --color-text: #fff; */ + opacity: 1.0; + } } 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/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/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/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/events.d.ts b/shared/events.d.ts index a25dbf4..13ef527 100644 --- a/shared/events.d.ts +++ b/shared/events.d.ts @@ -1,6 +1,5 @@ /** - * @file Defines built-in events from Panorama's events system - * @see https://github.com/StrataSource/pano-typed/ + * @packageDocumentation Defines built-in events from Panorama's events system */ /** Defines built-in panel events from Panorama's events system. */ diff --git a/shared/index.d.ts b/shared/index.d.ts index 52c2b93..8aec882 100644 --- a/shared/index.d.ts +++ b/shared/index.d.ts @@ -1,8 +1,11 @@ /** - * @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). */ +/// /// /// /// @@ -85,11 +88,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/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 new file mode 100644 index 0000000..98af739 --- /dev/null +++ b/shared/primitives.d.ts @@ -0,0 +1,87 @@ +/** + * @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..2f8fd36 100644 --- a/shared/style.d.ts +++ b/shared/style.d.ts @@ -1,6 +1,5 @@ /** - * @file Defines style properties accessible through scripting - * @see https://github.com/StrataSource/pano-typed/ + * @packageDocumentation Defines style properties accessible through scripting */ /** Generic panel styling properties. */ 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,